@cratis/chronicle 6.9.1 → 6.11.0

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
@@ -49,7 +50,7 @@ describe('ReadModels', () => {
         class MissingModel { id = ''; }
         fromEvent(SomeEvent)(MissingModel);
 
-        it('should retain the legacy prototype-only instance for getInstanceById', async () => {
+        it('should retain a prototype-only instance for getInstanceById when the document is empty', async () => {
             const { readModels, release } = createReadModels(MissingModel);
             const instance = await readModels.getInstanceById(MissingModel, 'missing');
             expect(instance).toBeInstanceOf(MissingModel);
@@ -65,13 +66,21 @@ describe('ReadModels', () => {
             expect(release).not.toHaveBeenCalled();
         });
 
-        it('should return null when the kernel responds with literal JSON null', async () => {
+        it('should return null from findInstanceById when the kernel responds with JSON null', async () => {
             const { readModels, getInstanceByKey, release } = createReadModels(MissingModel);
             getInstanceByKey.mockResolvedValue({ ReadModel: 'null' });
             const instance = await readModels.findInstanceById(MissingModel, 'missing');
             expect(instance).toBeNull();
             expect(release).not.toHaveBeenCalled();
         });
+
+        it('should retain the constructed default instance from getInstanceById for JSON null', async () => {
+            const { readModels, getInstanceByKey } = createReadModels(MissingModel);
+            getInstanceByKey.mockResolvedValue({ ReadModel: 'null' });
+            const instance = await readModels.getInstanceById(MissingModel, 'missing');
+            expect(instance).toBeInstanceOf(MissingModel);
+            expect(instance.id).toBe('');
+        });
     });
 
     describe('when a read model instance exists for a key', () => {
@@ -85,9 +94,65 @@ describe('ReadModels', () => {
             const instance = await readModels.findInstanceById(ExistingModel, 'found');
             expect(instance).toBeInstanceOf(ExistingModel);
             expect(instance?.id).toBe('found');
-            const legacyInstance = await readModels.getInstanceById(ExistingModel, 'found');
-            expect(legacyInstance).toBeInstanceOf(ExistingModel);
-            expect(legacyInstance.id).toBe('found');
+            const canonicalInstance = await readModels.getInstanceById(ExistingModel, 'found');
+            expect(canonicalInstance).toBeInstanceOf(ExistingModel);
+            expect(canonicalInstance.id).toBe('found');
+        });
+    });
+
+    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);
         });
     });
 

package/readModels/ReadModels.ts

@@ -24,9 +24,11 @@ import { JsonSchemaGenerator } from '../schemas/index.js';
 import { WellKnownSinks } from '../sinks/index.js';
 import { getReadModelMetadata, getReadModelId } from './readModel.js';
 import { assertUniqueReadModelIds } from './assertUniqueReadModelIds.js';
+import { rootReadModelTypes } from './rootReadModelTypes.js';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
 import { MaterializedReadModels } from './MaterializedReadModels.js';
 import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
+import { deserializeReadModel } from './deserializeReadModel.js';
 import type { IReadModels } from './IReadModels.js';
 import type { ReadModelChangeset } from './ReadModelChangeset.js';
 import type { ReadModelSnapshot } from './ReadModelSnapshot.js';
@@ -41,6 +43,7 @@ interface ResolvedReadModel {
     readonly observerIdentifier: string;
     readonly schema: string;
     readonly isActive: boolean;
+    readonly isModelBound?: boolean;
 }
 
 /**
@@ -54,7 +57,8 @@ export class ReadModels implements IReadModels {
         private readonly _namespace: string,
         private readonly _connection: ChronicleConnection,
         private readonly _clientArtifacts: IClientArtifactsProvider,
-        private readonly _defaultSinkTypeId: string
+        private readonly _defaultSinkTypeId: string,
+        private readonly _isModelBoundProjectionRegistered?: (readModelType: Constructor) => boolean
     ) {
         this.materialized = new MaterializedReadModels(_eventStore, _namespace, _connection);
     }
@@ -74,10 +78,7 @@ export class ReadModels implements IReadModels {
         });
     }
 
-    /**
-     * @inheritdoc
-     * @deprecated Use {@link findInstanceById} to distinguish an absent instance from a stored one.
-     */
+    /** @inheritdoc */
     async getInstanceById<TReadModel>(readModelType: Constructor<TReadModel>, key: string, sessionId?: string): Promise<TReadModel> {
         const readModel = this.resolveReadModel(readModelType);
         const response = await this._connection.readModels.getInstanceByKey({
@@ -245,7 +246,8 @@ export class ReadModels implements IReadModels {
     }
 
     private resolveReadModels<TReadModel>(readModelType?: Constructor<TReadModel>): ResolvedReadModel[] {
-        assertUniqueReadModelIds(this._clientArtifacts.readModels);
+        const rootTypes = rootReadModelTypes(this._clientArtifacts);
+        assertUniqueReadModelIds(rootTypes);
         const resolved = new Map<string, ResolvedReadModel>();
 
         for (const projectionType of this._clientArtifacts.projections) {
@@ -270,7 +272,7 @@ export class ReadModels implements IReadModels {
             });
         }
 
-        for (const modelBoundType of this._clientArtifacts.readModels) {
+        for (const modelBoundType of rootTypes) {
             if (!hasFromEventMetadata(modelBoundType) && !hasModelBoundProperties(modelBoundType)) {
                 continue;
             }
@@ -287,7 +289,8 @@ export class ReadModels implements IReadModels {
                 observerType: ContractReadModelObserverType.Projection,
                 observerIdentifier: identifier,
                 schema: this.getReadModelSchema(modelBoundType, identifier),
-                isActive: !isPassive(modelBoundType)
+                isActive: !isPassive(modelBoundType),
+                isModelBound: true
             });
         }
 
@@ -327,13 +330,16 @@ export class ReadModels implements IReadModels {
 
     private resolveReadModel<TReadModel>(readModelType: Constructor<TReadModel>): ResolvedReadModel {
         const [resolved] = this.resolveReadModels(readModelType);
-        if (!resolved) {
-            throw new Error(`Unknown read model '${readModelType.name}'. Make sure it is discoverable through a projection, reducer, or model-bound mapping.`);
+        const neverRegistered = resolved?.isModelBound && this._isModelBoundProjectionRegistered && !this._isModelBoundProjectionRegistered(readModelType);
+        if (!resolved || neverRegistered) {
+            throw new Error(hasModelBoundProperties(readModelType)
+                ? `Unknown read model '${readModelType.name}'. It has model-bound property mappings but was not registered when the event store was created. With standard decorators, a class whose mappings are all on properties is only registered once an instance exists; add a class-level @fromEvent(...) decorator so it registers when its module loads.`
+                : `Unknown read model '${readModelType.name}'. Make sure it is discoverable through a projection, reducer, or model-bound mapping.`);
         }
-
         return resolved;
     }
 
+
     private toDefinition(readModel: ResolvedReadModel) {
         return {
             Type: {
@@ -367,10 +373,7 @@ export class ReadModels implements IReadModels {
     }
 
     private deserializeReadModel<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 schemaHasComplianceMetadata(schema: string): boolean {

package/readModels/conceptValueType.spec.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, Guid } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { deserializeReadModel } from './deserializeReadModel.js';
+
+class Cid extends ConceptAs<Guid> { static readonly valueType = Guid; }
+class BirthDate extends ConceptAs<Date> { static readonly valueType = Date; }
+class Concepts { cid = new Cid(Guid.empty); birth = new BirthDate(new Date(0)); }
+
+describe('concept value restoration', () => {
+    it('uses static valueType for Guid and Date without design metadata', () => {
+        const concepts = deserializeReadModel(Concepts, JSON.stringify({ cid: 'f417bba6-5737-488a-a225-37da46b96221', birth: '2025-01-02T00:00:00.000Z' }));
+        expect(concepts.cid).toBeInstanceOf(Cid);
+        expect(concepts.cid.value).toBeInstanceOf(Guid);
+        expect(concepts.birth).toBeInstanceOf(BirthDate);
+        expect(concepts.birth.value).toBeInstanceOf(Date);
+    });
+});

package/readModels/deserializeReadModel.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 { ConceptAs, Guid, field } from '@cratis/fundamentals';
+import { describe, expect, it } from 'vitest';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
+import { deserializeReadModel } from './deserializeReadModel.js';
+
+class Identity extends ConceptAs<Guid> {}
+Reflect.defineMetadata('design:paramtypes', [Guid], Identity);
+class Model {
+    date!: Date;
+    id!: Guid;
+    identity!: Identity;
+    enabled!: boolean;
+    get computed(): string { return 'computed'; }
+}
+for (const name of ['date', 'id', 'identity', 'enabled', 'computed']) TypeIntrospector.trackProperty(Model, name);
+Reflect.defineMetadata('design:type', Date, Model.prototype, 'date');
+Reflect.defineMetadata('design:type', Guid, Model.prototype, 'id');
+Reflect.defineMetadata('design:type', Identity, Model.prototype, 'identity');
+Reflect.defineMetadata('design:type', Boolean, Model.prototype, 'enabled');
+
+class Inferred {
+    date = new Date(0);
+    id = Guid.empty;
+}
+
+class Address { street = ''; city = ''; }
+class DecoratedAddress { street = ''; city = ''; }
+field(String)(DecoratedAddress.prototype, 'street');
+class Person { address = new Address(); decorated = new DecoratedAddress(); children: Address[] = []; }
+field(Array, { genericArguments: [Address] })(Person.prototype, 'children');
+
+const guid = 'f417bba6-5737-488a-a225-37da46b96221';
+
+describe('deserializeReadModel', () => {
+    it('restores declared values, concepts and false strings while skipping read-only accessors', () => {
+        const model = deserializeReadModel(Model, JSON.stringify({
+            date: '2025-01-02T00:00:00.000Z', id: guid, identity: guid, enabled: 'false', computed: 'stored'
+        }));
+        expect(model.date).toBeInstanceOf(Date);
+        expect(model.id).toBeInstanceOf(Guid);
+        expect(model.identity.value).toBeInstanceOf(Guid);
+        expect(model.enabled).toBe(false);
+        expect(model.computed).toBe('computed');
+    });
+
+    it('uses inferred member types without legacy design metadata', () => {
+        const model = deserializeReadModel(Inferred, JSON.stringify({ date: '2025-01-02T00:00:00.000Z', id: guid }));
+        expect(model.date).toBeInstanceOf(Date);
+        expect(model.id).toBeInstanceOf(Guid);
+    });
+
+    it('restores nested plain members, mixed decorated members and typed child arrays', () => {
+        const person = deserializeReadModel(Person, JSON.stringify({
+            address: { street: 'Main', city: 'Oslo' },
+            decorated: { street: 'Oak', city: 'Rome' },
+            children: [{ street: 'First', city: 'Paris' }, { street: 'Second', city: 'Berlin' }]
+        }));
+        expect(person.address).toBeInstanceOf(Address);
+        expect(person.address).toEqual({ street: 'Main', city: 'Oslo' });
+        expect(person.decorated).toBeInstanceOf(DecoratedAddress);
+        expect(person.decorated).toEqual({ street: 'Oak', city: 'Rome' });
+        expect(person.children).toHaveLength(2);
+        expect(person.children[0]).toBeInstanceOf(Address);
+        expect(person.children[1]).toEqual({ street: 'Second', city: 'Berlin' });
+    });
+
+    it('introspects members only once for multiple rows', () => {
+        const getMembers = TypeIntrospector.getMembers;
+        let calls = 0;
+        TypeIntrospector.getMembers = function (...args) { calls++; return getMembers.apply(this, args); };
+        try {
+            class Rows { enabled = false; }
+            deserializeReadModel(Rows, '{"enabled":false}');
+            deserializeReadModel(Rows, '{"enabled":false}');
+            expect(calls).toBe(1);
+        } finally {
+            TypeIntrospector.getMembers = getMembers;
+        }
+    });
+});

package/readModels/deserializeReadModel.ts

@@ -0,0 +1,82 @@
+// 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 { conceptAsTypeKey, type Constructor, Fields, Guid, JsonSerializer, typeKeyOf } from '@cratis/fundamentals';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
+import { conceptValueType } from '../types/conceptValueType.js';
+import { getChildrenFromMetadata } from '../projections/modelBound/childrenFrom.js';
+
+const memberCache = new WeakMap<Function, Map<string, Function | undefined>>();
+
+function membersFor(type: Function): Map<string, Function | undefined> {
+    let members = memberCache.get(type);
+    if (!members) {
+        members = TypeIntrospector.getMembers(type);
+        memberCache.set(type, members);
+    }
+    return members;
+}
+
+function writable(type: Function, name: string): boolean {
+    let prototype = type.prototype;
+    while (prototype) {
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+        if (descriptor) return !descriptor.get || !!descriptor.set;
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return true;
+}
+
+function convert(type: Function, value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+    if (typeKeyOf(type as Constructor) === conceptAsTypeKey) {
+        const underlying = conceptValueType(type);
+        return Reflect.construct(type, [underlying ? convert(underlying, value) : value]);
+    }
+    if (type === Boolean) return typeof value === 'string' && /^(true|false)$/i.test(value) ? value.toLowerCase() === 'true' : value;
+    if (type === Number) return Number(value);
+    if (type === String) return String(value);
+    if (type === Date || type === Guid || typeKeyOf(type as Constructor) === 'Guid') {
+        return JsonSerializer.deserializeFromInstance(type as Constructor<object>, value);
+    }
+    if (typeof value === 'object' && type !== Array && type !== Object && !Array.isArray(value)) {
+        return restore(type as Constructor<object>, value as Record<string, unknown>);
+    }
+    return value;
+}
+
+function restore<T>(type: Constructor<T>, stored: Record<string, unknown> | null): T {
+    const fields = Fields.getFieldsForType(type);
+    const instance = fields.length > 0
+        ? JsonSerializer.deserializeFromInstance(type as Constructor<object>, stored) as T
+        : Reflect.construct(type, []) as T;
+    if (!stored || typeof stored !== 'object' || Array.isArray(stored)) return instance;
+
+    const fieldByName = new Map(fields.map(field => [field.name, field]));
+    const result = instance as Record<string, unknown>;
+    for (const [name, runtimeType] of membersFor(type)) {
+        if (name.startsWith('__') || !writable(type, name) || !Object.prototype.hasOwnProperty.call(stored, name)) continue;
+        const value = stored[name];
+        const field = fieldByName.get(name);
+        const childType = getChildrenFromMetadata(type.prototype, name).find(metadata => metadata.childType)?.childType ?? field?.genericArguments?.[0];
+        if (Array.isArray(value) && childType) {
+            result[name] = value.map(item => convert(childType, item));
+        } else if (field && (value === null || value === undefined || !runtimeType || runtimeType === Array || runtimeType === Object || typeof value !== 'object')) {
+            // The serializer has already handled decorated scalar fields.
+            if (value === null || value === undefined) result[name] = value;
+        } else {
+            result[name] = value === null || value === undefined || !runtimeType ? value : convert(runtimeType, value);
+        }
+    }
+    return instance;
+}
+
+/** Restores declared model members not covered by Fundamentals' @field-based deserializer. */
+export function deserializeReadModel<TReadModel>(readModelType: Constructor<TReadModel>, json: string): TReadModel {
+    if (!json) {
+        return Object.create(readModelType.prototype) as TReadModel;
+    }
+
+    return restore(readModelType, JSON.parse(json) as Record<string, unknown> | null);
+}

package/readModels/discovery.spec.ts

@@ -67,6 +67,33 @@ describe('when discovering read models from observers', () => {
         expect(JSON.parse(definition.Schema).properties.value.type).toBe('string');
         expect(register.mock.calls.some(call => call[0].Projections[0].ReadModel === 'MappedOnly')).toBe(true);
     });
+    it('should register a property-bound model without file discovery', async () => {
+        class DecoratedOnly { value = ''; }
+        setFrom(Event)(DecoratedOnly.prototype, 'value');
+        setFrom(Event)(DecoratedOnly.prototype, 'value');
+        expect(DefaultClientArtifactsProvider.default.readModels.filter(type => type === DecoratedOnly)).toHaveLength(1);
+        const { connection, registerMany } = createConnection();
+        await new ReadModels('store', 'Default', connection, DefaultClientArtifactsProvider.default, 'sink').register(DecoratedOnly);
+        expect(registerMany.mock.calls[0][0].ReadModels[0].Type.Identifier).toBe('DecoratedOnly');
+    });
+
+    it('should refuse to query a model-bound read model whose projection was never registered', async () => {
+        class RegisteredLate { value = ''; }
+        setFrom(Event)(RegisteredLate.prototype, 'value');
+        const { connection } = createConnection();
+        const readModels = new ReadModels('store', 'Default', connection, DefaultClientArtifactsProvider.default, 'sink', () => false);
+        await expect(readModels.findInstanceById(RegisteredLate, 'key')).rejects.toThrow(/add a class-level @fromEvent/);
+    });
+
+    it('should explain how to register an unregistered property-bound model', async () => {
+        class NeverRegistered { value = ''; }
+        Reflect.defineMetadata('chronicle:projection:setFrom', [{ eventType: Event }], NeverRegistered.prototype, 'value');
+        Reflect.defineMetadata('chronicle:typeIntrospection:properties', ['value'], NeverRegistered);
+        const { connection } = createConnection();
+        await expect(new ReadModels('store', 'Default', connection, DefaultClientArtifactsProvider.default, 'sink').findInstanceById(NeverRegistered, 'key'))
+            .rejects.toThrow(/add a class-level @fromEvent/);
+    });
+
     it('should deduplicate inferred types and retain custom identifiers', async () => {
         const provider = DefaultClientArtifactsProvider.default;
         for (const type of [ModelBound, Projected, Reduced]) {

package/readModels/rootReadModelTypes.spec.ts

@@ -0,0 +1,115 @@
+// 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 } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { childrenFrom } from '../projections/modelBound/childrenFrom.js';
+import { nested } from '../projections/modelBound/nested.js';
+import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import { DecoratorType } from '../types/DecoratorType.js';
+import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
+import { JsonSchemaGenerator } from '../schemas/JsonSchemaGenerator.js';
+import { projection } from '../projections/declarative/projection.js';
+import type { IProjectionBuilderFor } from '../projections/declarative/IProjectionBuilderFor.js';
+import { setFrom } from '../projections/modelBound/setFrom.js';
+import { rootReadModelTypes } from './rootReadModelTypes.js';
+import { Projections } from '../projections/Projections.js';
+import type { ChronicleConnection } from '../connection/ChronicleConnection.js';
+import { assertUniqueReadModelIds } from './assertUniqueReadModelIds.js';
+
+class Added { value!: string; }
+eventType()(Added);
+
+function parentWithChild() {
+    class Item { value!: string; }
+    setFrom(Added)(Item.prototype, 'value');
+    class Parent { items!: Item[]; }
+    field(Array, { genericArguments: [Item] })(Parent.prototype, 'items');
+    childrenFrom(Added)(Parent.prototype, 'items');
+    return { Parent, Item };
+}
+
+describe('root model-bound discovery', () => {
+    it('discovers only the parent as a root projection', async () => {
+        const { Parent, Item } = parentWithChild();
+        const artifacts = { readModels: [Parent, Item], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        const projections = new Projections('test', 'Default', {} as ChronicleConnection, artifacts, 'sink');
+        await projections.discover();
+        expect(projections.hasFor('Parent')).toBe(true);
+        expect(projections.hasFor('Item')).toBe(false);
+    });
+
+    it('does not register a child with its own setFrom as a root', () => {
+        const { Parent, Item } = parentWithChild();
+        const artifacts = { readModels: [Parent, Item], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(rootReadModelTypes(artifacts)).toEqual([Parent]);
+    });
+
+    it('resolves children from decorator metadata without design metadata', () => {
+        class Item { value = ''; }
+        setFrom(Added)(Item.prototype, 'value');
+        class Parent { items: Item[] = []; }
+        childrenFrom(Added, Item)(Parent.prototype, 'items');
+        const artifacts = { readModels: [Parent, Item], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(rootReadModelTypes(artifacts)).toEqual([Parent]);
+        expect(JsonSchemaGenerator.generate(Parent, undefined, true).properties?.items.items?.properties?.value.type).toBe('string');
+        const projections = new Projections('test', 'Default', {} as ChronicleConnection, artifacts, 'sink');
+        return projections.discover().then(() => {
+            expect(projections.hasFor('Parent')).toBe(true);
+            expect(projections.hasFor('Item')).toBe(false);
+        });
+    });
+
+    it('excludes nested default-instance members and their grandchildren', () => {
+        class Leaf { value = ''; }
+        setFrom(Added)(Leaf.prototype, 'value');
+        class Address { leaf = new Leaf(); }
+        nested(Address.prototype, 'leaf');
+        class Parent { addr = new Address(); }
+        nested(Parent.prototype, 'addr');
+        const artifacts = { readModels: [Parent, Address, Leaf], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(rootReadModelTypes(artifacts)).toEqual([Parent]);
+    });
+
+    it('excludes a typed child referenced only by a declarative children builder', () => {
+        class Child { value = ''; }
+        setFrom(Added)(Child.prototype, 'value');
+        class Parent { children: Child[] = []; }
+        field(Array, { genericArguments: [Child] })(Parent.prototype, 'children');
+        class ParentProjection {
+            define(builder: IProjectionBuilderFor<Parent>) { builder.children<Child>(parent => parent.children, () => {}); }
+        }
+        projection('parent-projection', Parent)(ParentProjection);
+        const artifacts = { readModels: [Parent, Child], projections: [ParentProjection], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(rootReadModelTypes(artifacts)).toEqual([Parent]);
+    });
+
+    it('retains a self-referencing tree as a root', () => {
+        class Node { children: Node[] = []; }
+        childrenFrom(Added, Node)(Node.prototype, 'children');
+        const artifacts = { readModels: [Node], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(rootReadModelTypes(artifacts)).toEqual([Node]);
+    });
+
+    it('does not eagerly register a property-only child as a root', () => {
+        const discoverer = new TypeDiscoverer();
+        const before = discoverer.getTypesByDecoratorType(DecoratorType.ReadModel);
+        const { Parent, Item } = parentWithChild();
+        expect(discoverer.getTypesByDecoratorType(DecoratorType.ReadModel)).toEqual(before);
+        const artifacts = new DefaultClientArtifactsProvider(discoverer);
+        expect(rootReadModelTypes(artifacts)).toContain(Parent);
+        expect(rootReadModelTypes(artifacts)).not.toContain(Item);
+    });
+
+    it('permits equal-named child types under different parents', () => {
+        const first = parentWithChild();
+        const second = parentWithChild();
+        Object.defineProperty(second.Parent, 'name', { value: 'OtherParent' });
+        const artifacts = { readModels: [first.Parent, first.Item, second.Item, second.Parent], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        expect(() => assertUniqueReadModelIds(rootReadModelTypes(artifacts))).not.toThrow();
+        expect(rootReadModelTypes(artifacts)).toEqual([first.Parent, second.Parent]);
+    });
+});

package/readModels/rootReadModelTypes.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { type Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
+import { getProjectionMetadata } from '../projections/declarative/projection.js';
+import { ProjectionBuilderFor } from '../projections/declarative/ProjectionBuilderFor.js';
+import type { IProjectionFor } from '../projections/declarative/IProjectionFor.js';
+import type { ChildrenDefinitionLike } from '../projections/modelBound/childrenAndNestedBuilder.js';
+import { getChildrenFromMetadata } from '../projections/modelBound/childrenFrom.js';
+import { resolveChildElementType, resolveNestedType } from '../projections/modelBound/childrenAndNestedBuilder.js';
+import { isNested } from '../projections/modelBound/nested.js';
+import { getReducerMetadata } from '../reducers/reducer.js';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
+
+/** Excludes models used as children or nested objects from root projection registration. */
+export function rootReadModelTypes(artifacts: IClientArtifactsProvider): Constructor[] {
+    const models = artifacts.readModels;
+    const usedAsChildren = new Set<Function>();
+    const visited = new Set<Function>();
+    const inspect = (type: Function): void => {
+        if (visited.has(type)) return;
+        visited.add(type);
+        for (const property of TypeIntrospector.getTrackedProperties(type)) {
+            const child = getChildrenFromMetadata(type.prototype, property).length > 0;
+            const nested = isNested(type.prototype, property);
+            if (!child && !nested) continue;
+            const referenced = child ? resolveChildElementType(type, property) : resolveNestedType(type, property);
+            if (referenced && referenced !== type && referenced !== Array && referenced !== Object) {
+                usedAsChildren.add(referenced);
+                inspect(referenced);
+            }
+        }
+    };
+    for (const type of models) inspect(type);
+    const inspectDeclarative = (type: Function, definitions: { children: Record<string, ChildrenDefinitionLike>; nested: Record<string, ChildrenDefinitionLike> }): void => {
+        for (const [property, definition] of Object.entries(definitions.children)) {
+            const referenced = resolveChildElementType(type, property);
+            if (!referenced) continue;
+            if (referenced !== type) usedAsChildren.add(referenced);
+            inspect(referenced);
+            inspectDeclarative(referenced, { children: definition.Children, nested: definition.Nested });
+        }
+        for (const [property, definition] of Object.entries(definitions.nested)) {
+            const referenced = resolveNestedType(type, property);
+            if (!referenced) continue;
+            if (referenced !== type) usedAsChildren.add(referenced);
+            inspect(referenced);
+            inspectDeclarative(referenced, { children: definition.Children, nested: definition.Nested });
+        }
+    };
+    for (const type of artifacts.projections) {
+        const model = getProjectionMetadata(type)?.readModelType;
+        if (!model) continue;
+        inspect(model);
+        const builder = new ProjectionBuilderFor<unknown>();
+        (new type() as IProjectionFor<unknown>).define(builder);
+        inspectDeclarative(model, builder.getSubobjectDefinitions());
+    }
+    for (const type of artifacts.reducers) {
+        const model = getReducerMetadata(type)?.readModel;
+        if (model) inspect(model);
+    }
+    return models.filter(type => !usedAsChildren.has(type));
+}