@cratis/chronicle 6.32.1 → 6.34.0

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.32.1",
+    "version": "6.34.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -184,6 +184,12 @@
     },
     "devDependencies": {
         "@cratis/fundamentals": "7.20.0",
+        "@opentelemetry/context-async-hooks": "2.11.0",
+        "@opentelemetry/core": "2.11.0",
+        "@opentelemetry/instrumentation-grpc": "0.222.0",
+        "@opentelemetry/instrumentation-http": "0.222.0",
+        "@opentelemetry/sdk-metrics": "2.11.0",
+        "@opentelemetry/sdk-trace-base": "2.11.0",
         "@types/node": "^26.6.3",
         "@typescript/native": "npm:typescript@^7.0.2",
         "esbuild": "^0.28.2",

package/projections/Projections.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 { ProjectionOwner, type ProjectionDefinition } from '@cratis/chronicle.contracts';
 import { Constructor, Guid } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -36,7 +36,7 @@ export class Projections implements IProjections {
     private readonly _modelBound = new Map<string, Constructor>();
     private readonly _failedPartitions: FailedPartitions;
 
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/projections' });
+    private readonly _logger: ReturnType<typeof createLogger>;
 
     /**
      * Creates a new {@link Projections} instance.
@@ -55,6 +55,7 @@ export class Projections implements IProjections {
         private readonly _defaultSinkTypeId: string,
         private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
     ) {
+        this._logger = createLogger('@cratis/chronicle/projections', _connection.logger);
         this._failedPartitions = new FailedPartitions(_eventStore, _namespace, _connection);
     }
 
@@ -296,7 +297,7 @@ export class Projections implements IProjections {
                     identifier,
                     attempt,
                     nextAttemptInMs: delay,
-                    error: msg
+                    error
                 });
                 await new Promise(resolve => setTimeout(resolve, delay));
                 delay = Math.min(delay * 2, 15000);

package/reactors/Reactors.ts

@@ -2,7 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { diag } from '@opentelemetry/api';
+import { createLogger } from '../logging/createLogger.js';
+import { runInBackgroundContext } from '../telemetry/runInBackgroundContext.js';
 import { Constructor } from '@cratis/fundamentals';
 import { ObservationState, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -102,7 +103,7 @@ export class Reactors implements IReactors {
     /** How long to wait before re-establishing an observation whose stream ended. */
     private static readonly _reobserveDelayMs = 2000;
 
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/reactors' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _lifecycle: ConnectionLifecycle;
     private readonly _reactors = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReactorMessage>>();
@@ -130,6 +131,7 @@ export class Reactors implements IReactors {
         private readonly _eventStore?: IEventStore,
         private readonly _artifactActivator?: ClientArtifactsActivator
     ) {
+        this._logger = createLogger('@cratis/chronicle/reactors', _connection.logger);
         this._lifecycle = lifecycle;
         lifecycle.onDisconnected(async () => {
             this._logger.info('Disconnected — stopping all reactor observations');
@@ -177,19 +179,21 @@ export class Reactors implements IReactors {
     }
 
     private startObservation(id: string, reactorType: Constructor): void {
-        if (this._disposed) return;
-        const metadata = getReactorMetadata(reactorType)!;
-        const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
-
-        this._logger.info('Starting reactor observation', {
-            reactorId: id,
-            eventSequenceId,
-            handlerCount: eventTypes.length,
-            handlers: eventTypes.map(e => e.methodName)
+        runInBackgroundContext(() => {
+            if (this._disposed) return;
+            const metadata = getReactorMetadata(reactorType)!;
+            const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
+            const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
+
+            this._logger.info('Starting reactor observation', {
+                reactorId: id,
+                eventSequenceId,
+                handlerCount: eventTypes.length,
+                handlers: eventTypes.map(e => e.methodName)
+            });
+
+            void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
         });
-
-        void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
     }
 
     private async runObservation(
@@ -201,7 +205,7 @@ export class Reactors implements IReactors {
         try {
             await this.observeReactor(id, reactorType, eventSequenceId, eventTypes);
         } catch (error) {
-            this._logger.error('Reactor observation loop exited with error', { reactorId: id, error: String(error) });
+            this._logger.error('Reactor observation loop exited with error', { reactorId: id, error });
         }
 
         this.scheduleReobserve(id, reactorType);
@@ -223,14 +227,14 @@ export class Reactors implements IReactors {
             return;
         }
 
-        const handle = setTimeout(() => {
+        const handle = runInBackgroundContext(() => setTimeout(() => {
             if (!this._registered || this._disposed) {
                 return;
             }
 
             this._logger.info('Re-establishing reactor observation', { reactorId: id });
             this.startObservation(id, reactorType);
-        }, Reactors._reobserveDelayMs);
+        }, Reactors._reobserveDelayMs));
 
         handle.unref?.();
     }
@@ -286,7 +290,6 @@ export class Reactors implements IReactors {
 
                 this._logger.debug('Received events to observe', {
                     reactorId: id,
-                    partition: eventsToObserve.Partition,
                     count: eventsToObserve.Events.length,
                     replayState: eventsToObserve.ReplayState
                 });
@@ -301,12 +304,12 @@ export class Reactors implements IReactors {
                             replayState: eventsToObserve.ReplayState
                         }, this._artifactActivator, artifact => runActivated(artifact, () =>
                             notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition),
-                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }));
+                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }), this._connection.logger);
                     } else if (reactorInstance) {
                         await notifyReplayLifecycle(reactorInstance, eventsToObserve.ReplayState, eventsToObserve.Partition);
                     }
                 } catch (err) {
-                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: String(err) });
+                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: err });
                     if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
                         exceptionMessages.push(String(err.processingError));
                     }
@@ -348,7 +351,6 @@ export class Reactors implements IReactors {
                             }
 
                             const content = JSON.parse(event.Content) as Record<string, unknown>;
-                            this._logger.debug('Event content', { reactorId: id, eventTypeId, contentKeys: Object.keys(content), rawContent: event.Content.substring(0, 200) });
                             const context = toClientEventContext(event.Context!);
 
                             this._logger.info('Invoking reactor handler', {
@@ -364,7 +366,7 @@ export class Reactors implements IReactors {
 
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
-                            this._logger.error('Error handling event in reactor', { reactorId: id, error: String(err) });
+                            this._logger.error('Error handling event in reactor', { reactorId: id, error: err });
                             exceptionMessages.push(String(err));
                             exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                             state = ObservationState.Failed;
@@ -386,9 +388,9 @@ export class Reactors implements IReactors {
                             readModels: services.readModels, eventSequenceId, partition: eventsToObserve.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.Events,
                             eventContext: toClientEventContext(firstInvocableEvent.Context!)
-                        }, this._artifactActivator, processEvents);
+                        }, this._artifactActivator, processEvents, this._connection.logger);
                     } catch (err) {
-                        this._logger.error('Error activating reactor', { reactorId: id, error: String(err) });
+                        this._logger.error('Error activating reactor', { reactorId: id, error: err });
                         exceptionMessages.push(String(err));
                         const completionStack = err instanceof Error ? (err.stack ?? '') : '';
                         exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
@@ -419,7 +421,7 @@ export class Reactors implements IReactors {
             if (!this._queues.has(id)) {
                 this._logger.debug('Reactor observation stream closed cleanly', { reactorId: id });
             } else {
-                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: String(err) });
+                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: err });
             }
         } finally {
             // Only retire our own queue: a reconnect can already have replaced it,

package/reactors/for_Reactors/when_delivering/with_activation.spec.ts

@@ -4,7 +4,8 @@
 import { EventContext as WireContext, EventObservationState, EventType, ObservationState, type ReactorMessage } from '@cratis/chronicle.contracts';
 import { ReplayState } from '../../../index.js';
 import { chai, describe, it, vi } from 'vitest';
-import { diag, DiagLogLevel, type DiagLogger } from '@opentelemetry/api';
+import type { IChronicleLogger } from '../../../logging/IChronicleLogger.js';
+import type { ChronicleLogEntry } from '../../../logging/ChronicleLogEntry.js';
 import type { ChronicleConnection } from '../../../connection/index.js';
 import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
@@ -98,7 +99,7 @@ function delivery(events: ReturnType<typeof event>[], replayState = ReplayState.
 }
 
 async function observe(type: Function, batches: ReturnType<typeof delivery>[], namespace = 'tenant-a',
-    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void) {
+    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void, logger?: IChronicleLogger) {
     const acknowledgements: NonNullable<ReactorMessage['Content']>['Value1'][] = [];
     const append = vi.fn().mockResolvedValue({ isSuccess: appendResult });
     const appendMany = vi.fn().mockImplementation(async () => {
@@ -122,7 +123,7 @@ async function observe(type: Function, batches: ReturnType<typeof delivery>[], n
         await lifecycle.disconnected(error => { throw error; });
         finished();
     }
-    const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+    const connection = { logger, reactors: { observe: stream } } as unknown as ChronicleConnection;
     const artifacts = { reactors: [type], eventTypes: [ActivationEvent] } as unknown as IClientArtifactsProvider;
     await new Reactors(artifacts, connection, 'store', namespace, lifecycle, eventLog, undefined, store, activator).register();
     await complete;
@@ -462,16 +463,15 @@ describe('when delivering reactor batches', () => {
     });
 
     it('should log disposal failure without changing successful acknowledgement', async () => {
-        const errors: string[] = [];
-        diag.setLogger({ error: (...values: unknown[]) => { errors.push(values.map(String).join(' ')); } } as DiagLogger, DiagLogLevel.ERROR);
-        try {
-            const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('cleanup'); } });
-            const result = await observe(ActivationReactor, [delivery([event('live', 1n)])], 'tenant-a', activator);
-            result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
-            result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
-            errors.some(value => value.includes('Error disposing activated artifact')).should.be.true;
-        } finally {
-            diag.disable();
-        }
+        const entries: ChronicleLogEntry[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('private cleanup details'); } });
+        const result = await observe(ActivationReactor, [delivery([event('private payload', 1n)])], 'tenant-a', activator,
+            true, undefined, { log: entry => entries.push(entry) });
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
+        entries.filter(entry => entry.attributes['exception.type'] === 'Error').should.have.lengthOf(1);
+        JSON.stringify(entries).should.not.contain('private cleanup details');
+        JSON.stringify(entries).should.not.contain('private payload');
+        JSON.stringify(entries).should.not.contain('book-1');
     });
 });

package/readModels/IReadModels.ts

@@ -95,4 +95,19 @@ export interface IReadModels {
      * @returns The read model instances with decrypted PII values.
      */
     releaseMany<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]>;
+
+    /**
+     * Releases PII in a raw stored document using its __subject and per-property __subjects metadata.
+     * Each __subjects key names a top-level property and overrides the default for its entire subtree.
+     * Properties without either subject are copied unchanged; id and @subject() are not fallbacks.
+     * @param readModelType - The discovered read model type supplying the schema.
+     * @param document - A JSON document, with optional non-empty string __subject and a __subjects map of property names to non-empty strings.
+     * @returns A new plain document containing only schema-declared top-level properties, without __subject or __subjects.
+     * The input is never mutated. This does not construct a typed read model instance.
+     * @throws If metadata is invalid, a subject property is absent from the document or schema, any release fails,
+     * or a response is malformed, incomplete, or conflicts with another property's group. No partial result is returned.
+     * @remarks Kernel per-property decryption failures that return HasError: false cannot be detected:
+     * https://github.com/Cratis/Chronicle/issues/4480.
+     */
+    releaseDocument<TReadModel>(readModelType: Constructor<TReadModel>, document: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>>;
 }

package/readModels/ReadModels.ts

@@ -19,7 +19,7 @@ import { hasFromEventMetadata } from '../projections/modelBound/fromEvent.js';
 import { hasModelBoundProperties } from '../types/TypeDiscoverer.js';
 import { isPassive } from '../projections/modelBound/passive.js';
 import { getReducerMetadata } from '../reducers/reducer.js';
-import { JsonSchemaGenerator } from '../schemas/index.js';
+import { JsonSchemaGenerator, type JsonSchema } from '../schemas/index.js';
 import { WellKnownSinks } from '../sinks/index.js';
 import { getReadModelMetadata, getReadModelId } from './readModel.js';
 import { buildReadModelDefinition } from './buildReadModelDefinition.js';
@@ -238,6 +238,123 @@ export class ReadModels implements IReadModels {
         return Promise.all(releasePromises);
     }
 
+    /** @inheritdoc */
+    async releaseDocument<TReadModel>(readModelType: Constructor<TReadModel>, document: Readonly<Record<string, unknown>>): Promise<Record<string, unknown>> {
+        const readModel = this.resolveReadModel(readModelType);
+        const schema = JSON.parse(this.getReadModelSchema(readModelType, readModel.identifier)) as JsonSchema;
+        const properties = schema.properties ?? {};
+        const stored = this.copyStoredDocument(document);
+        const storedDefaultSubject = stored.__subject;
+        const defaultSubject = this.isDocumentSubject(storedDefaultSubject) ? storedDefaultSubject : undefined;
+        const storedSubjects = this.isDocumentObject(stored.__subjects) ? stored.__subjects : {};
+        const subjects = new Map<string, string>();
+
+        if (storedDefaultSubject !== undefined && storedDefaultSubject !== null && typeof storedDefaultSubject !== 'string') {
+            throw new Error('Stored read model document has an invalid default subject.');
+        }
+        for (const [property, subject] of Object.entries(storedSubjects)) {
+            if (property === '__subject' || property === '__subjects') {
+                throw new Error('Stored read model document has an unknown subject property.');
+            }
+            // The kernel's JSON subject map ignores null/empty strings, but rejects non-string values.
+            if (subject !== null && typeof subject !== 'string') {
+                throw new Error('Stored read model document has an invalid property subject.');
+            }
+            // Cleared or removed properties can leave stale mappings in stored documents.
+            if (!Object.hasOwn(stored, property)) {
+                continue;
+            }
+            if (!Object.hasOwn(properties, property)) {
+                throw new Error('Stored read model document has an unknown subject property.');
+            }
+            if (this.isDocumentSubject(subject)) {
+                subjects.set(property, subject);
+            }
+        }
+
+        const groups = new Map<string, string[]>();
+        const releasedEntries: [string, unknown][] = [];
+        for (const [property, value] of Object.entries(stored)) {
+            // Only schema-declared data is returned, never storage bookkeeping.
+            if (property === '__subject' || property === '__subjects' || !Object.hasOwn(properties, property)) {
+                continue;
+            }
+            const subject = subjects.get(property) ?? defaultSubject;
+            if (subject === undefined) {
+                releasedEntries.push([property, value]);
+                continue;
+            }
+            const group = groups.get(subject) ?? [];
+            group.push(property);
+            groups.set(subject, group);
+        }
+
+        for (const [subject, propertyNames] of groups) {
+            const payload = Object.fromEntries(propertyNames.map(property => [property, stored[property]]));
+            const groupSchema: JsonSchema = {
+                ...schema,
+                properties: Object.fromEntries(propertyNames.map(property => [property, properties[property]])),
+                required: schema.required?.filter(property => propertyNames.includes(property))
+            };
+            const released = await this.releaseDocumentProperties(subject, groupSchema, payload);
+            const releasedProperties = Object.keys(released);
+            if (releasedProperties.length !== propertyNames.length ||
+                releasedProperties.some(property => !Object.hasOwn(payload, property))) {
+                throw new Error('Failed to release stored read model document: missing or conflicting properties.');
+            }
+            releasedEntries.push(...Object.entries(released));
+        }
+
+        // Publish only after every subject succeeded. Entire top-level subtrees belong to one group.
+        return Object.fromEntries(releasedEntries);
+    }
+
+    private async releaseDocumentProperties(subject: string, schema: JsonSchema, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+        try {
+            const response = await this._connection.compliance.release({
+                EventStore: this._eventStore,
+                Namespace: this._namespace,
+                Subject: subject,
+                Schema: JSON.stringify(schema),
+                Payload: JSON.stringify(payload)
+            });
+            if (response.HasError !== false || typeof response.Payload !== 'string') {
+                throw new Error();
+            }
+            const released: unknown = JSON.parse(response.Payload);
+            if (!this.isDocumentObject(released)) {
+                throw new Error();
+            }
+            return released;
+        } catch {
+            // Kernel, transport and JSON parser errors can contain PII; do not expose them as causes.
+            throw new Error('Failed to release PII in stored read model document.');
+        }
+    }
+
+    private copyStoredDocument(document: Readonly<Record<string, unknown>>): Record<string, unknown> {
+        try {
+            if (!this.isDocumentObject(document)) {
+                throw new Error();
+            }
+            const copy: unknown = JSON.parse(JSON.stringify(document));
+            if (!this.isDocumentObject(copy)) {
+                throw new Error();
+            }
+            return copy;
+        } catch {
+            throw new Error('Stored read model document must be a JSON object.');
+        }
+    }
+
+    private isDocumentObject(value: unknown): value is Record<string, unknown> {
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
+    }
+
+    private isDocumentSubject(value: unknown): value is string {
+        return typeof value === 'string' && value.length > 0;
+    }
+
     private async releaseSnapshotInstances<TReadModel>(readModelType: Constructor<TReadModel>, snapshots: ReadModelSnapshot<TReadModel>[]): Promise<ReadModelSnapshot<TReadModel>[]> {
         return Promise.all(
             snapshots.map(async snapshot => ({

package/readModels/for_ReadModels/given/a_stored_read_model.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { field } from '@cratis/fundamentals';
+import type { ReleaseRequest, ReleaseResponse } from '@cratis/chronicle.contracts';
+import { vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { pii } from '../../../compliance/pii.js';
+import { subject } from '../../../compliance/subject.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import type { IReadModels } from '../../IReadModels.js';
+import { ReadModels } from '../../ReadModels.js';
+
+class AccountOpened {}
+
+export class ContactDetails {
+    @field(String)
+    @pii()
+    phone!: string;
+}
+
+@fromEvent(AccountOpened)
+export class AccountDocument {
+    @field(String)
+    @subject()
+    id!: string;
+
+    @field(String)
+    @pii()
+    name!: string;
+
+    @field(String)
+    @pii()
+    email!: string;
+
+    @field(ContactDetails)
+    contact!: ContactDetails;
+
+    @field(Array, { genericArguments: [ContactDetails] })
+    contacts!: ContactDetails[];
+}
+
+export class a_stored_read_model {
+    readonly release = vi.fn<(request: ReleaseRequest) => Promise<ReleaseResponse>>()
+        .mockImplementation(async request => ({ HasError: false, Error: '', Payload: request.Payload }));
+    readonly readModels: IReadModels;
+
+    constructor() {
+        const connection = { compliance: { release: this.release } } as unknown as ChronicleConnection;
+        const artifacts: IClientArtifactsProvider = {
+            eventTypes: [], readModels: [AccountDocument], projections: [], reducers: [], reactors: [],
+            seeders: [], constraints: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+        };
+        this.readModels = new ReadModels('store', 'tenant', connection, artifacts, 'sink');
+    }
+
+    requestFor(subject: string): ReleaseRequest {
+        return this.release.mock.calls.map(([request]) => request).find(request => request.Subject === subject)!;
+    }
+}