@cratis/chronicle 6.33.0 → 6.35.0

package/for_ChronicleClient/when_registering_artifacts/with_invalid_handler_mappings.spec.ts

@@ -0,0 +1,142 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
+import { ChronicleClient } from '../../ChronicleClient.js';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../artifacts/IClientArtifactsProvider.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles } from '../../events/handles.js';
+import { reactor, replay } from '../../reactors/index.js';
+import { reducer } from '../../reducers/index.js';
+
+chai.should();
+
+const transport = vi.hoisted(() => ({
+    ensureEventStore: vi.fn(),
+    register: vi.fn(),
+    observe: vi.fn()
+}));
+
+vi.mock('../../connection/ChronicleConnection', () => ({
+    ChronicleConnection: class {
+        async resetChannel() {}
+        async connect() {}
+        disconnect() {}
+        server = { getVersionInfo: async () => ({}) };
+        eventStores = { ensureEventStore: transport.ensureEventStore };
+        eventTypes = new Proxy({}, { get: () => transport.register });
+        constraints = new Proxy({}, { get: () => transport.register });
+        projections = new Proxy({}, { get: () => transport.register });
+        readModels = new Proxy({}, { get: () => transport.register });
+        webhooks = new Proxy({}, { get: () => transport.register });
+        eventSeeding = new Proxy({}, { get: () => transport.register });
+        reactors = { observe: transport.observe };
+        reducers = { observe: transport.observe };
+    }
+}));
+vi.mock('../../connection/KernelKeepAlive', () => ({
+    KernelKeepAlive: class { async start() {} }
+}));
+
+@eventType('preflight-author')
+class AuthorRegistered {}
+@eventType('preflight-missing')
+class Unregistered {}
+
+@reactor('valid-reactor')
+class ValidReactor { @handles(AuthorRegistered) notify() {} }
+@reducer('valid-reducer')
+class ValidReducer { @handles(AuthorRegistered) update() {} }
+
+@reactor('missing-event')
+class MissingReactor { @handles(Unregistered) notify() {} }
+@reactor('duplicate-event')
+class DuplicateReactor {
+    @handles(AuthorRegistered) notify() {}
+    authorRegistered() {}
+}
+@reactor('ambiguous-replay')
+class AmbiguousReactor { @replay(AuthorRegistered) @handles(AuthorRegistered) notify() {} }
+
+@reducer('missing-event')
+class MissingReducer { @handles(Unregistered) update() {} }
+@reducer('duplicate-event')
+class DuplicateReducer {
+    @handles(AuthorRegistered) update() {}
+    authorRegistered() {}
+}
+
+for (const [kind, type, message] of [
+    ['reactor', MissingReactor, /notify.*MissingReactor.*Unregistered.*no registered event type/],
+    ['reactor', DuplicateReactor, /multiple handlers.*preflight-author.*notify.*authorRegistered/],
+    ['reactor', AmbiguousReactor, /notify.*AmbiguousReactor.*cannot combine @handles and @replay/],
+    ['reducer', MissingReducer, /update.*MissingReducer.*Unregistered.*no registered event type/],
+    ['reducer', DuplicateReducer, /multiple handlers.*preflight-author.*update.*authorRegistered/]
+] as const) {
+    describe(`when getting an event store with invalid mappings on ${type.name}`, () => {
+        let client: ChronicleClient;
+        let artifacts: IClientArtifactsProvider;
+        let result: PromiseSettledResult<unknown>;
+        let disconnectedSubscriptions: Set<unknown>;
+        let clientSubscriptionCount: number;
+        beforeEach(async () => {
+            vi.clearAllMocks();
+            disconnectedSubscriptions = new Set();
+            const onDisconnected = ConnectionLifecycle.prototype.onDisconnected;
+            vi.spyOn(ConnectionLifecycle.prototype, 'onDisconnected').mockImplementation(function (this: ConnectionLifecycle, handler) {
+                disconnectedSubscriptions.add(handler);
+                const unsubscribe = onDisconnected.call(this, handler);
+                return () => { unsubscribe(); disconnectedSubscriptions.delete(handler); };
+            });
+            transport.ensureEventStore.mockResolvedValue({ IsAuthorized: true });
+            transport.register.mockResolvedValue({});
+            transport.observe.mockImplementation(async function* () {
+                yield { Events: [], Partition: '', ReplayState: 0, InitialState: '' };
+            });
+            artifacts = {
+                reactors: kind === 'reactor' ? [ValidReactor, type] : [ValidReactor],
+                reducers: kind === 'reducer' ? [ValidReducer, type] : [ValidReducer],
+                eventTypes: [AuthorRegistered], readModels: [], projections: [], constraints: [],
+                webhooks: [], seeders: [], eventTypeMigrations: [], globalForHandlers: []
+            };
+            client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', {
+                discoveryPatterns: [], clientArtifactsProvider: artifacts
+            }));
+            clientSubscriptionCount = disconnectedSubscriptions.size;
+            [result] = await Promise.allSettled([client.getEventStore('store')]);
+        });
+        afterEach(() => { client.dispose(); vi.restoreAllMocks(); });
+
+        it('should reject getEventStore with the handler validation error', () => {
+            result.status.should.equal('rejected');
+            if (result.status === 'rejected') (result.reason as Error).message.should.match(message);
+        });
+        it('should leave no discarded-store lifecycle subscriptions after either failed retrieval', async () => {
+            disconnectedSubscriptions.size.should.equal(clientSubscriptionCount);
+            await Promise.allSettled([client.getEventStore('store')]);
+            disconnectedSubscriptions.size.should.equal(clientSubscriptionCount);
+        });
+        it('should not register any artifacts or begin observations', () => {
+            transport.register.mock.calls.should.have.lengthOf(0);
+            transport.observe.mock.calls.should.have.lengthOf(0);
+        });
+        it('should reject a second retrieval instead of returning the failed store', async () => {
+            const [retry] = await Promise.allSettled([client.getEventStore('store')]);
+            retry.status.should.equal('rejected');
+            if (retry.status === 'rejected') (retry.reason as Error).message.should.match(message);
+            transport.register.mock.calls.should.have.lengthOf(0);
+            transport.observe.mock.calls.should.have.lengthOf(0);
+        });
+        it('should register a fresh store after the invalid mapping is removed and cache only that store', async () => {
+            artifacts.reactors.splice(1);
+            artifacts.reducers.splice(1);
+            const store = await client.getEventStore('store');
+            transport.register.mock.calls.length.should.be.greaterThan(0);
+            transport.observe.mock.calls.should.have.lengthOf(2);
+            (await client.getEventStore('store')).should.equal(store);
+            transport.ensureEventStore.mock.calls.should.have.lengthOf(2);
+        });
+    });
+}

package/for_ChronicleClient/when_starting_background_work/with_a_correlated_caller.spec.ts

@@ -0,0 +1,150 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { context, propagation, trace } from '@opentelemetry/api';
+import { createServer, ServerError, Status, type ServiceImplementation } from 'nice-grpc';
+import { Metadata } from 'nice-grpc-common';
+import { ConnectionServiceDefinition, EventStoresDefinition, ServerDefinition, ReactorsDefinition, ReducersDefinition, ReadModelsDefinition } from '@cratis/chronicle.contracts';
+import { ChronicleClient } from '../../ChronicleClient.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../artifacts/IClientArtifactsProvider.js';
+import { CorrelationId, correlationIdManager } from '../../correlation/index.js';
+import type { ChronicleLogEntry } from '../../logging/ChronicleLogEntry.js';
+import { reactor } from '../../reactors/reactor.js';
+import { reducer } from '../../reducers/reducer.js';
+import { telemetrySession } from '../../telemetry/for_ChronicleTelemetry/given/a_telemetry_session.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+class BackgroundReactor {}
+reactor('background-reactor')(BackgroundReactor);
+class BackgroundReducer {}
+reducer('background-reducer')(BackgroundReducer);
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [], readModels: [], reactors: [BackgroundReactor], reducers: [BackgroundReducer],
+    seeders: [], constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+let server: ReturnType<typeof createServer>;
+let client: ChronicleClient;
+let received: { method: string; metadata: Metadata }[];
+let logs: ChronicleLogEntry[];
+let hostTraceId: string;
+const correlation = new CorrelationId('a4450131-7cd4-40ba-9438-69c680efc1f3');
+
+function deferred() {
+    let resolve!: () => void;
+    const promise = new Promise<void>(complete => { resolve = complete; });
+    return { promise, resolve };
+}
+
+beforeEach(async () => {
+    received = [];
+    logs = [];
+    const reobserved = deferred();
+    const reconnected = deferred();
+    const endKeepAlive = deferred();
+    const counts = new Map<string, number>();
+    server = createServer().use(async function* (call, callContext) {
+        const method = call.method.path;
+        received.push({ method, metadata: Metadata(callContext.metadata) });
+        const count = (counts.get(method) ?? 0) + 1;
+        counts.set(method, count);
+        const observations = [...counts].filter(([path]) => path.endsWith('/Observe'));
+        if (observations.length === 2 && observations.every(([, total]) => total >= 2)) reobserved.resolve();
+        if (observations.length === 2 && observations.every(([, total]) => total >= 3)) reconnected.resolve();
+        return yield* call.next(call.request, callContext);
+    });
+    const unused = async () => { throw new Error('Unexpected RPC'); };
+    const success = async () => ({ IsAuthorized: true, ValidationResults: [], ExceptionMessages: [] });
+    let connections = 0;
+    server.add(ConnectionServiceDefinition, {
+        ...Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unused])),
+        checkCompatibility: async () => ({ IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' }),
+        connectionKeepAlive: async () => ({}),
+        connect: async function* (request, callContext) {
+            const first = ++connections === 1;
+            yield { ConnectionId: request.ConnectionId };
+            if (first) await endKeepAlive.promise;
+            else await new Promise<void>(resolve => callContext.signal.addEventListener('abort', () => resolve(), { once: true }));
+        }
+    } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+    server.add(ServerDefinition, {
+        ...Object.fromEntries(Object.keys(ServerDefinition.methods).map(name => [name, unused])),
+        getVersionInfo: async () => ({})
+    } as ServiceImplementation<typeof ServerDefinition>);
+    server.add(EventStoresDefinition, {
+        allEventStores: unused, ensureEventStore: success, observeEventStores: unused
+    } as ServiceImplementation<typeof EventStoresDefinition>);
+    server.add(ReadModelsDefinition, {
+        ...Object.fromEntries(Object.keys(ReadModelsDefinition.methods).map(name => [name, unused])),
+        registerMany: success
+    } as ServiceImplementation<typeof ReadModelsDefinition>);
+    server.add(ReactorsDefinition, {
+        ...Object.fromEntries(Object.keys(ReactorsDefinition.methods).map(name => [name, unused])),
+        observe: async function* (requests) {
+            for await (const _request of requests) {
+                yield { Events: [], Partition: '', ReplayState: 0 };
+                throw new ServerError(Status.UNAVAILABLE, 'End stream to exercise re-observation');
+            }
+        }
+    } as ServiceImplementation<typeof ReactorsDefinition>);
+    server.add(ReducersDefinition, {
+        ...Object.fromEntries(Object.keys(ReducersDefinition.methods).map(name => [name, unused])),
+        observe: async function* (requests) {
+            for await (const _request of requests) {
+                yield { Events: [], Partition: '', ReplayState: 0 };
+                throw new ServerError(Status.UNAVAILABLE, 'End stream to exercise re-observation');
+            }
+        }
+    } as ServiceImplementation<typeof ReducersDefinition>);
+    const port = await server.listen('127.0.0.1:0');
+    const span = telemetry.traces.getTracer('host').startSpan('host');
+    hostTraceId = span.spanContext().traceId;
+    const active = propagation.setBaggage(trace.setSpan(context.active(), span), propagation.createBaggage({
+        'cratis.correlation_id': { value: correlation.toString() }, email: { value: 'private@example.com' }
+    }));
+    try {
+        await context.with(active, () => correlationIdManager.run(correlation, async () => {
+            client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://127.0.0.1:${port}?disableTls=true&apiKey=test`, {
+                discoveryPatterns: [], clientArtifactsProvider: artifacts, logger: { log: entry => logs.push(entry) }
+            }));
+            await client.getEventStore('store');
+            context.active().should.equal(active);
+            correlationIdManager.scoped!.should.equal(correlation);
+        }));
+        await reobserved.promise;
+        endKeepAlive.resolve();
+        await reconnected.promise;
+    } finally { span.end(); endKeepAlive.resolve(); }
+});
+
+afterEach(async () => {
+    client?.dispose();
+    await server?.shutdown();
+});
+
+describe('when a correlated getEventStore starts background streams and their recovery loops', () => {
+    it('should not propagate the caller trace or baggage on observations or keep-alive RPCs', () => {
+        const background = received.filter(({ method }) => /\/(Observe|Connect|ConnectionKeepAlive)$/.test(method));
+        background.length.should.be.greaterThanOrEqual(10);
+        for (const { metadata } of background) {
+            should.equal(metadata.get('traceparent'), undefined);
+            should.equal(metadata.get('baggage'), undefined);
+        }
+    });
+    it('should retain the caller context on the foreground operation', () => {
+        const foreground = received.find(({ method }) => method.endsWith('/EnsureEventStore'))!;
+        foreground.metadata.get('traceparent')!.should.contain(hostTraceId);
+        should.equal(foreground.metadata.get('baggage'), `cratis.correlation_id=${correlation}`);
+    });
+    it('should not label background-loop diagnostics with the initiating business correlation or trace', () => {
+        const background = logs.filter(entry => /observation|keep-alive|Reconnect/.test(entry.message));
+        background.length.should.be.greaterThan(0);
+        for (const entry of background) {
+            entry.attributes.should.not.have.property('cratis.correlation_id');
+            entry.attributes.should.not.have.property('trace_id');
+            entry.attributes.should.not.have.property('span_id');
+        }
+    });
+});

package/for_ChronicleOptions/when_configuring_telemetry/with_event_source_identifiers.spec.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { runInNewContext } from 'node:vm';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { ChronicleTelemetryOptions } from '../../telemetry/ChronicleTelemetryOptions.js';
+
+chai.should();
+
+for (const policy of [
+    { mode: 'unknown' }, {}, null,
+    { mode: 'hmac' }, { mode: 'hmac', key: '' }, { mode: 'hmac', key: 'secret' },
+    { mode: 'hmac', key: [] }, { mode: 'hmac', key: new Uint8Array() },
+    { mode: 'hmac', key: Buffer.alloc(0) }, { mode: 'hmac', key: new Uint16Array([1]) },
+    { mode: 'hmac', key: new DataView(new ArrayBuffer(1)) },
+    { mode: 'hmac', key: runInNewContext('new Uint8Array()') },
+    { mode: 'hmac', key: runInNewContext('new Uint16Array([1])') }
+]) {
+    describe(`when configuring event source privacy with ${JSON.stringify(policy)}`, () => {
+        it('should reject invalid telemetry configuration before a client can make business calls', () => {
+            const telemetry = { eventSourceId: policy } as unknown as ChronicleTelemetryOptions;
+            (() => ChronicleOptions.development({ telemetry })).should.throw(TypeError);
+            (() => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry })).should.throw(TypeError);
+        });
+    });
+}
+
+describe('when configuring an HMAC key created in another realm', () => {
+    it('should accept a non-empty byte array without relying on its realm constructor', () => {
+        const key = runInNewContext('new Uint8Array([1, 2, 3])') as Uint8Array;
+        (key instanceof Uint8Array).should.be.false;
+        (() => ChronicleOptions.development({ telemetry: { eventSourceId: { mode: 'hmac', key } } })).should.not.throw();
+        (() => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry: { eventSourceId: { mode: 'hmac', key } } })).should.not.throw();
+    });
+});
+
+for (const eventSourceId of [undefined, { mode: 'raw' }, { mode: 'hmac', key: new Uint8Array([1]) }, { mode: 'hmac', key: Buffer.from('key') }] as const) {
+    describe('when configuring a supported event source privacy policy', () => {
+        it('should accept omitted identifiers, raw identifiers and non-empty byte keys', () => {
+            (() => ChronicleOptions.development({ telemetry: { eventSourceId } })).should.not.throw();
+        });
+    });
+}

package/index.ts

@@ -37,7 +37,13 @@ export { EventStoreNamespaceName } from './EventStoreNamespaceName.js';
 export { Guid } from '@cratis/fundamentals';
 export { ReplayState } from '@cratis/chronicle.contracts';
 export { ChronicleInstrumentationName, ChronicleTracer } from './Tracing.js';
-export { ChronicleMeter, ChronicleMeterName, ChronicleMetrics } from './Metrics.js';
+export { ChronicleMeter, ChronicleMeterName, ChronicleMetrics, ChronicleConventionMetrics } from './Metrics.js';
+export { WellKnownTelemetryNames } from './WellKnownTelemetryNames.js';
+export type { ChronicleTelemetryOptions } from './telemetry/ChronicleTelemetryOptions.js';
+export type { IChronicleLogger } from './logging/IChronicleLogger.js';
+export type { ChronicleLogEntry } from './logging/ChronicleLogEntry.js';
+export { ChronicleLogLevel } from './logging/ChronicleLogLevel.js';
+export { DiagChronicleLogger } from './logging/DiagChronicleLogger.js';
 
 export * from './events/index.js';
 export * from './eventSequences/index.js';

package/logging/ChronicleLogEntry.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Attributes } from '@opentelemetry/api';
+import type { ChronicleLogLevel } from './ChronicleLogLevel.js';
+
+/** Structured diagnostic without event payloads, error messages or error stacks. */
+export interface ChronicleLogEntry {
+    readonly category: string;
+    readonly level: ChronicleLogLevel;
+    readonly message: string;
+    /** Safe diagnostic fields, including correlation and valid trace/span identifiers when available. */
+    readonly attributes: Readonly<Attributes>;
+}

package/logging/ChronicleLogLevel.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Severity of a Chronicle diagnostic. */
+export enum ChronicleLogLevel {
+    Verbose = 'verbose',
+    Debug = 'debug',
+    Info = 'info',
+    Warn = 'warn',
+    Error = 'error'
+}

package/logging/DiagChronicleLogger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { diag } from '@opentelemetry/api';
+import type { IChronicleLogger } from './IChronicleLogger.js';
+import type { ChronicleLogEntry } from './ChronicleLogEntry.js';
+
+/** Compatibility adapter used when no application logger is supplied during the minor-release overlap. */
+export class DiagChronicleLogger implements IChronicleLogger {
+    log(entry: ChronicleLogEntry): void {
+        diag.createComponentLogger({ namespace: entry.category })[entry.level](entry.message, entry.attributes);
+    }
+}

package/logging/IChronicleLogger.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 type { ChronicleLogEntry } from './ChronicleLogEntry.js';
+
+/** Application-owned diagnostic sink, configured separately for each Chronicle client. */
+export interface IChronicleLogger {
+    /** Receives one sanitized diagnostic. Implementations should not throw. */
+    log(entry: ChronicleLogEntry): void;
+}

package/logging/createLogger.ts

@@ -0,0 +1,50 @@
+// 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, trace, isSpanContextValid, type Attributes } from '@opentelemetry/api';
+import { ClientError, ServerError } from 'nice-grpc-common';
+import { correlationIdManager } from '../correlation/index.js';
+import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.js';
+import { exceptionType } from '../telemetry/spanAttributes.js';
+import { ChronicleLogLevel } from './ChronicleLogLevel.js';
+import { DiagChronicleLogger } from './DiagChronicleLogger.js';
+import type { IChronicleLogger } from './IChronicleLogger.js';
+
+/** Binds a category to a client-owned sink and adds safe correlation fields. */
+export function createLogger(category: string, sink: IChronicleLogger = new DiagChronicleLogger()) {
+    const log = (level: ChronicleLogLevel) => (message: string, fields: Record<string, unknown> = {}) => {
+        const attributes: Attributes = {};
+        for (const [key, value] of Object.entries(fields)) {
+            if (key === 'error') {
+                attributes['error.type'] = exceptionType(value);
+                attributes['exception.type'] = exceptionType(value);
+                if (value instanceof ClientError || value instanceof ServerError) attributes['rpc.grpc.status_code'] = value.code;
+            } else if (key === 'sequenceNumber') {
+                const number = Number(value);
+                if (Number.isSafeInteger(number)) attributes[WellKnownTelemetryNames.attributes.sequenceNumber] = number;
+            } else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                attributes[key] = value;
+            } else if (Array.isArray(value) && value.every(item => typeof item === 'string')) {
+                attributes[key] = value;
+            }
+        }
+        const active = context.active();
+        const correlationKey = WellKnownTelemetryNames.attributes.correlationId;
+        const correlation = correlationIdManager.scoped?.toString() ?? propagation.getBaggage(active)?.getEntry(correlationKey)?.value;
+        if (correlation) attributes[correlationKey] = correlation;
+        const spanContext = trace.getSpanContext(active);
+        if (spanContext && isSpanContextValid(spanContext)) {
+            attributes.trace_id = spanContext.traceId;
+            attributes.span_id = spanContext.spanId;
+        }
+        try {
+            sink.log({ category, level, message, attributes });
+        } catch {
+            // Diagnostics are not the operation's outcome. A broken sink must not change RPCs or acknowledgements.
+        }
+    };
+    return {
+        verbose: log(ChronicleLogLevel.Verbose), debug: log(ChronicleLogLevel.Debug),
+        info: log(ChronicleLogLevel.Info), warn: log(ChronicleLogLevel.Warn), error: log(ChronicleLogLevel.Error)
+    };
+}

package/logging/for_ChronicleLogger/when_logging/with_client_owned_sinks.spec.ts

@@ -0,0 +1,96 @@
+// 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, vi } from 'vitest';
+import { diag, DiagLogLevel } from '@opentelemetry/api';
+import { ClientError, ServerError, Status } from 'nice-grpc-common';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import { createLogger } from '../../createLogger.js';
+import type { ChronicleLogEntry } from '../../ChronicleLogEntry.js';
+import { telemetrySession } from '../../../telemetry/for_ChronicleTelemetry/given/a_telemetry_session.fixture.js';
+import { CorrelationId, correlationIdManager } from '../../../correlation/index.js';
+
+vi.mock('../../../connection/ChronicleConnection.js', () => ({ ChronicleConnection: class { disconnect() {} } }));
+chai.should();
+const telemetry = telemetrySession();
+
+describe('when two clients have different diagnostic sinks', () => {
+    const first: ChronicleLogEntry[] = [];
+    const second: ChronicleLogEntry[] = [];
+    beforeEach(() => {
+        first.length = 0;
+        second.length = 0;
+        const one = new ChronicleClient(ChronicleOptions.development({ discoveryPatterns: [], logger: { log: entry => first.push(entry) } }));
+        const two = new ChronicleClient(ChronicleOptions.development({ discoveryPatterns: [], logger: { log: entry => second.push(entry) } }));
+        one.dispose();
+        two.dispose();
+    });
+    it('should route each diagnostic only to its owning sink', () => {
+        first.should.have.lengthOf(2);
+        second.should.have.lengthOf(2);
+        (first[0] === second[0]).should.be.false;
+    });
+});
+
+describe('when logging in a correlated trace', () => {
+    let entry: ChronicleLogEntry;
+    beforeEach(async () => {
+        const logger = createLogger('test', { log: value => { entry = value; } });
+        await correlationIdManager.run(new CorrelationId('business-id'), () => telemetry.traces.getTracer('host').startActiveSpan('operation', async span => {
+            try { logger.error('Operation failed', { error: new TypeError('secret'), sequenceNumber: 9007199254740992n }); }
+            finally { span.end(); }
+        }));
+    });
+    it('should export error types with business and trace identifiers but no exception details', () => {
+        entry.attributes.should.include({ 'error.type': 'TypeError', 'exception.type': 'TypeError', 'cratis.correlation_id': 'business-id' });
+        entry.attributes.should.have.property('trace_id');
+        entry.attributes.should.have.property('span_id');
+        entry.attributes.should.not.have.property('cratis.event_sequence.number');
+        JSON.stringify(entry).should.not.contain('secret');
+    });
+});
+
+for (const error of [new ClientError('/test', Status.UNAVAILABLE, 'secret'), new ServerError(Status.UNAVAILABLE, 'secret')]) {
+    describe('when logging a gRPC failure', () => {
+        let entry: ChronicleLogEntry;
+        beforeEach(() => {
+            createLogger('test', { log: value => { entry = value; } }).error('Operation failed', { error });
+        });
+        it('should retain the numeric status without exporting sensitive exception details', () => {
+            entry.attributes.should.include({ 'rpc.grpc.status_code': Status.UNAVAILABLE });
+            JSON.stringify(entry).should.not.contain('secret');
+        });
+    });
+}
+
+for (const error of [new DOMException('secret', 'TimeoutError'), new DOMException('secret', 'AbortError'), { code: Status.UNAVAILABLE, message: 'secret' }]) {
+    describe('when logging a non-gRPC error with a numeric code', () => {
+        let entry: ChronicleLogEntry;
+        beforeEach(() => {
+            createLogger('test', { log: value => { entry = value; } }).error('Operation failed', { error });
+        });
+        it('should not label its code as a gRPC status', () => {
+            entry.attributes.should.not.have.property('rpc.grpc.status_code');
+            JSON.stringify(entry).should.not.contain('secret');
+        });
+    });
+}
+
+describe('when no logger is configured during the compatibility period', () => {
+    it('should still deliver sanitized diagnostics to diag', () => {
+        const error = vi.fn();
+        diag.setLogger({ error, warn: vi.fn(), info: vi.fn(), debug: vi.fn(), verbose: vi.fn() }, DiagLogLevel.ERROR);
+        try {
+            createLogger('test').error('Operation failed', { error: new Error('secret') });
+            error.mock.calls.should.have.lengthOf(1);
+            JSON.stringify(error.mock.calls).should.not.contain('secret');
+        } finally { diag.disable(); }
+    });
+});
+
+describe('when a diagnostic sink throws', () => {
+    it('should leave the operation unaffected', () => {
+        (() => createLogger('test', { log: () => { throw new Error('sink failed'); } }).info('Diagnostic')).should.not.throw();
+    });
+});

package/observation/EventHandler.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A registered event type and its selected instance method. */
+export interface EventHandler {
+    readonly id: string;
+    readonly generation: number;
+    readonly methodName: string;
+}

package/observation/createHandlerInstanceValidator.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import { getHandledEventType } from '../events/handles.js';
+import { getInstanceMethods } from './getInstanceMethods.js';
+
+/** Captures @handles prototype methods during preflight and rejects instance properties hiding them, except bound methods. */
+export function createHandlerInstanceValidator(type: Constructor, names: Iterable<string>, methods = getInstanceMethods(type)):
+    (instance: object) => void {
+    const handlers = [...new Set(names)].filter(name => getHandledEventType(methods.get(name)!) !== undefined).map(name => {
+        const method = methods.get(name)!;
+        let declaring = type.prototype;
+        while (declaring && Object.getOwnPropertyDescriptor(declaring, name)?.value !== method) {
+            declaring = Object.getPrototypeOf(declaring);
+        }
+        const eventType = getHandledEventType(method)!;
+        const declaration = `@handles(${(eventType as Function).name})`;
+        return { name, method, declaration, declaringType: declaring?.constructor.name ?? type.name };
+    });
+    return instance => {
+        for (const { name, method, declaration, declaringType } of handlers) {
+            let current: object | null = instance;
+            while (current && !Object.hasOwn(current, name)) current = Object.getPrototypeOf(current) as object | null;
+            const value: unknown = current ? Object.getOwnPropertyDescriptor(current, name)?.value : undefined;
+            if (current === instance && typeof value === 'function' && isBoundCopyOf(value, method)) continue;
+            if (current === instance || !current || value !== method) {
+                throw new Error(`Override '${name}' on '${type.name}' hides ${declaration} declared on '${declaringType}'; use a method with @handles instead of an instance field.`);
+            }
+        }
+    };
+}
+
+/**
+ * Checks whether a function is a (possibly repeatedly) Function.prototype.bind copy of a method.
+ * @param value - The function found on the instance.
+ * @param method - The declared method.
+ * @returns True when the function name is one or more `bound ` prefixes followed by the method name.
+ */
+function isBoundCopyOf(value: Function, method: Function): boolean {
+    return value.name.startsWith('bound ') && value.name.replace(/^(bound )+/, '') === method.name;
+}