@cratis/chronicle 6.9.1 → 6.11.0

package/projections/Projections.ts

@@ -20,10 +20,12 @@ import { toObserverRunningState } from '../observation/toObserverRunningState.js
 import { getReadModelMetadata } from '../readModels/index.js';
 import { getReadModelId } from '../readModels/readModel.js';
 import { assertUniqueReadModelIds } from '../readModels/assertUniqueReadModelIds.js';
+import { rootReadModelTypes } from '../readModels/rootReadModelTypes.js';
 import { JsonSchemaGenerator } from '../schemas/index.js';
 import { TypeIntrospector } from '../types/index.js';
 import { hasModelBoundProperties } from '../types/TypeDiscoverer.js';
 import { IProjections } from './IProjections.js';
+import { constantValueExpression } from './constantValueExpression.js';
 import { getProjectionMetadata } from './declarative/projection.js';
 import { ProjectionBuilderFor } from './declarative/ProjectionBuilderFor.js';
 import type { IProjectionFor } from './declarative/IProjectionFor.js';
@@ -101,7 +103,7 @@ export class Projections implements IProjections {
         this._modelBound.clear();
 
         const declarativeTypes = this._clientArtifacts.projections;
-        const readModelTypes = this._clientArtifacts.readModels;
+        const readModelTypes = rootReadModelTypes(this._clientArtifacts);
         this._logger.debug('Discovering projections', { declarativeCount: declarativeTypes.length, readModelCount: readModelTypes.length });
 
         for (const type of declarativeTypes) {
@@ -143,7 +145,7 @@ export class Projections implements IProjections {
         const inferred = this._clientArtifacts.projections
             .map(type => getProjectionMetadata(type)?.readModelType)
             .filter((type): type is Constructor => type !== undefined);
-        assertUniqueReadModelIds([...this._clientArtifacts.readModels, ...inferred]);
+        assertUniqueReadModelIds([...rootReadModelTypes(this._clientArtifacts), ...inferred]);
         const builtProjections: BuiltProjection[] = [
             ...Array.from(this._declarative.values()).map(type => this.buildDeclarativeDefinition(type)),
             ...Array.from(this._modelBound.values()).map(type => this.buildModelBoundDefinition(type))
@@ -396,7 +398,7 @@ export class Projections implements IProjections {
 
     private getReadModelSchema(readModelIdentifier: string): string {
         const types = [
-            ...this._clientArtifacts.readModels,
+            ...rootReadModelTypes(this._clientArtifacts),
             ...this._clientArtifacts.projections
                 .map(projectionType => getProjectionMetadata(projectionType)?.readModelType)
                 .filter((type): type is Constructor => type !== undefined)
@@ -457,7 +459,7 @@ export class Projections implements IProjections {
             return undefined;
         }
 
-        const matchingReadModels = this._clientArtifacts.readModels
+        const matchingReadModels = rootReadModelTypes(this._clientArtifacts)
             .map(type => ({ type, metadata: getReadModelMetadata(type) }))
             .filter(candidate => candidate.metadata)
             .filter(candidate => {
@@ -496,7 +498,7 @@ export class Projections implements IProjections {
                 Key: eventType,
                 Value: {
                     Properties: {},
-                    Key: fromEvent.constantKey ?? fromEvent.key ?? '$eventSourceId',
+                    Key: fromEvent.constantKey ? constantValueExpression(fromEvent.constantKey) : (fromEvent.key ?? '$eventSourceId'),
                     ParentKey: fromEvent.parentKey ?? ''
                 }
             });
@@ -525,7 +527,7 @@ export class Projections implements IProjections {
 
             for (const mapping of getJoinMetadata(prototype, property)) {
                 const entry = this.ensureJoinEntry(joinByEventType, mapping.eventType);
-                entry.Value.On = mapping.on ?? entry.Value.On;
+                entry.Value.On = mapping.on ?? (entry.Value.On || property);
                 entry.Value.Properties[property] = mapping.eventPropertyName ?? property;
             }
 
@@ -652,7 +654,7 @@ export class Projections implements IProjections {
                 Key: eventType,
                 Value: {
                     Properties: {},
-                    Key: fromEvent.constantKey ?? fromEvent.key ?? '$eventSourceId',
+                    Key: fromEvent.constantKey ? constantValueExpression(fromEvent.constantKey) : (fromEvent.key ?? '$eventSourceId'),
                     ParentKey: fromEvent.parentKey ?? ''
                 }
             });

package/projections/constantValueExpression.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { constantValueExpression } from './constantValueExpression.js';
+
+describe('constantValueExpression', () => {
+    it.each([
+        [true, '$value(true)'],
+        [false, '$value(false)'],
+        [42, '$value(42)'],
+        [-1.5, '$value(-1.5)'],
+        ['on-loan', '$value(on-loan)'],
+        ['å', '$value(å)'],
+        ['', '$value()'],
+        [new Date('2025-01-02T03:04:05.006Z'), '$value(2025-01-02T03:04:05.006Z)'],
+        [null, '$null'],
+        [undefined, '$null'],
+        [{ value: 'wrapped' }, '$value(wrapped)'],
+        [{ value: { value: 17 } }, '$value(17)'],
+        [{ value: null }, '$null'],
+        ['$null', '$null'],
+        ['$value(already)', '$value(already)']
+    ])('should encode %s as %s', (value, expression) => {
+        expect(constantValueExpression(value)).toBe(expression);
+    });
+
+    it.each(['a(b)', 'a,b', 'a\nb', '$bad', 'a)', '$value(a,b)', '$value(a(b))', '$value(a', '$value(a)garbage'])('rejects unsupported characters in %s', value => {
+        expect(() => constantValueExpression(value)).toThrow(/unsupported by the kernel/);
+    });
+});

package/projections/constantValueExpression.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Converts a constant to the projection expression understood by the Chronicle kernel. */
+export function constantValueExpression(value: unknown): string {
+    if (value === null || value === undefined) {
+        return '$null';
+    }
+
+    if (value instanceof Date) {
+        return `$value(${value.toISOString()})`;
+    }
+
+    if (typeof value === 'object' && 'value' in value) {
+        return constantValueExpression(value.value);
+    }
+
+    const text = String(value);
+    if (text === '$null') return text;
+    const wrapped = text.startsWith('$value(');
+    const content = wrapped && text.endsWith(')') ? text.slice(7, -1) : text;
+    // ValueExpressionResolver accepts only word characters, spaces, and ._/:*+-.
+    // .NET's \w also accepts Unicode letters, non-spacing marks, decimal digits and connector punctuation.
+    if ((wrapped && !text.endsWith(')')) || !/^[\p{L}\p{Mn}\p{Nd}\p{Pc} ._/:*+-]*$/u.test(content)) {
+        throw new Error(`Constant value '${text}' contains characters unsupported by the kernel's $value expression.`);
+    }
+    return wrapped ? text : `$value(${text})`;
+}

package/projections/declarative/ChildrenBuilder.spec.ts

@@ -36,10 +36,12 @@ eventType()(WholeLineReceived);
 class OrderLine {
     productId!: string;
     quantity!: number;
+    summary!: OrderSummary | undefined;
 }
 
 class OrderSummary {
     total!: number;
+    details!: OrderSummary | undefined;
 }
 
 class Order {
@@ -59,6 +61,8 @@ interface ChildrenDefinition {
     From: FromRecord[];
     RemovedWith: Array<{ Key: { Id: string } }>;
     FromEventProperty?: { Event: { Id: string } | undefined; PropertyExpression: string };
+    Nested: Record<string, ChildrenDefinition>;
+    Join: Array<{ Value: { On: string } }>;
 }
 
 interface BuiltDefinition {
@@ -68,6 +72,21 @@ interface BuiltDefinition {
 }
 
 describe('ChildrenBuilder and NestedBuilder', () => {
+    it('resolves a child join after identifiedBy is configured', () => {
+        const builder = new ProjectionBuilderFor<Order>();
+        builder.children<OrderLine>(order => order.lines, child => child
+            .join(LineAdded, join => join.set(line => line.quantity).to(event => event.quantity))
+            .identifiedBy(line => line.productId));
+        const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+        expect(definition.Children.lines.Join[0].Value.On).toBe('productId');
+    });
+
+    it('rejects a root join without on at build time', () => {
+        const builder = new ProjectionBuilderFor<Order>();
+        expect(() => builder.join(LineAdded)).not.toThrow();
+        expect(() => builder.build('order', 'Order')).toThrow("A join with event 'LineAdded' requires an on property.");
+    });
+
     describe('when using children on the top-level builder', () => {
         it('should produce a children definition keyed by the target property', () => {
             const builder = new ProjectionBuilderFor<Order>();
@@ -94,12 +113,26 @@ describe('ChildrenBuilder and NestedBuilder', () => {
             const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
             const summaryDefinition = definition.Nested.summary;
 
+            expect(summaryDefinition.IdentifiedBy).toBe('*NotSet*');
             const fromEntry = summaryDefinition.From.find(candidate => candidate.Key.Id === 'SummaryUpdated')!;
             expect(fromEntry.Value.Properties.total).toBe('total');
             expect(summaryDefinition.RemovedWith[0].Key.Id).toBe('SummaryCleared');
         });
     });
 
+    describe('when nesting within a child or nested definition', () => {
+        it('should mark every nested definition as not identified by a property', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.children<OrderLine>(order => order.lines, child => child
+                .nested<OrderSummary>(line => line.summary, nested => nested
+                    .nested<OrderSummary>(summary => summary.details, () => {})));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            expect(definition.Children.lines.Nested.summary.IdentifiedBy).toBe('*NotSet*');
+            expect(definition.Children.lines.Nested.summary.Nested.details.IdentifiedBy).toBe('*NotSet*');
+        });
+    });
+
     describe('when using addChild with a builder callback', () => {
         it('should produce a children definition keyed by identifiedBy and usingKey', () => {
             const builder = new ProjectionBuilderFor<Order>();
@@ -132,7 +165,7 @@ describe('ChildrenBuilder and NestedBuilder', () => {
     describe('when using addChild on a join builder', () => {
         it('should produce a children definition from the join clause', () => {
             const builder = new ProjectionBuilderFor<Order>();
-            builder.join(WholeLineReceived, join => join.addChild<OrderLine>(order => order.lines, child => child
+            builder.join(WholeLineReceived, join => join.on(order => order.id).addChild<OrderLine>(order => order.lines, child => child
                 .identifiedBy(line => line.productId)));
 
             const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
@@ -143,6 +176,18 @@ describe('ChildrenBuilder and NestedBuilder', () => {
         });
     });
 
+    describe('when joining from a child projection', () => {
+        it('should use the child identifier when on is omitted', () => {
+            const builder = new ProjectionBuilderFor<Order>();
+            builder.children<OrderLine>(order => order.lines, child => child
+                .identifiedBy(line => line.productId)
+                .join(LineAdded, join => join.set(line => line.quantity).to(event => event.quantity)));
+
+            const definition = builder.build('order', 'Order') as unknown as BuiltDefinition;
+            expect(definition.Children.lines.Join[0].Value.On).toBe('productId');
+        });
+    });
+
     describe('when using setThisValue on a from builder', () => {
         it('should map the whole event property onto the $this well-known expression', () => {
             const builder = new ProjectionBuilderFor<Order>();

package/projections/declarative/ChildrenBuilder.ts

@@ -67,11 +67,17 @@ export class ChildrenBuilder<TParentReadModel, TChildReadModel>
         return this;
     }
 
+    /** @inheritdoc */
+    protected defaultJoinOn(): string | undefined {
+        return this._identifiedBy;
+    }
+
     /**
      * Builds the {@link ChildrenDefinitionLike} representing this children collection.
      * @returns The accumulated children definition.
      */
     buildDefinition(): ChildrenDefinitionLike {
+        this.resolveJoins();
         return {
             IdentifiedBy: this._identifiedBy ?? '$eventSourceId',
             From: this._from,

package/projections/declarative/FromBuilder.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { constantValueExpression } from '../constantValueExpression.js';
 import { AddBuilder } from './AddBuilder.js';
 import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder.js';
 import { CompositeKeyBuilder } from './CompositeKeyBuilder.js';
@@ -98,13 +99,13 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
 
     /** @inheritdoc */
     usingConstantKey(value: string): this {
-        this.entry.key = value;
+        this.entry.key = constantValueExpression(value);
         return this;
     }
 
     /** @inheritdoc */
     usingConstantParentKey(value: string): this {
-        this.entry.parentKey = value;
+        this.entry.parentKey = constantValueExpression(value);
         return this;
     }
 

package/projections/declarative/JoinBuilder.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import { constantValueExpression } from '../constantValueExpression.js';
 import { AddBuilder } from './AddBuilder.js';
 import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder.js';
 import { CompositeKeyBuilder } from './CompositeKeyBuilder.js';
@@ -106,7 +107,7 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
 
     /** @inheritdoc */
     usingConstantKey(value: string): this {
-        this.entry.key = value;
+        this.entry.key = constantValueExpression(value);
         return this;
     }
 

package/projections/declarative/NestedBuilder.ts

@@ -6,6 +6,7 @@ import { ChildrenDefinitionLike, ProjectionBuilderCore } from './ProjectionBuild
 import { IChildrenBuilder } from './IChildrenBuilder.js';
 import { INestedBuilder } from './INestedBuilder.js';
 import { ChildrenBuilder } from './ChildrenBuilder.js';
+import { notSetPropertyPath } from '../notSetPropertyPath.js';
 
 /**
  * Concrete implementation of {@link INestedBuilder}, building the `ChildrenDefinition` for a
@@ -61,8 +62,9 @@ export class NestedBuilder<TParentReadModel, TNestedReadModel>
      * @returns The accumulated nested definition.
      */
     buildDefinition(): ChildrenDefinitionLike {
+        this.resolveJoins();
         return {
-            IdentifiedBy: '',
+            IdentifiedBy: notSetPropertyPath,
             From: this._from,
             Join: this._join,
             Children: this._children,

package/projections/declarative/ProjectionBuilderCore.ts

@@ -73,6 +73,7 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
     protected _initialState: string = '{}';
     protected readonly _from: FromRecord[] = [];
     protected readonly _join: JoinRecord[] = [];
+    private readonly _joinEventNames = new Map<JoinRecord, string>();
     protected readonly _removedWith: RemovedWithRecord[] = [];
     protected readonly _removedWithJoin: RemovedWithJoinRecord[] = [];
     protected readonly _children: Record<string, ChildrenDefinitionLike> = {};
@@ -129,14 +130,16 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
         const contractType = this.toContractEventType(eventType);
         const joinBuilder = new JoinBuilder<TReadModel, TEvent>();
         builderCallback?.(joinBuilder);
-        this._join.push({
+        const record: JoinRecord = {
             Key: contractType,
             Value: {
                 On: joinBuilder.entry.on,
                 Properties: joinBuilder.entry.properties,
                 Key: joinBuilder.entry.key
             }
-        });
+        };
+        this._join.push(record);
+        this._joinEventNames.set(record, eventType.name);
         this.mergeChildAdditions(contractType, joinBuilder.entry.children);
         return this as unknown as TBuilder;
     }
@@ -191,6 +194,21 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
         return this as unknown as TBuilder;
     }
 
+    /** Resolves join defaults once the entire projection (including identifiedBy) is configured. */
+    protected resolveJoins(): void {
+        for (const record of this._join) {
+            record.Value.On ||= this.defaultJoinOn() ?? '';
+            if (!record.Value.On) {
+                throw new Error(`A join with event '${this._joinEventNames.get(record)}' requires an on property.`);
+            }
+        }
+    }
+
+    /** Returns a default join-on path for children, if one is available. */
+    protected defaultJoinOn(): string | undefined {
+        return undefined;
+    }
+
     /**
      * Creates an empty {@link ChildrenDefinitionLike} accumulator for a children/nested entry.
      * @returns A fresh, empty children definition.

package/projections/declarative/ProjectionBuilderFor.spec.ts

@@ -28,6 +28,10 @@ class Inventory {
     removedTotal!: number;
     thingsHappenedCount!: number;
     countsByEventType!: Record<string, number>;
+    active!: boolean;
+    status!: string;
+    started!: Date;
+    cleared!: string | null;
     incrementsByEventType!: Record<string, number>;
     decrementsByEventType!: Record<string, number>;
 }
@@ -81,14 +85,48 @@ describe('ProjectionBuilderFor', () => {
             const entry = definition.From.find(candidate => candidate.Key.Id === 'ThingHappened')!;
 
             expect(entry.Value.Properties.thingsHappenedCount).toBe('$count');
-            expect(entry.Value.Key).toBe('singleton');
+            expect(entry.Value.Key).toBe('$value(singleton)');
+        });
+    });
+
+    describe('when setting constants on a from builder', () => {
+        it('should encode constants as value expressions and null as a clear', () => {
+            const builder = new ProjectionBuilderFor<Inventory>();
+            builder.from(ThingHappened, from => {
+                from.set(model => model.active).toValue(true);
+                from.set(model => model.status).toValue('on-loan');
+                from.set(model => model.total).toValue(2.5);
+                from.set(model => model.started).toValue(new Date('2025-01-02T03:04:05.006Z'));
+                from.set(model => model.cleared).toValue(null);
+                from.set(model => model.id).toValue({ value: 'wrapped' });
+                from.setThisValue().toValue('whole');
+            });
+
+            const definition = builder.build('inventory', 'Inventory') as unknown as { From: FromRecord[] };
+            expect(definition.From[0].Value.Properties).toMatchObject({
+                active: '$value(true)',
+                status: '$value(on-loan)',
+                total: '$value(2.5)',
+                started: '$value(2025-01-02T03:04:05.006Z)',
+                cleared: '$null',
+                id: '$value(wrapped)',
+                $this: '$value(whole)'
+            });
+        });
+
+        it('should encode constant keys and parent keys as expressions', () => {
+            const builder = new ProjectionBuilderFor<Inventory>();
+            builder.from(ThingHappened, from => from.usingConstantKey('singleton').usingConstantParentKey('parent'));
+            const definition = builder.build('inventory', 'Inventory') as unknown as { From: Array<{ Value: { Key: string; ParentKey: string } }> };
+            expect(definition.From[0].Value.Key).toBe('$value(singleton)');
+            expect(definition.From[0].Value.ParentKey).toBe('$value(parent)');
         });
     });
 
     describe('when using add on a join builder', () => {
         it('should produce a $add expression targeting the event property', () => {
             const builder = new ProjectionBuilderFor<Inventory>();
-            builder.join(ItemAdded, join => join.add(model => model.total).with(event => event.quantity));
+            builder.join(ItemAdded, join => join.on(model => model.id).add(model => model.total).with(event => event.quantity));
 
             const definition = builder.build('inventory', 'Inventory') as unknown as { Join: JoinRecord[] };
             const entry = definition.Join.find(candidate => candidate.Key.Id === 'ItemAdded')!;
@@ -97,10 +135,20 @@ describe('ProjectionBuilderFor', () => {
         });
     });
 
+    describe('when setting a constant on a join builder', () => {
+        it('should send a value expression for the property and key', () => {
+            const builder = new ProjectionBuilderFor<Inventory>();
+            builder.join(ItemAdded, join => join.on(model => model.id).usingConstantKey('singleton').set(model => model.status).toValue('on-loan'));
+            const definition = builder.build('inventory', 'Inventory') as unknown as { Join: Array<{ Value: { Key: string; Properties: Record<string, string> } }> };
+            expect(definition.Join[0].Value.Key).toBe('$value(singleton)');
+            expect(definition.Join[0].Value.Properties.status).toBe('$value(on-loan)');
+        });
+    });
+
     describe('when using subtract on a join builder', () => {
         it('should produce a $subtract expression targeting the event property', () => {
             const builder = new ProjectionBuilderFor<Inventory>();
-            builder.join(ItemRemoved, join => join.subtract(model => model.removedTotal).with(event => event.quantity));
+            builder.join(ItemRemoved, join => join.on(model => model.id).subtract(model => model.removedTotal).with(event => event.quantity));
 
             const definition = builder.build('inventory', 'Inventory') as unknown as { Join: JoinRecord[] };
             const entry = definition.Join.find(candidate => candidate.Key.Id === 'ItemRemoved')!;
@@ -112,7 +160,7 @@ describe('ProjectionBuilderFor', () => {
     describe('when using count on a join builder', () => {
         it('should produce a $count expression', () => {
             const builder = new ProjectionBuilderFor<Inventory>();
-            builder.join(ThingHappened, join => join.count(model => model.thingsHappenedCount));
+            builder.join(ThingHappened, join => join.on(model => model.id).count(model => model.thingsHappenedCount));
 
             const definition = builder.build('inventory', 'Inventory') as unknown as { Join: JoinRecord[] };
             const entry = definition.Join.find(candidate => candidate.Key.Id === 'ThingHappened')!;
@@ -121,6 +169,15 @@ describe('ProjectionBuilderFor', () => {
         });
     });
 
+    describe('when joining without an on property', () => {
+        it('should reject a definition that the kernel cannot convert', () => {
+            const builder = new ProjectionBuilderFor<Inventory>();
+            builder.join(ThingHappened, join => join.count(model => model.thingsHappenedCount));
+            expect(() => builder.build('inventory', 'Inventory'))
+                .toThrow("A join with event 'ThingHappened' requires an on property.");
+        });
+    });
+
     describe('when using count with event context property on fromEvery', () => {
         it('should produce a $count expression with dictionary key from event context', () => {
             const builder = new ProjectionBuilderFor<Inventory>();

package/projections/declarative/ProjectionBuilderFor.ts

@@ -4,6 +4,7 @@
 import { AutoMap } from '@cratis/chronicle.contracts';
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { EventSequenceId } from '../../eventSequences/EventSequenceId.js';
+import type { ChildrenDefinitionLike } from '../modelBound/childrenAndNestedBuilder.js';
 import { ChildrenBuilder } from './ChildrenBuilder.js';
 import { IChildrenBuilder } from './IChildrenBuilder.js';
 import { INestedBuilder } from './INestedBuilder.js';
@@ -120,6 +121,11 @@ export class ProjectionBuilderFor<TReadModel> extends ProjectionBuilderCore<TRea
         return this;
     }
 
+    /** Names of children and nested members configured by declarative builders. */
+    getSubobjectDefinitions(): { children: Record<string, ChildrenDefinitionLike>; nested: Record<string, ChildrenDefinitionLike> } {
+        return { children: this._children, nested: this._nested };
+    }
+
     /**
      * Builds the contract-compatible projection definition payload.
      * @param identifier - The projection identifier.
@@ -127,6 +133,7 @@ export class ProjectionBuilderFor<TReadModel> extends ProjectionBuilderCore<TRea
      * @returns The projection definition object ready to send to the kernel.
      */
     build(identifier: string, readModelName: string): Record<string, unknown> {
+        this.resolveJoins();
         const definition: Record<string, unknown> = {
             EventSequenceId: this._eventSequenceId,
             Identifier: identifier,

package/projections/declarative/SetBuilder.ts

@@ -3,6 +3,7 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { ISetBuilder } from './ISetBuilder.js';
+import { constantValueExpression } from '../constantValueExpression.js';
 
 /**
  * Concrete implementation of {@link ISetBuilder} that records the property mapping
@@ -28,7 +29,7 @@ export class SetBuilder<TEvent, TParentBuilder> implements ISetBuilder<TEvent, T
 
     /** @inheritdoc */
     toValue<TProperty>(value: TProperty): TParentBuilder {
-        this._setProperty(this._readModelProperty, JSON.stringify(value));
+        this._setProperty(this._readModelProperty, constantValueExpression(value));
         return this._parent;
     }
 

package/projections/modelBound/addFrom.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 addFrom property decorator. */
 export interface AddFromMetadata {
@@ -22,7 +23,7 @@ const METADATA_KEY = 'chronicle:projection:addFrom';
  * @returns A property decorator.
  */
 export function addFrom(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: AddFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];

package/projections/modelBound/childrenAndNestedBuilder.ts

@@ -5,6 +5,8 @@ import 'reflect-metadata';
 import { AutoMap } from '@cratis/chronicle.contracts';
 import { Constructor, Fields } from '@cratis/fundamentals';
 import { TypeIntrospector } from '../../types/index.js';
+import { constantValueExpression } from '../constantValueExpression.js';
+import { notSetPropertyPath } from '../notSetPropertyPath.js';
 import { getEventTypeFor } from '../../events/eventTypeDecorator.js';
 import { getAddFromMetadata } from './addFrom.js';
 import { ChildrenFromMetadata, getChildrenFromMetadata } from './childrenFrom.js';
@@ -110,7 +112,7 @@ export function applyPropertyMappings(prototype: object, property: string, fromB
 
     for (const mapping of getSetValueMetadata(prototype, property)) {
         const entry = ensureFromEntry(fromByEventType, mapping.eventType);
-        entry.Value.Properties[property] = JSON.stringify(mapping.value);
+        entry.Value.Properties[property] = constantValueExpression(mapping.value);
     }
 
     for (const mapping of getAddFromMetadata(prototype, property)) {
@@ -127,7 +129,7 @@ export function applyPropertyMappings(prototype: object, property: string, fromB
         const entry = ensureFromEntry(fromByEventType, mapping.eventType);
         entry.Value.Properties[property] = '$increment';
         if (mapping.constantKey) {
-            entry.Value.Key = `$value(${mapping.constantKey})`;
+            entry.Value.Key = constantValueExpression(mapping.constantKey);
         }
     }
 
@@ -135,7 +137,7 @@ export function applyPropertyMappings(prototype: object, property: string, fromB
         const entry = ensureFromEntry(fromByEventType, mapping.eventType);
         entry.Value.Properties[property] = '$decrement';
         if (mapping.constantKey) {
-            entry.Value.Key = `$value(${mapping.constantKey})`;
+            entry.Value.Key = constantValueExpression(mapping.constantKey);
         }
     }
 
@@ -143,7 +145,7 @@ export function applyPropertyMappings(prototype: object, property: string, fromB
         const entry = ensureFromEntry(fromByEventType, mapping.eventType);
         entry.Value.Properties[property] = '$count';
         if (mapping.constantKey) {
-            entry.Value.Key = `$value(${mapping.constantKey})`;
+            entry.Value.Key = constantValueExpression(mapping.constantKey);
         }
     }
 }
@@ -164,17 +166,17 @@ function createEmptyChildrenDefinition(): ChildrenDefinitionLike {
 
 /**
  * Resolves the element type of a `@childrenFrom` collection property. TypeScript erases
- * generic type arguments at runtime, so the element type can only be recovered when the
- * property was declared with `@field(Array, { genericArguments: [ItemType] })` - without it,
+ * generic type arguments at runtime, so the element type must be supplied by @childrenFrom
+ * or `@field(Array, { genericArguments: [ItemType] })` - without it,
  * the children definition still registers correctly (structural Key/ParentKey wiring plus
  * AutoMap), it just cannot also translate the child type's own decorators.
  * @param type - The declaring class constructor.
  * @param property - The property name.
  * @returns The child element type constructor, or undefined when it cannot be resolved.
  */
-function resolveChildElementType(type: Function, property: string): Function | undefined {
+export function resolveChildElementType(type: Function, property: string): Function | undefined {
     const field = Fields.getFieldsForType(type as Constructor).find(candidate => candidate.name === property);
-    return field?.genericArguments?.[0];
+    return getChildrenFromMetadata(type.prototype, property).find(metadata => metadata.childType)?.childType ?? field?.genericArguments?.[0];
 }
 
 /**
@@ -185,7 +187,7 @@ function resolveChildElementType(type: Function, property: string): Function | u
  * @param property - The property name.
  * @returns The nested type constructor, or undefined when it cannot be resolved.
  */
-function resolveNestedType(type: Function, property: string): Function | undefined {
+export function resolveNestedType(type: Function, property: string): Function | undefined {
     const field = Fields.getFieldsForType(type as Constructor).find(candidate => candidate.name === property);
     if (field?.type && field.type !== Object && field.type !== Array) {
         return field.type;
@@ -196,7 +198,8 @@ function resolveNestedType(type: Function, property: string): Function | undefin
         return designType;
     }
 
-    return undefined;
+    const inferred = TypeIntrospector.getMembers(type).get(property);
+    return inferred && inferred !== Object && inferred !== Array ? inferred : undefined;
 }
 
 /**
@@ -340,7 +343,7 @@ export function buildChildrenEntry(type: Function, property: string, metadataLis
 export function buildNestedEntry(type: Function, property: string): ChildrenDefinitionLike {
     const nestedType = resolveNestedType(type, property);
     const definition = createEmptyChildrenDefinition();
-    definition.IdentifiedBy = '';
+    definition.IdentifiedBy = notSetPropertyPath;
 
     // A @clearWith on the property carrying @nested clears this nested object, the same as a
     // class-level @clearWith on the nested type itself (which populateFromType also honors).