@cratis/chronicle 3.1.1 → 4.0.0

package/projections/Projections.ts

@@ -12,6 +12,11 @@ import { ChronicleConnection } from '../connection';
 import { toContractsGuid } from '../connection/Guid';
 import { WellKnownSinks } from '../sinks';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+import { JobId } from '../jobs/JobId';
+import { FailedPartition } from '../observation/FailedPartition';
+import { FailedPartitions } from '../observation/FailedPartitions';
+import { toObserverRunningState } from '../observation/toObserverRunningState';
 import { getReadModelMetadata } from '../readModels';
 import { TypeIntrospector } from '../types';
 import { IProjections } from './IProjections';
@@ -24,20 +29,28 @@ import {
     buildNestedEntry,
     ChildrenDefinitionLike,
     ContractEventType,
+    ensureFromEntry,
     FromRecord,
     getEventTypeMapKey,
     toContractEventType
 } from './modelBound/childrenAndNestedBuilder';
 import { getChildrenFromMetadata } from './modelBound/childrenFrom';
+import { getClearWithPropertyMetadata } from './modelBound/clearWith';
+import { getEventSequenceMetadata } from './modelBound/eventSequence';
+import { getFromAllMetadata } from './modelBound/fromAll';
 import { getFromEveryMetadata } from './modelBound/fromEvery';
 import { getFromEventMetadata, hasFromEventMetadata } from './modelBound/fromEvent';
 import { getJoinMetadata } from './modelBound/join';
+import { isNoAutoMap, isPropertyNoAutoMap } from './modelBound/noAutoMap';
 import { ProjectionId } from './ProjectionId';
+import { ProjectionQueryResult } from './ProjectionQueryResult';
+import { ProjectionState } from './ProjectionState';
 import { isNested } from './modelBound/nested';
 import { isNotRewindable } from './modelBound/notRewindable';
 import { isPassive } from './modelBound/passive';
 import { getRemovedWithClassMetadata, getRemovedWithPropertyMetadata } from './modelBound/removedWith';
 import { getRemovedWithJoinClassMetadata, getRemovedWithJoinPropertyMetadata } from './modelBound/removedWithJoin';
+import { UnableToQueryProjection } from './UnableToQueryProjection';
 
 interface ResolvedModelBoundMetadata {
     id: ProjectionId;
@@ -52,19 +65,27 @@ interface ResolvedModelBoundMetadata {
 export class Projections implements IProjections {
     private readonly _declarative = new Map<string, Constructor>();
     private readonly _modelBound = new Map<string, Constructor>();
+    private readonly _failedPartitions: FailedPartitions;
 
     private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/projections' });
 
     /**
      * Creates a new {@link Projections} instance.
+     * @param _eventStore - The event store name.
+     * @param _namespace - The event store namespace.
+     * @param _connection - Chronicle connection.
      * @param _clientArtifacts - Provider for discovered client artifact types.
+     * @param _defaultSinkTypeId - The identifier of the default read model sink.
      */
     constructor(
         private readonly _eventStore: string,
+        private readonly _namespace: string,
         private readonly _connection: ChronicleConnection,
         private readonly _clientArtifacts: IClientArtifactsProvider,
         private readonly _defaultSinkTypeId: string
-    ) {}
+    ) {
+        this._failedPartitions = new FailedPartitions(_eventStore, _namespace, _connection);
+    }
 
     /** @inheritdoc */
     async discover(): Promise<void> {
@@ -137,6 +158,148 @@ export class Projections implements IProjections {
         }
     }
 
+    /** @inheritdoc */
+    hasFor(projectionId: ProjectionId | string): boolean {
+        const id = this.toProjectionIdValue(projectionId);
+        return this._declarative.has(id) || this._modelBound.has(id);
+    }
+
+    /** @inheritdoc */
+    hasForModel(readModelType: Constructor): boolean {
+        try {
+            this.resolveProjectionIdForModel(readModelType);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** @inheritdoc */
+    getProjectionIdFor(readModelType: Constructor): ProjectionId {
+        return this.resolveProjectionIdForModel(readModelType);
+    }
+
+    /** @inheritdoc */
+    async getStateFor(projectionId: ProjectionId | string): Promise<ProjectionState> {
+        const id = this.toProjectionIdValue(projectionId);
+        const eventSequenceId = this.resolveEventSequenceIdFor(id);
+
+        const response = await this._connection.observers.getObserverInformation({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ObserverId: id,
+            EventSequenceId: eventSequenceId
+        });
+
+        return {
+            runningState: toObserverRunningState(response.RunningState),
+            isSubscribed: response.IsSubscribed,
+            nextEventSequenceNumber: new EventSequenceNumber(response.NextEventSequenceNumber),
+            lastHandledEventSequenceNumber: new EventSequenceNumber(response.LastHandledEventSequenceNumber),
+            tailEventSequenceNumber: new EventSequenceNumber(response.TailEventSequenceNumber)
+        };
+    }
+
+    /** @inheritdoc */
+    getStateForModel(readModelType: Constructor): Promise<ProjectionState> {
+        return this.getStateFor(this.resolveProjectionIdForModel(readModelType));
+    }
+
+    /** @inheritdoc */
+    getFailedPartitionsForModel(readModelType: Constructor): Promise<FailedPartition[]> {
+        const projectionId = this.resolveProjectionIdForModel(readModelType);
+        return this._failedPartitions.getFailedPartitionsFor(projectionId.value);
+    }
+
+    /** @inheritdoc */
+    async replay(projectionId: ProjectionId | string): Promise<JobId> {
+        const id = this.toProjectionIdValue(projectionId);
+
+        const response = await this._connection.observers.replay({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ObserverId: id,
+
+            // The kernel resolves the observer's own event sequence from its identifier - it does not
+            // need to be told which one to replay.
+            EventSequenceId: ''
+        });
+
+        return response.JobId ? JobId.from(response.JobId) : JobId.from(Guid.empty);
+    }
+
+    /** @inheritdoc */
+    replayForModel(readModelType: Constructor): Promise<JobId> {
+        return this.replay(this.resolveProjectionIdForModel(readModelType));
+    }
+
+    /** @inheritdoc */
+    async query(declaration: string, eventSequenceId: string = EventSequenceId.eventLog.value): Promise<ProjectionQueryResult> {
+        const result = await this._connection.projections.preview({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            EventSequenceId: eventSequenceId,
+            Declaration: declaration
+        });
+
+        if (result.Value1) {
+            throw new UnableToQueryProjection(result.Value1.Errors.map(error => error.Message));
+        }
+
+        return {
+            readModelEntries: result.Value0?.ReadModelEntries ?? []
+        };
+    }
+
+    private toProjectionIdValue(projectionId: ProjectionId | string): string {
+        return typeof projectionId === 'string' ? projectionId : projectionId.value;
+    }
+
+    /**
+     * Resolves the {@link ProjectionId} of the projection that maintains a specific read model type,
+     * from what has already been discovered.
+     * @param readModelType - The read model type to resolve for.
+     * @returns The resolved {@link ProjectionId}.
+     */
+    private resolveProjectionIdForModel(readModelType: Constructor): ProjectionId {
+        for (const [id, type] of this._modelBound) {
+            if (type === readModelType) {
+                return new ProjectionId(id);
+            }
+        }
+
+        for (const [id, type] of this._declarative) {
+            const metadata = getProjectionMetadata(type);
+            if (metadata?.readModelType === readModelType) {
+                return new ProjectionId(id);
+            }
+        }
+
+        throw new Error(
+            `No projection found for read model '${readModelType.name}'. Make sure discover() has run and the ` +
+            'read model is model-bound, or its declarative projection() decorator specifies an explicit readModelType.');
+    }
+
+    /**
+     * Resolves the event sequence identifier a discovered projection reads from, without requiring
+     * its full definition to have been built.
+     * @param projectionId - The projection identifier to resolve for.
+     * @returns The resolved event sequence identifier.
+     */
+    private resolveEventSequenceIdFor(projectionId: string): string {
+        const modelBoundType = this._modelBound.get(projectionId);
+        if (modelBoundType) {
+            return getEventSequenceMetadata(modelBoundType) ?? EventSequenceId.eventLog.value;
+        }
+
+        const declarativeType = this._declarative.get(projectionId);
+        if (declarativeType) {
+            return getProjectionMetadata(declarativeType)?.eventSequenceId ?? EventSequenceId.eventLog.value;
+        }
+
+        return EventSequenceId.eventLog.value;
+    }
+
     private async registerWithRetry(projection: unknown, identifier: string, maxAttempts = 5): Promise<void> {
         let delay = 2000;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -344,14 +507,25 @@ export class Projections implements IProjections {
                 childrenByProperty[property] = buildChildrenEntry(type, property, childrenFromList);
             }
 
-            if (isNested(prototype, property)) {
+            const propertyIsNested = isNested(prototype, property);
+            if (propertyIsNested) {
                 nestedByProperty[property] = buildNestedEntry(type, property);
             }
+
+            // A scalar (non-nested, non-children-collection) root property clears back to no value
+            // every time the given event is observed. A nested single-object property's clearWith is
+            // handled by buildNestedEntry instead, which clears the whole nested object.
+            if (childrenFromList.length === 0 && !propertyIsNested) {
+                for (const clearWith of getClearWithPropertyMetadata(prototype, property)) {
+                    const entry = ensureFromEntry(fromByEventType, clearWith.eventType);
+                    entry.Value.Properties[property] = '$null';
+                }
+            }
         }
 
         const allProperties: Record<string, string> = {};
         for (const property of properties) {
-            const fromEvery = getFromEveryMetadata(prototype, property);
+            const fromEvery = getFromEveryMetadata(prototype, property) ?? getFromAllMetadata(prototype, property);
             if (fromEvery) {
                 allProperties[property] = fromEvery.contextProperty
                     ? fromEvery.contextProperty
@@ -379,7 +553,8 @@ export class Projections implements IProjections {
             RemovedWithJoin: Array.from(removedWithJoinByEventType.values()),
             LastUpdated: { Value: '' },
             Tags: [],
-            AutoMap: AutoMap.Enabled,
+            AutoMap: isNoAutoMap(type) ? AutoMap.Disabled : AutoMap.Enabled,
+            NoAutoMapProperties: properties.filter(property => isPropertyNoAutoMap(prototype, property)),
             Nested: nestedByProperty
         };
         definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
@@ -392,7 +567,7 @@ export class Projections implements IProjections {
         if (readModelMetadata && hasFromEventMetadata(type)) {
             return {
                 id: new ProjectionId(readModelMetadata.id.value),
-                eventSequenceId: undefined,
+                eventSequenceId: getEventSequenceMetadata(type),
                 readModelIdentifier: readModelMetadata.id.value
             };
         }

package/projections/UnableToQueryProjection.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when a projection query fails because the Projection Declaration Language
+ * declaration contains errors.
+ */
+export class UnableToQueryProjection extends Error {
+    /**
+     * Creates a new {@link UnableToQueryProjection}.
+     * @param errors - The collection of error messages describing why the query failed.
+     */
+    constructor(errors: ReadonlyArray<string>) {
+        super(`Unable to query projection. Errors:\n${errors.join('\n')}`);
+        this.name = 'UnableToQueryProjection';
+    }
+}

package/projections/index.ts

@@ -4,5 +4,8 @@
 export { ProjectionId } from './ProjectionId';
 export type { IProjections } from './IProjections';
 export { Projections } from './Projections';
+export type { ProjectionState } from './ProjectionState';
+export type { ProjectionQueryResult } from './ProjectionQueryResult';
+export { UnableToQueryProjection } from './UnableToQueryProjection';
 export * from './declarative';
 export * from './modelBound';

package/projections/modelBound/eventSequence.ts

@@ -0,0 +1,38 @@
+// 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 { EventSequenceId } from '../../eventSequences/EventSequenceId';
+
+const METADATA_KEY = 'chronicle:projection:eventSequence';
+
+/**
+ * Class decorator that overrides the event sequence a model-bound projection reads from.
+ * When applied, auto-inbox routing is suppressed - the explicit value is always honored.
+ * @param sequence - The event sequence identifier to read from.
+ * @returns A class decorator.
+ */
+export function eventSequence(sequence: string): ClassDecorator {
+    return (target: object) => {
+        Reflect.defineMetadata(METADATA_KEY, sequence, target);
+    };
+}
+
+/**
+ * Convenience class decorator that pins a model-bound projection to the default event log
+ * sequence. Equivalent to `eventSequence(EventSequenceId.eventLog.value)`, but more expressive
+ * about the intent to read from the local event log rather than an inbox or another sequence.
+ * @param target - The class constructor.
+ */
+export function eventLog(target: Function): void {
+    Reflect.defineMetadata(METADATA_KEY, EventSequenceId.eventLog.value, target);
+}
+
+/**
+ * Retrieves the explicit event sequence identifier stored on a class, if any.
+ * @param target - The class constructor.
+ * @returns The event sequence identifier, or undefined when the class has no explicit override.
+ */
+export function getEventSequenceMetadata(target: Function): string | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target);
+}

package/projections/modelBound/fromAll.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 'reflect-metadata';
+import { TypeIntrospector } from '../../types';
+
+/** Metadata stored by the fromAll property decorator. */
+export interface FromAllMetadata {
+    /** The event property name to read the value from. */
+    readonly property?: string;
+    /** The event context property name to read the value from. */
+    readonly contextProperty?: string;
+}
+
+const METADATA_KEY = 'chronicle:projection:fromAll';
+
+/**
+ * Property decorator that sets the decorated read model property from a property present on every
+ * event type the projection is built from - the convention-based counterpart to declaring the same
+ * mapping on every individual `fromEvent`. Equivalent to {@link fromEvery} for model-bound
+ * projections; use whichever name reads better for the property being mapped.
+ * @param property - Optional event property name. If not specified, uses the model property name.
+ * @param contextProperty - Optional event context property name.
+ * @returns A property decorator.
+ */
+export function fromAll(property?: string, contextProperty?: string): PropertyDecorator {
+    return (target: object, propertyKey: string | symbol) => {
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propertyKey.toString());
+        const metadata: FromAllMetadata = { property, contextProperty };
+        Reflect.defineMetadata(METADATA_KEY, metadata, target, propertyKey.toString());
+    };
+}
+
+/**
+ * Retrieves fromAll metadata stored on the given property.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns The fromAll metadata, or undefined if not decorated.
+ */
+export function getFromAllMetadata(target: object, propertyKey: string): FromAllMetadata | undefined {
+    return Reflect.getMetadata(METADATA_KEY, target, propertyKey);
+}

package/projections/modelBound/index.ts

@@ -35,3 +35,7 @@ export { setValue, getSetValueMetadata } from './setValue';
 export type { SetValueMetadata } from './setValue';
 export { fromEvery, getFromEveryMetadata } from './fromEvery';
 export type { FromEveryMetadata } from './fromEvery';
+export { fromAll, getFromAllMetadata } from './fromAll';
+export type { FromAllMetadata } from './fromAll';
+export { noAutoMap, isNoAutoMap, isPropertyNoAutoMap } from './noAutoMap';
+export { eventSequence, eventLog, getEventSequenceMetadata } from './eventSequence';

package/projections/modelBound/noAutoMap.ts

@@ -0,0 +1,47 @@
+// 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 { TypeIntrospector } from '../../types';
+
+const CLASS_METADATA_KEY = 'chronicle:projection:noAutoMap:class';
+const PROPERTY_METADATA_KEY = 'chronicle:projection:noAutoMap:property';
+
+/**
+ * Class or property decorator that disables AutoMap for a model-bound projection.
+ * Applied to a class, it prevents AutoMap from mapping any property automatically.
+ * Applied to a property, it excludes only that single property from AutoMap while every other
+ * property keeps mapping - use it to stop an unrelated event that carries an identically named
+ * property from silently overwriting a property whose value is set explicitly (for example via
+ * `setFrom`).
+ * @param target - The class constructor, or the class prototype when used on a property.
+ * @param propertyKey - The property name, when used as a property decorator.
+ */
+export function noAutoMap(target: object, propertyKey?: string | symbol): void {
+    if (propertyKey !== undefined) {
+        const key = propertyKey.toString();
+        TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
+        Reflect.defineMetadata(PROPERTY_METADATA_KEY, true, target, key);
+    } else {
+        Reflect.defineMetadata(CLASS_METADATA_KEY, true, target as Function);
+    }
+}
+
+/**
+ * Checks whether the given class has AutoMap disabled entirely.
+ * @param target - The class constructor.
+ * @returns True if the class is marked with {@link noAutoMap}; false otherwise.
+ */
+export function isNoAutoMap(target: Function): boolean {
+    return Reflect.hasMetadata(CLASS_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a specific property is excluded from AutoMap.
+ * @param target - The class prototype.
+ * @param propertyKey - The property name.
+ * @returns True if the property is marked with {@link noAutoMap}; false otherwise.
+ */
+export function isPropertyNoAutoMap(target: object, propertyKey: string): boolean {
+    return Reflect.hasMetadata(PROPERTY_METADATA_KEY, target, propertyKey);
+}

package/reactors/Reactors.ts

@@ -12,6 +12,9 @@ import { getEventTypeMetadata } from '../events/eventTypeDecorator';
 import { EventContext } from '../events/EventContext';
 import { EventTypeId } from '../events/EventTypeId';
 import { EventTypeGeneration } from '../events/EventTypeGeneration';
+import { Tag } from '../events/Tag';
+import { getTagsFor } from '../events/tagDecorator';
+import { getFilterTagsFor } from '../events/filterEventsByTagDecorator';
 import { EventSequenceId } from '../eventSequences/EventSequenceId';
 import type { IEventLog } from '../eventSequences/IEventLog';
 import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle';
@@ -239,9 +242,9 @@ export class Reactors implements IReactors {
                             Key: EVENT_SOURCE_ID_KEY
                         })),
                         IsReplayable: false,
-                        Tags: [],
+                        Tags: getTagsFor(reactorType).map(t => t.value),
                         Filters: {
-                            FilterTags: [],
+                            FilterTags: getFilterTagsFor(reactorType).map(t => t.value),
                             EventSourceType: '',
                             EventStreamType: 'All'
                         }
@@ -303,7 +306,8 @@ export class Reactors implements IReactors {
                             },
                             occurred: new Date(event.Context!.Occurred?.Value ?? ''),
                             correlationId: event.Context?.CorrelationId ? `${event.Context.CorrelationId.lo}-${event.Context.CorrelationId.hi}` : '',
-                            causation: []
+                            causation: [],
+                            tags: (event.Context!.Tags ?? []).map(value => new Tag(value))
                         };
 
                         this._logger.info('Invoking reactor handler', {

package/readModels/MaterializedReadModels.spec.ts

@@ -0,0 +1,98 @@
+// 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 { describe, expect, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../connection';
+import { pii } from '../compliance/pii';
+import { subject } from '../compliance/subject';
+import { readModel } from './readModel';
+import { MaterializedReadModels } from './MaterializedReadModels';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+function createMaterializedReadModels(instancesJson: string[], releaseResponse: Record<string, unknown> = { HasError: false, Payload: '{}' }) {
+    const release = vi.fn().mockResolvedValue(releaseResponse);
+    const getInstances = vi.fn().mockResolvedValue({ Instances: instancesJson });
+    const connection = {
+        compliance: { release },
+        materializedReadModels: { getInstances }
+    } as unknown as ChronicleConnection;
+
+    const readModels = new MaterializedReadModels('test-store', 'test-namespace', connection);
+    return { readModels, release };
+}
+
+describe('MaterializedReadModels', () => {
+    describe('when a read model has a property decorated with @subject()', () => {
+        class Employee {
+            id = '';
+            personId = '';
+            ssn = '';
+        }
+        field(String)(Employee.prototype, 'id');
+        field(String)(Employee.prototype, 'personId');
+        field(String)(Employee.prototype, 'ssn');
+        pii()(Employee.prototype, 'ssn');
+        subject()(Employee.prototype, 'personId');
+        readModel('EmployeeWithSubjectMaterialized')(Employee);
+
+        it('should release using the decorated property as the subject', async () => {
+            const json = JSON.stringify({ id: 'employee-1', personId: 'person-42', ssn: '123-45-6789' });
+            const { readModels, release } = createMaterializedReadModels([json]);
+
+            await readModels.getInstances(Employee);
+
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'person-42' }));
+        });
+    });
+
+    describe('when a read model has no property decorated with @subject() but has an id property', () => {
+        class Customer {
+            id = '';
+            ssn = '';
+        }
+        field(String)(Customer.prototype, 'id');
+        field(String)(Customer.prototype, 'ssn');
+        pii()(Customer.prototype, 'ssn');
+        readModel('CustomerWithIdOnlyMaterialized')(Customer);
+
+        it('should fall back to the id property as the subject, unchanged from today', async () => {
+            const json = JSON.stringify({ id: 'customer-7', ssn: '987-65-4321' });
+            const { readModels, release } = createMaterializedReadModels([json]);
+
+            await readModels.getInstances(Customer);
+
+            expect(release).toHaveBeenCalledWith(expect.objectContaining({ Subject: 'customer-7' }));
+        });
+    });
+
+    describe('when a read model has neither a decorated property nor an id property', () => {
+        class Anonymous {
+            ssn = '';
+        }
+        field(String)(Anonymous.prototype, 'ssn');
+        pii()(Anonymous.prototype, 'ssn');
+        readModel('AnonymousMaterialized')(Anonymous);
+
+        it('should not call release, unchanged from today', async () => {
+            const json = JSON.stringify({ ssn: '000-00-0000' });
+            const { readModels, release } = createMaterializedReadModels([json]);
+
+            await readModels.getInstances(Anonymous);
+
+            expect(release).not.toHaveBeenCalled();
+        });
+
+        it('should return the instance unreleased', async () => {
+            const json = JSON.stringify({ ssn: '000-00-0000' });
+            const { readModels } = createMaterializedReadModels([json]);
+
+            const [instance] = await readModels.getInstances(Anonymous);
+
+            expect(instance.ssn).toBe('000-00-0000');
+        });
+    });
+});

package/readModels/MaterializedReadModels.ts

@@ -6,6 +6,7 @@ import { JsonSerializer } from '@cratis/fundamentals';
 import { ChronicleConnection } from '../connection';
 import { JsonSchemaGenerator } from '../schemas';
 import { getReadModelMetadata } from './readModel';
+import { ReadModelSubjectResolver } from './ReadModelSubjectResolver';
 import type { IMaterializedReadModels } from './IMaterializedReadModels';
 
 const defaultTake = 50;
@@ -97,7 +98,7 @@ export class MaterializedReadModels implements IMaterializedReadModels {
     }
 
     private async releaseInstance<TReadModel>(readModelType: Constructor<TReadModel>, instance: TReadModel, schema: string): Promise<TReadModel> {
-        const subject = this.extractSubject(instance);
+        const subject = ReadModelSubjectResolver.resolveFrom(readModelType, instance);
         if (!subject) {
             return instance;
         }
@@ -141,11 +142,4 @@ export class MaterializedReadModels implements IMaterializedReadModels {
         }
     }
 
-    private extractSubject<TReadModel>(instance: TReadModel): string | undefined {
-        const anyInstance = instance as Record<string, unknown>;
-        if (anyInstance.id !== undefined && anyInstance.id !== null) {
-            return String(anyInstance.id);
-        }
-        return undefined;
-    }
 }

package/readModels/ReadModelSubjectResolver.spec.ts

@@ -0,0 +1,84 @@
+// 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 { describe, expect, it } from 'vitest';
+import { subject } from '../compliance/subject';
+import { ReadModelSubjectResolver } from './ReadModelSubjectResolver';
+
+// Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
+// fixtures don't depend on the test runner's decorator-syntax support.
+
+describe('ReadModelSubjectResolver', () => {
+    describe('when the read model has a property decorated with @subject()', () => {
+        class Employee {
+            id = '';
+            personId = '';
+        }
+        subject()(Employee.prototype, 'personId');
+
+        it('should resolve to the decorated property value', () => {
+            const instance = new Employee();
+            instance.id = 'employee-1';
+            instance.personId = 'person-42';
+
+            expect(ReadModelSubjectResolver.resolveFrom(Employee, instance)).toBe('person-42');
+        });
+
+        it('should take precedence over the id property', () => {
+            const instance = new Employee();
+            instance.id = 'employee-1';
+            instance.personId = 'person-42';
+
+            expect(ReadModelSubjectResolver.resolveFrom(Employee, instance)).not.toBe('employee-1');
+        });
+
+        it('should fall back to id when the decorated property has no value', () => {
+            const instance = new Employee();
+            instance.id = 'employee-1';
+            instance.personId = '';
+
+            expect(ReadModelSubjectResolver.resolveFrom(Employee, instance)).toBe('employee-1');
+        });
+    });
+
+    describe('when the read model has no property decorated with @subject()', () => {
+        class Customer {
+            id = '';
+            name = '';
+        }
+
+        it('should fall back to the id property', () => {
+            const instance = new Customer();
+            instance.id = 'customer-7';
+
+            expect(ReadModelSubjectResolver.resolveFrom(Customer, instance)).toBe('customer-7');
+        });
+    });
+
+    describe('when the read model has neither a decorated property nor an id property', () => {
+        class Anonymous {
+            name = '';
+        }
+
+        it('should not resolve a subject', () => {
+            const instance = new Anonymous();
+
+            expect(ReadModelSubjectResolver.resolveFrom(Anonymous, instance)).toBeUndefined();
+        });
+    });
+
+    describe('when the instance does not exist', () => {
+        class Customer {
+            id = '';
+        }
+
+        it('should not resolve a subject for null', () => {
+            expect(ReadModelSubjectResolver.resolveFrom(Customer, null as unknown as Customer)).toBeUndefined();
+        });
+
+        it('should not resolve a subject for undefined', () => {
+            expect(ReadModelSubjectResolver.resolveFrom(Customer, undefined as unknown as Customer)).toBeUndefined();
+        });
+    });
+});