@cratis/chronicle 6.9.0 → 6.10.0

package/projections/modelBound/decorators.standard.spec.ts

@@ -20,6 +20,12 @@ import { getSetFromMetadata, setFrom } from './setFrom.js';
 import { getSetValueMetadata, setValue } from './setValue.js';
 import { getSubtractFromMetadata, subtractFrom } from './subtractFrom.js';
 import { getTrackedJsonSchemaProperties, jsonSchemaProperty } from '../../schemas/jsonSchemaProperty.js';
+import { DecoratorType } from '../../types/DecoratorType.js';
+import { TypeDiscoverer } from '../../types/TypeDiscoverer.js';
+import { DefaultClientArtifactsProvider } from '../../artifacts/DefaultClientArtifactsProvider.js';
+import { ReadModels } from '../../readModels/ReadModels.js';
+import type { ChronicleConnection } from '../../connection/ChronicleConnection.js';
+import { vi } from 'vitest';
 
 class Changed {}
 
@@ -45,7 +51,46 @@ class Mappings {
     @jsonSchemaProperty() tracked!: string;
 }
 
+class StandardMappedOnly {
+    @setFrom(Changed) value = '';
+}
+
+class UnconstructedMappedOnly {
+    @setFrom(Changed) value = '';
+}
+
 describe('standard model-bound decorators', () => {
+    it('collects a standard-mapped class for lazy root discovery when constructed without file discovery', () => {
+        new StandardMappedOnly();
+        new StandardMappedOnly();
+        expect(TypeDiscoverer.default.getTypeByDecoratorTypeAndName(DecoratorType.ReadModel, 'StandardMappedOnly'))
+            .toBeUndefined();
+        expect(DefaultClientArtifactsProvider.default.readModels.filter(type => type === StandardMappedOnly)).toHaveLength(1);
+    });
+
+    it('registers the declaring class once even when subclasses and many instances are constructed', () => {
+        class Base {
+            @setFrom(Changed) value = '';
+        }
+        class Derived extends Base {}
+        const track = vi.spyOn(TypeDiscoverer.default, 'trackModelBoundProperty');
+        try {
+            for (let index = 0; index < 50; index++) new Base();
+            new Derived();
+            expect(track.mock.calls.filter(([type]) => type === Base)).toHaveLength(1);
+            expect(track.mock.calls.some(([type]) => type === Derived)).toBe(false);
+        } finally {
+            track.mockRestore();
+        }
+    });
+
+    it('should explain that an unconstructed property-only model was never registered', async () => {
+        const getInstanceByKey = vi.fn().mockResolvedValue({ ReadModel: '{"value":"stored"}' });
+        const connection = { readModels: { getInstanceByKey } } as unknown as ChronicleConnection;
+        const readModels = new ReadModels('store', 'Default', connection, DefaultClientArtifactsProvider.default, 'sink');
+        await expect(readModels.findInstanceById(UnconstructedMappedOnly, 'id')).rejects.toThrow(/add a class-level @fromEvent/);
+        expect(getInstanceByKey).not.toHaveBeenCalled();
+    });
     it('stores class and property annotations without constructing an instance', () => {
         const target = Mappings.prototype;
         expect(isNoAutoMap(Mappings)).toBe(true);

package/projections/modelBound/decrement.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the decrement property decorator. */
 export interface DecrementMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:decrement';
  * @returns A property decorator.
  */
 export function decrement(eventType: Function, constantKey?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: DecrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/fromAll.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the fromAll property decorator. */
 export interface FromAllMetadata {
@@ -25,7 +26,7 @@ const METADATA_KEY = 'chronicle:projection:fromAll';
  * @returns A property decorator.
  */
 export function fromAll(property?: string, contextProperty?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((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());

package/projections/modelBound/fromEvery.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the fromEvery property decorator. */
 export interface FromEveryMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:fromEvery';
  * @returns A property decorator.
  */
 export function fromEvery(property?: string, contextProperty?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propertyKey.toString());
         const metadata: FromEveryMetadata = { property, contextProperty };
         Reflect.defineMetadata(METADATA_KEY, metadata, target, propertyKey.toString());

package/projections/modelBound/increment.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the increment property decorator. */
 export interface IncrementMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:increment';
  * @returns A property decorator.
  */
 export function increment(eventType: Function, constantKey?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: IncrementMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/join.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the join property decorator. */
 export interface JoinMetadata {
@@ -25,7 +26,7 @@ const METADATA_KEY = 'chronicle:projection:join';
  * @returns A property decorator.
  */
 export function join(eventType: Function, on?: string, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: JoinMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/nested.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { decorateProperty, hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
 
 const METADATA_KEY = 'chronicle:projection:nested';
 
@@ -13,7 +14,7 @@ const METADATA_KEY = 'chronicle:projection:nested';
  * @param target - The class prototype.
  * @param propertyKey - The property name.
  */
-const decorateNested = decorateProperty((target: object, propertyKey: string | symbol): void => {
+const decorateNested = decorateModelBoundProperty((target: object, propertyKey: string | symbol): void => {
     const key = propertyKey.toString();
     TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
     Reflect.defineMetadata(METADATA_KEY, true, target, key);

package/projections/modelBound/noAutoMap.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { decorateClassOrProperty, hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { hasPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
 
 const CLASS_METADATA_KEY = 'chronicle:projection:noAutoMap:class';
 const PROPERTY_METADATA_KEY = 'chronicle:projection:noAutoMap:property';
@@ -18,7 +19,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:noAutoMap:property';
  * @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.
  */
-const decorateNoAutoMap = decorateClassOrProperty((target: object, propertyKey?: string | symbol): void => {
+const decorateNoAutoMap = decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol): void => {
     if (propertyKey !== undefined) {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);

package/projections/modelBound/removedWith.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
+import { ChronicleClassOrPropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the removedWith class or property decorator. */
 export interface RemovedWithMetadata {
@@ -28,7 +29,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:removedWith:property';
  * @returns A class and property decorator.
  */
 export function removedWith(eventType: Function, key?: string, parentKey?: string): ChronicleClassOrPropertyDecorator {
-    return decorateClassOrProperty((target: object, propertyKey?: string | symbol) => {
+    return decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol) => {
         if (propertyKey !== undefined) {
             const propKey = propertyKey.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);

package/projections/modelBound/removedWithJoin.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChronicleClassOrPropertyDecorator, decorateClassOrProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundClassOrProperty } from '../../types/modelBoundProperty.js';
+import { ChronicleClassOrPropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the removedWithJoin class or property decorator. */
 export interface RemovedWithJoinMetadata {
@@ -23,7 +24,7 @@ const PROPERTY_METADATA_KEY = 'chronicle:projection:removedWithJoin:property';
  * @returns A class and property decorator.
  */
 export function removedWithJoin(eventType: Function, key?: string): ChronicleClassOrPropertyDecorator {
-    return decorateClassOrProperty((target: object, propertyKey?: string | symbol) => {
+    return decorateModelBoundClassOrProperty((target: object, propertyKey?: string | symbol) => {
         if (propertyKey !== undefined) {
             const propKey = propertyKey.toString();
             TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);

package/projections/modelBound/setFrom.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setFrom property decorator. */
 export interface SetFromMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:setFrom';
  * @returns A property decorator.
  */
 export function setFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/setFromContext.ts

@@ -5,7 +5,8 @@ import 'reflect-metadata';
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import type { EventContext } from '../../events/index.js';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setFromContext property decorator. */
 export interface SetFromContextMetadata {
@@ -29,7 +30,7 @@ export function setFromContext(
     eventType: Function,
     contextPropertyOrAccessor?: string | PropertyAccessor<EventContext>
 ): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetFromContextMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/setValue.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the setValue property decorator. */
 export interface SetValueMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:setValue';
  * @returns A property decorator.
  */
 export function setValue(eventType: Function, value: unknown): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetValueMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/subtractFrom.ts

@@ -3,7 +3,8 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
-import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
+import { decorateModelBoundProperty } from '../../types/modelBoundProperty.js';
+import { ChroniclePropertyDecorator, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the subtractFrom property decorator. */
 export interface SubtractFromMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:subtractFrom';
  * @returns A property decorator.
  */
 export function subtractFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
-    return decorateProperty((target: object, propertyKey: string | symbol) => {
+    return decorateModelBoundProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SubtractFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/notSetPropertyPath.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The wire representation of PropertyPath.NotSet, used for nested projections. */
+export const notSetPropertyPath = '*NotSet*';

package/reactors/Reactors.ts

@@ -105,7 +105,9 @@ export class Reactors implements IReactors {
     private readonly _lifecycle: ConnectionLifecycle;
     private readonly _reactors = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReactorMessage>>();
+    private readonly _observations = new Map<string, AbortController>();
     private _registered = false;
+    private _disposed = false;
 
     /**
      * Creates a new {@link Reactors} instance.
@@ -133,6 +135,13 @@ export class Reactors implements IReactors {
         });
     }
 
+    /** Stops observations permanently when the owning client is disposed. */
+    dispose(): void {
+        this._disposed = true;
+        this._registered = false;
+        this.disconnectAll();
+    }
+
     /** @inheritdoc */
     async discover(): Promise<void> {
         this._reactors.clear();
@@ -147,7 +156,7 @@ export class Reactors implements IReactors {
 
     /** @inheritdoc */
     async register(): Promise<void> {
-        if (this._registered) {
+        if (this._registered || this._disposed) {
             return;
         }
 
@@ -155,6 +164,7 @@ export class Reactors implements IReactors {
             await this.discover();
         }
 
+        if (this._disposed) return;
         this._logger.info('Registering reactors', { count: this._reactors.size });
         for (const [id, reactorType] of this._reactors) {
             this.startObservation(id, reactorType);
@@ -164,6 +174,7 @@ 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 = this.getEventTypesFor(reactorType);
@@ -205,12 +216,12 @@ export class Reactors implements IReactors {
     private scheduleReobserve(id: string, reactorType: Constructor): void {
         // A disconnect clears the registration; the reconnect re-registers every
         // reactor from scratch, so retrying here as well would double up.
-        if (!this._registered) {
+        if (!this._registered || this._disposed) {
             return;
         }
 
         const handle = setTimeout(() => {
-            if (!this._registered) {
+            if (!this._registered || this._disposed) {
                 return;
             }
 
@@ -228,7 +239,9 @@ export class Reactors implements IReactors {
         eventTypes: EventTypeEntry[]
     ): Promise<void> {
         const queue = new AsyncQueue<ReactorMessage>();
+        const controller = new AbortController();
         this._queues.set(id, queue);
+        this._observations.set(id, controller);
 
         queue.send({
             Content: {
@@ -259,7 +272,7 @@ export class Reactors implements IReactors {
         try {
             const reactorInstance = new (reactorType as new () => Record<string, Function>)();
 
-            for await (const eventsToObserve of this._connection.reactors.observe(queue)) {
+            for await (const eventsToObserve of this._connection.reactors.observe(queue, { signal: controller.signal })) {
                 let lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
                 let state = ObservationState.Success;
                 const exceptionMessages: string[] = [];
@@ -358,7 +371,9 @@ export class Reactors implements IReactors {
             // leak a duplicate stream on every reconnect.
             if (this._queues.get(id) === queue) {
                 this._queues.delete(id);
+                this._observations.delete(id);
             }
+            queue.complete();
         }
     }
 
@@ -422,9 +437,9 @@ export class Reactors implements IReactors {
     }
 
     private disconnectAll(): void {
-        for (const queue of this._queues.values()) {
-            queue.complete();
-        }
+        for (const controller of this._observations.values()) controller.abort();
+        for (const queue of this._queues.values()) queue.complete();
+        this._observations.clear();
         this._queues.clear();
     }
 }

package/reactors/reactor.ts

@@ -25,8 +25,8 @@ export interface ReactorMetadata {
  * identifier. This is the TypeScript equivalent of the C# `[Reactor]` attribute.
  *
  * Reactors observe events from an event sequence and produce side effects.
- * Method dispatch is by convention: the type of the first parameter of each public method
- * determines which events it handles.
+ * Method dispatch is by convention: a handler's name is the event class name with
+ * its first letter lowercased (for example, `projectRegistered` handles `ProjectRegistered`).
  *
  * @param id - The unique identifier for the reactor. Defaults to the class name if omitted.
  * @param eventSequenceId - Optional explicit event sequence identifier.

package/readModels/MaterializedReadModels.spec.ts

@@ -25,6 +25,28 @@ function createMaterializedReadModels(instancesJson: string[], releaseResponse:
 }
 
 describe('MaterializedReadModels', () => {
+    describe('when materialized models have undecorated members', () => {
+        class Model { name = ''; count = 0; occurred = new Date(0); }
+        const json = JSON.stringify({ name: 'stored', count: 3, occurred: '2024-02-01T00:00:00.000Z' });
+
+        it('should restore members in paged reads', async () => {
+            const { readModels } = createMaterializedReadModels([json]);
+            const [instance] = await readModels.getInstances(Model);
+            expect(instance).toMatchObject({ name: 'stored', count: 3 });
+            expect(instance.occurred).toEqual(new Date('2024-02-01T00:00:00.000Z'));
+        });
+
+        it('should restore members in observed pages', async () => {
+            const connection = { materializedReadModels: { observeInstances: async function* () {
+                yield { Instances: [json] };
+            } } } as unknown as ChronicleConnection;
+            const readModels = new MaterializedReadModels('store', 'tenant', connection);
+            const response = await readModels.observeInstances(Model)[Symbol.asyncIterator]().next();
+            expect(response.value?.[0].name).toBe('stored');
+            expect(response.value?.[0].occurred).toBeInstanceOf(Date);
+        });
+    });
+
     describe('when a read model has a property decorated with @subject()', () => {
         class Employee {
             id = '';

package/readModels/MaterializedReadModels.ts

@@ -7,6 +7,7 @@ import { ChronicleConnection } from '../connection/index.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 import { getReadModelMetadata } from './readModel.js';
 import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
+import { deserializeReadModel } from './deserializeReadModel.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 
 const defaultTake = 50;
@@ -82,10 +83,7 @@ export class MaterializedReadModels implements IMaterializedReadModels {
     }
 
     private deserialize<TReadModel>(readModelType: Constructor<TReadModel>, json: string): TReadModel {
-        if (!json) {
-            return Object.create(readModelType.prototype) as TReadModel;
-        }
-        return JsonSerializer.deserialize(readModelType as Constructor<object>, json) as TReadModel;
+        return deserializeReadModel(readModelType, json);
     }
 
     private async releaseInstances<TReadModel>(readModelType: Constructor<TReadModel>, instances: TReadModel[]): Promise<TReadModel[]> {

package/readModels/ReadModels.spec.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { field, type Constructor } from '@cratis/fundamentals';
+import { ConceptAs, field, Guid, type Constructor } from '@cratis/fundamentals';
 import { describe, expect, it, vi } from 'vitest';
 import type { IClientArtifactsProvider } from '../artifacts/index.js';
 import type { ChronicleConnection } from '../connection/index.js';
@@ -10,6 +10,7 @@ import { subject } from '../compliance/subject.js';
 import { pii } from '../compliance/pii.js';
 import { reducer } from '../reducers/reducer.js';
 import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { setFrom } from '../projections/modelBound/setFrom.js';
 import { ReadModels } from './ReadModels.js';
 
 // Decorators are applied as plain function calls (rather than `@decorator` syntax) so these
@@ -91,6 +92,62 @@ describe('ReadModels', () => {
         });
     });
 
+    describe('when reading a model with undecorated and model-bound members', () => {
+        class Code extends ConceptAs<string> {}
+        class MappedModel {
+            id = '';
+            name = '';
+            count = 0;
+            active = false;
+            occurred = new Date(0);
+            mapped = '';
+            code = new Code('initial');
+            guid = Guid.empty;
+            typed = Guid.empty;
+        }
+        field(Guid)(MappedModel.prototype, 'typed');
+        setFrom(SomeEvent, 'value')(MappedModel.prototype, 'mapped');
+        fromEvent(SomeEvent)(MappedModel);
+        const json = JSON.stringify({ id: 'a', name: 'stored', count: 42, active: true,
+            occurred: '2024-01-02T00:00:00.000Z', mapped: 'from event', code: 'stored-code',
+            guid: 'e951d9a0-720f-4e37-835f-701707f7b678',
+            typed: 'e951d9a0-720f-4e37-835f-701707f7b678', __internal: 'ignored' });
+
+        it('should restore all declared members for single and multiple reads', async () => {
+            const { readModels, getInstanceByKey } = createReadModels(MappedModel);
+            getInstanceByKey.mockResolvedValue({ ReadModel: json });
+            const getAllInstances = vi.fn().mockResolvedValue({ Instances: [json] });
+            const connection = { readModels: { getAllInstances } } as unknown as ChronicleConnection;
+            const provider = { readModels: [MappedModel], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+            const all = await new ReadModels('store', 'tenant', connection, provider, 'sink').getInstances(MappedModel);
+            for (const instance of [await readModels.findInstanceById(MappedModel, 'a'),
+                await readModels.getInstanceById(MappedModel, 'a'), ...all]) {
+                expect(instance).toMatchObject({ id: 'a', name: 'stored', count: 42, active: true, mapped: 'from event' });
+                expect(instance?.occurred).toEqual(new Date('2024-01-02T00:00:00.000Z'));
+                expect(instance?.code).toBeInstanceOf(Code);
+                expect(instance?.code.value).toBe('stored-code');
+                expect(instance?.guid).toBeInstanceOf(Guid);
+                expect(instance?.typed).toBeInstanceOf(Guid);
+                expect(Object.hasOwn(instance as object, '__internal')).toBe(false);
+            }
+        });
+
+        it('should restore snapshot and watched instances', async () => {
+            const connection = { readModelExplorer: { allSnapshotsForReadModel: vi.fn().mockResolvedValue({ Data: [{ Instance: json }] }) },
+                readModels: { watch: async function* () {
+                    yield { Namespace: 'tenant', ModelKey: 'a', ReadModel: json, Removed: false };
+                } } } as unknown as ChronicleConnection;
+            const provider = { readModels: [MappedModel], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+            const readModels = new ReadModels('store', 'tenant', connection, provider, 'sink');
+            const snapshots = await readModels.getSnapshotsById(MappedModel, 'a');
+            const watched = await readModels.watch(MappedModel)[Symbol.asyncIterator]().next();
+            expect(snapshots[0].readModel.mapped).toBe('from event');
+            expect(snapshots[0].readModel.occurred).toBeInstanceOf(Date);
+            expect(watched.value?.readModel.name).toBe('stored');
+            expect(watched.value?.readModel.occurred).toBeInstanceOf(Date);
+        });
+    });
+
     describe('when reading a compliance-bearing reducer', () => {
         class PrivateModel { id = ''; ssn = ''; }
         field(String)(PrivateModel.prototype, 'id');
@@ -115,6 +172,34 @@ describe('ReadModels', () => {
         });
     });
 
+    describe('when watching a projection', () => {
+        class ProjectedModel { id = ''; }
+        field(String)(ProjectedModel.prototype, 'id');
+        fromEvent(SomeEvent)(ProjectedModel);
+
+        it('should skip the subscription marker and yield changes and removals', async () => {
+            const connection = {
+                readModels: { watch: async function* () {
+                    yield { Subscribed: true, Namespace: '', ModelKey: '', ReadModel: '', Removed: false };
+                    yield { Subscribed: false, Namespace: 'tenant', ModelKey: 'a', ReadModel: '{"id":"a"}', Removed: false };
+                    yield { Subscribed: false, Namespace: 'tenant', ModelKey: '', ReadModel: '{"id":"empty-key"}', Removed: false };
+                    yield { Subscribed: false, Namespace: 'tenant', ModelKey: 'a', ReadModel: '', Removed: true };
+                } }
+            } as unknown as ChronicleConnection;
+            const provider = { reducers: [], projections: [], readModels: [ProjectedModel] } as unknown as IClientArtifactsProvider;
+            const readModels = new ReadModels('store', 'tenant', connection, provider, 'sink');
+            const changesets = [];
+            for await (const changeset of readModels.watch(ProjectedModel)) {
+                changesets.push(changeset);
+            }
+
+            expect(changesets).toHaveLength(3);
+            expect(changesets[0]).toMatchObject({ namespace: 'tenant', key: 'a', removed: false, readModel: { id: 'a' } });
+            expect(changesets[1]).toMatchObject({ namespace: 'tenant', key: '', removed: false, readModel: { id: 'empty-key' } });
+            expect(changesets[2]).toMatchObject({ namespace: 'tenant', key: 'a', removed: true });
+        });
+    });
+
     describe('when watching a compliance-bearing reducer', () => {
         class PrivateModel { id = ''; ssn = ''; }
         field(String)(PrivateModel.prototype, 'id');
@@ -123,6 +208,29 @@ describe('ReadModels', () => {
         class PrivateReducer {}
         reducer('PrivateReducer', undefined, PrivateModel)(PrivateReducer);
 
+        it('should skip the subscription marker while releasing changes and retaining removals', async () => {
+            const release = vi.fn().mockResolvedValue({ HasError: false, Payload: '{"id":"a","ssn":"cleartext"}' });
+            const connection = {
+                readModels: { watch: async function* () {
+                    yield { Subscribed: true, Namespace: '', ModelKey: '', ReadModel: '', Removed: false };
+                    yield { Subscribed: false, Namespace: 'tenant', ModelKey: 'a', ReadModel: '{"id":"a","ssn":"ciphertext"}', Removed: false };
+                    yield { Subscribed: false, Namespace: 'tenant', ModelKey: 'a', ReadModel: '', Removed: true };
+                } },
+                compliance: { release }
+            } as unknown as ChronicleConnection;
+            const provider = { reducers: [PrivateReducer], projections: [], readModels: [] } as unknown as IClientArtifactsProvider;
+            const readModels = new ReadModels('store', 'tenant', connection, provider, 'sink');
+            const changesets = [];
+            for await (const changeset of readModels.watch(PrivateModel)) {
+                changesets.push(changeset);
+            }
+
+            expect(changesets).toHaveLength(2);
+            expect(changesets[0]).toMatchObject({ namespace: 'tenant', key: 'a', removed: false, readModel: { id: 'a', ssn: 'cleartext' } });
+            expect(changesets[1]).toMatchObject({ namespace: 'tenant', key: 'a', removed: true });
+            expect(release).toHaveBeenCalledTimes(1);
+        });
+
         it('should reject rather than expose an unreleased changeset', async () => {
             const release = vi.fn().mockResolvedValue({ HasError: true, Error: 'denied' });
             const connection = {