@cratis/chronicle 6.16.1 → 6.18.0

package/projections/declarative/AddChildBuilder.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 { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 import { IAddChildBuilder } from './IAddChildBuilder.js';
 
 /**
@@ -14,8 +15,10 @@ export interface ChildAdditionEntry {
     targetProperty: string;
     /** The child model property used to identify instances, when set via the builder callback overload. */
     identifiedBy?: string;
-    /** The event property used as the key, when set via the builder callback overload. */
+    /** The event property or context expression used as the key, when set via the builder callback overload. */
     usingKey?: string;
+    /** The event context expression used as the parent key, when set via the builder callback overload. */
+    usingParentKey?: string;
     /** The event property whose value becomes the child directly, when set via the plain accessor overload. */
     fromEventProperty?: string;
 }
@@ -36,8 +39,9 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
     private _usedAsBuilder = false;
     private _identifiedByProperty: string | undefined;
     private _usingKeyProperty: string | undefined;
+    private _usingParentKeyProperty: string | undefined;
 
-    /** Whether any builder member (`identifiedBy`/`usingKey`) was invoked on the probe. */
+    /** Whether any builder member (`identifiedBy`, `usingKey`, `usingKeyFromContext`, or `usingParentKeyFromContext`) was invoked on the probe. */
     get usedAsBuilder(): boolean {
         return this._usedAsBuilder;
     }
@@ -52,6 +56,11 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         return this._usingKeyProperty;
     }
 
+    /** The parent key expression captured via `usingParentKeyFromContext()`, if any. */
+    get usingParentKeyProperty(): string | undefined {
+        return this._usingParentKeyProperty;
+    }
+
     /** The event property path captured when the probe was used as a plain accessor. */
     get capturedEventProperty(): string {
         return this._pathHandler.property;
@@ -77,10 +86,26 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         return this;
     }
 
+    /** @inheritdoc */
+    usingKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent> {
+        this._usingKeyProperty = eventContextPropertyExpression(contextPropertyName);
+        this._usedAsBuilder = true;
+        return this;
+    }
+
+    /** @inheritdoc */
+    usingParentKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent> {
+        this._usingParentKeyProperty = eventContextPropertyExpression(contextPropertyName);
+        this._usedAsBuilder = true;
+        return this;
+    }
+
     /**
      * Proxy `get` trap: known builder members dispatch to the real implementation above;
      * anything else (a plain event property accessed by the accessor overload) falls through
      * to path-capturing so the accessor overload keeps working against the same probe.
+     * The builder member names are therefore reserved: an event property with one of these names
+     * cannot be selected through the accessor overload.
      * @param _target - The proxy's (unused) empty target object.
      * @param prop - The accessed property name.
      * @returns The resolved member.
@@ -92,6 +117,12 @@ export class AddChildBuilder<TChildModel, TEvent> implements IAddChildBuilder<TC
         if (prop === 'usingKey') {
             return this.usingKey.bind(this);
         }
+        if (prop === 'usingKeyFromContext') {
+            return this.usingKeyFromContext.bind(this);
+        }
+        if (prop === 'usingParentKeyFromContext') {
+            return this.usingParentKeyFromContext.bind(this);
+        }
         return Reflect.get(this._pathProxy as object, prop);
     }
 }

package/projections/declarative/FromBuilder.ts

@@ -15,6 +15,7 @@ import { ISetBuilder } from './ISetBuilder.js';
 import { ISubtractBuilder } from './ISubtractBuilder.js';
 import { SetBuilder } from './SetBuilder.js';
 import { SubtractBuilder } from './SubtractBuilder.js';
+import { recordKeyDeclaration } from './projectionBuilderProvenance.js';
 
 /**
  * Accumulated property mapping for a from clause.
@@ -58,12 +59,14 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         const proxy = new Proxy({}, handler);
         keyAccessor(proxy as TEvent);
         this.entry.key = handler.property;
+        recordKeyDeclaration(this, 'Key', '.from().usingKey');
         return this;
     }
 
     /** @inheritdoc */
     usingKeyFromContext(contextPropertyName: string): this {
         this.entry.key = eventContextPropertyExpression(contextPropertyName);
+        recordKeyDeclaration(this, 'Key', '.from().usingKeyFromContext');
         return this;
     }
 
@@ -73,12 +76,14 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         const proxy = new Proxy({}, handler);
         keyAccessor(proxy as TEvent);
         this.entry.parentKey = handler.property;
+        recordKeyDeclaration(this, 'ParentKey', '.from().usingParentKey');
         return this;
     }
 
     /** @inheritdoc */
     usingParentKeyFromContext(contextPropertyName: string): this {
         this.entry.parentKey = eventContextPropertyExpression(contextPropertyName);
+        recordKeyDeclaration(this, 'ParentKey', '.from().usingParentKeyFromContext');
         return this;
     }
 
@@ -87,6 +92,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         const compositeKeyBuilder = new CompositeKeyBuilder<TKeyType, TEvent>();
         builderCallback(compositeKeyBuilder);
         this.entry.key = compositeKeyBuilder.build();
+        recordKeyDeclaration(this, 'Key', '.from().usingCompositeKey');
         return this;
     }
 
@@ -95,18 +101,21 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         const compositeKeyBuilder = new CompositeKeyBuilder<TKeyType, TEvent>();
         builderCallback(compositeKeyBuilder);
         this.entry.parentKey = compositeKeyBuilder.build();
+        recordKeyDeclaration(this, 'ParentKey', '.from().usingParentCompositeKey');
         return this;
     }
 
     /** @inheritdoc */
     usingConstantKey(value: string): this {
         this.entry.key = constantValueExpression(value);
+        recordKeyDeclaration(this, 'Key', '.from().usingConstantKey');
         return this;
     }
 
     /** @inheritdoc */
     usingConstantParentKey(value: string): this {
         this.entry.parentKey = constantValueExpression(value);
+        recordKeyDeclaration(this, 'ParentKey', '.from().usingConstantParentKey');
         return this;
     }
 
@@ -162,6 +171,14 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -175,7 +192,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/IAddChildBuilder.ts

@@ -22,4 +22,18 @@ export interface IAddChildBuilder<TChildModel, TEvent> {
      * @returns This builder for fluent chaining.
      */
     usingKey(eventPropertyAccessor: PropertyAccessor<TEvent>): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
+
+    /**
+     * Specifies an event context property used as the parent key when adding a child.
+     * @param contextPropertyName - Property path on EventContext, using TypeScript casing.
+     * @returns This builder for fluent chaining.
+     */
+    usingParentKeyFromContext(contextPropertyName: string): IAddChildBuilder<TChildModel, TEvent>;
 }

package/projections/declarative/IReadModelPropertiesBuilder.ts

@@ -107,7 +107,24 @@ export interface IReadModelPropertiesBuilder<TReadModel, TEvent, TBuilder> {
     count(readModelPropertyAccessor: PropertyAccessor<TReadModel>): TBuilder;
 
     /**
-     * Adds a child model from the event to a collection property on the read model.
+     * Adds a child model configured through a child builder to a collection on the read model.
+     * Event members remain available while TypeScript resolves the two function-shaped overloads.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param builderCallback - Callback configuring the child identifier and keys.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): TBuilder;
+
+    /**
+     * Adds a child model directly from an event property to a collection on the read model.
+     * @param targetPropertyAccessor - Accessor for the collection property on the read model.
+     * @param eventPropertyAccessor - Accessor for the event property holding the child value.
+     * @returns This builder for fluent chaining.
+     */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): TBuilder;
+
+    /**
+     * Retains support for arbitrary read model accessors and explicitly selected child types.
      * @param targetPropertyAccessor - Accessor for the collection property on the read model.
      * @param eventPropertyAccessorOrBuilderCallback - Either a direct event property accessor or a builder callback.
      * @returns This builder for fluent chaining.

package/projections/declarative/JoinBuilder.ts

@@ -170,6 +170,14 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
     }
 
     /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, builderCallback: (builder: IAddChildBuilder<TChildModel, TEvent> & TEvent) => void): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(targetPropertyAccessor: (model: TReadModel) => readonly TChildModel[] | null | undefined, eventPropertyAccessor: PropertyAccessor<TEvent>): this;
+    /** @inheritdoc */
+    addChild<TChildModel>(
+        targetPropertyAccessor: PropertyAccessor<TReadModel>,
+        eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
+    ): this;
     addChild<TChildModel>(
         targetPropertyAccessor: PropertyAccessor<TReadModel>,
         eventPropertyAccessorOrBuilderCallback: PropertyAccessor<TEvent> | ((builder: IAddChildBuilder<TChildModel, TEvent>) => void)
@@ -183,7 +191,7 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
         (eventPropertyAccessorOrBuilderCallback as (value: unknown) => void)(probeProxy);
 
         this.entry.children.push(probe.usedAsBuilder
-            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty }
+            ? { targetProperty: targetHandler.property, identifiedBy: probe.identifiedByProperty, usingKey: probe.usingKeyProperty, usingParentKey: probe.usingParentKeyProperty }
             : { targetProperty: targetHandler.property, fromEventProperty: probe.capturedEventProperty });
         return this;
     }

package/projections/declarative/ProjectionBuilderCore.ts

@@ -14,6 +14,8 @@ import { FromEveryBuilder } from './FromEveryBuilder.js';
 import { RemovedWithBuilder } from './RemovedWithBuilder.js';
 import { RemovedWithJoinBuilder } from './RemovedWithJoinBuilder.js';
 import { ChildAdditionEntry } from './AddChildBuilder.js';
+import { eventContractPath } from '../eventContractPath.js';
+import { getProjectionBuilderProvenance, recordChildDeclaration, recordFromEveryDeclaration, recordKeyDeclaration } from './projectionBuilderProvenance.js';
 
 /** The contract-level event type identifier shape used across projection definitions. */
 export type ContractEventType = { Id: string; Generation: number; Tombstone: boolean };
@@ -118,6 +120,10 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
                 ParentKey: fromBuilder.entry.parentKey
             }
         });
+        for (const [field, declaration] of getProjectionBuilderProvenance(fromBuilder).keys) {
+            recordKeyDeclaration(this, `${eventContractPath('From', contractType)}.${field}`, declaration);
+        }
+        for (const child of fromBuilder.entry.children) recordChildDeclaration(this, `Children.${child.targetProperty}`, '.from().addChild');
         this.mergeChildAdditions(contractType, fromBuilder.entry.children);
         return this as unknown as TBuilder;
     }
@@ -146,6 +152,7 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
 
     /** @inheritdoc */
     fromEvery(builderCallback: (builder: IFromEveryBuilder<TReadModel>) => void): TBuilder {
+        recordFromEveryDeclaration(this);
         const builder = new FromEveryBuilder<TReadModel>();
         builderCallback(builder);
         this._all = {
@@ -249,7 +256,7 @@ export abstract class ProjectionBuilderCore<TReadModel, TBuilder> {
                 Key: eventType,
                 Value: {
                     Key: child.usingKey ?? '$eventSourceId',
-                    ParentKey: '$eventSourceId',
+                    ParentKey: child.usingParentKey ?? '$eventSourceId',
                     Properties: {}
                 }
             });

package/projections/declarative/addChildCompatibility.standard.spec.ts

@@ -0,0 +1,80 @@
+// 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 { eventType } from '../../events/eventTypeDecorator.js';
+import { FromBuilder } from './FromBuilder.js';
+import { IAddChildBuilder } from './IAddChildBuilder.js';
+import { IReadModelPropertiesBuilder } from './IReadModelPropertiesBuilder.js';
+import { JoinBuilder } from './JoinBuilder.js';
+import { ProjectionBuilderFor } from './ProjectionBuilderFor.js';
+
+class Line {
+    id = '';
+}
+
+class Base {
+    id = '';
+}
+
+class Derived extends Base {
+    derivedId = '';
+}
+
+class LineAdded {
+    line = new Line();
+}
+eventType()(LineAdded);
+
+class Order {
+    id = '';
+    lines: Line[] = [];
+    nullableLines: Line[] | null = null;
+    bases: Base[] = [];
+}
+
+// This checks the shared public interface independently of either concrete builder.
+function acceptOriginalCallSites(builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown>): void {
+    builder.addChild<Line>(model => model.nullableLines, event => event.line);
+    builder.addChild(model => model.nullableLines, child => child.identifiedBy(item => item.id));
+    builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+    builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child
+        .identifiedBy(item => item.derivedId)
+        .usingKeyFromContext('sequenceNumber'));
+    builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+}
+
+describe('addChild source compatibility', () => {
+    it('should accept nullable targets and explicitly narrower child types on the shared interface', () => {
+        const builder: IReadModelPropertiesBuilder<Order, LineAdded, unknown> = new FromBuilder<Order, LineAdded>();
+        acceptOriginalCallSites(builder);
+    });
+
+    it('should accept the original call shapes on the concrete from builder', () => {
+        const builder = new FromBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should accept the original call shapes on the concrete join builder', () => {
+        const builder = new JoinBuilder<Order, LineAdded>();
+        builder.addChild<Line>(model => model.nullableLines, event => event.line);
+        builder.addChild<Derived>(model => model.bases, (child: IAddChildBuilder<Derived, LineAdded>) => child.identifiedBy(item => item.derivedId));
+        builder.addChild<Derived>(model => model.bases, (event: LineAdded) => event.line);
+        builder.addChild<Line>(model => model.lines, (event: LineAdded) => event.line);
+        expect(builder.entry.children).toHaveLength(4);
+    });
+
+    it('should contextually type the unannotated builder callback in the documentation example', () => {
+        const projection = new ProjectionBuilderFor<Order>();
+        projection.from(LineAdded, from => from
+            .addChild(model => model.lines, child => child
+                .identifiedBy(item => item.id)
+                .usingKeyFromContext('sequenceNumber')
+                .usingParentKeyFromContext('eventSourceId')));
+        expect(projection.build('order', 'Order').Children).toHaveProperty('lines');
+    });
+});

package/projections/declarative/projectionBuilderProvenance.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Internal declaration origins; never part of a builder or its published interface. */
+interface BuilderProvenance {
+    fromEvery: boolean;
+    keys: Map<string, string>;
+    children: Map<string, string>;
+}
+
+const declarations = new WeakMap<object, BuilderProvenance>();
+
+function forBuilder(builder: object): BuilderProvenance {
+    let provenance = declarations.get(builder);
+    if (!provenance) {
+        provenance = { fromEvery: false, keys: new Map(), children: new Map() };
+        declarations.set(builder, provenance);
+    }
+    return provenance;
+}
+
+/** Records an explicit key operation on a from builder or projection builder. */
+export function recordKeyDeclaration(builder: object, path: string, declaration: string): void {
+    forBuilder(builder).keys.set(path, declaration);
+}
+
+/** Records a child addition without adding state to the public builder type. */
+export function recordChildDeclaration(builder: object, path: string, declaration: string): void {
+    forBuilder(builder).children.set(path, declaration);
+}
+
+/** Remembers empty fromEvery declarations, which have no wire representation. */
+export function recordFromEveryDeclaration(builder: object): void {
+    forBuilder(builder).fromEvery = true;
+}
+
+/** Reads declaration origins while compiling, before variant lowering. */
+export function getProjectionBuilderProvenance(builder: object): Readonly<BuilderProvenance> {
+    return forBuilder(builder);
+}

package/projections/eventContextExpressions.spec.ts

@@ -182,6 +182,24 @@ describe('event context expressions', () => {
             .From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
     });
 
+    it('should use context properties as addChild keys in a from clause', () => {
+        const child = declarative(builder => builder.from(Recorded, from => from.addChild<Child>(model => model.children, added => added
+            .identifiedBy(model => model.happened)
+            .usingKeyFromContext('sequenceNumber')
+            .usingParentKeyFromContext('eventSourceId'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(SequenceNumber)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
+    });
+
+    it('should use context properties as addChild keys in a join clause', () => {
+        const child = declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred)
+            .addChild<Child>(model => model.children, added => added
+                .usingKeyFromContext('eventSourceId')
+                .usingParentKeyFromContext('sequenceNumber'))));
+        child.Children.children.From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(SequenceNumber)');
+    });
+
     it('should use a context property as a from parent key', () => {
         declarative(builder => builder.from(Recorded, from => from.usingParentKeyFromContext('eventSourceId')))
             .From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
@@ -255,6 +273,8 @@ describe('event context expressions', () => {
         const mappings = [
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingKeyFromContext('missingKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.usingParentKeyFromContext('missingParent')),
+            (builder: ProjectionBuilderFor<Model>) => builder.from(Recorded, from => from.addChild<Child>(model => model.children, child => child.usingKeyFromContext('missingChildKey'))),
+            (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).addChild<Child>(model => model.children, child => child.usingParentKeyFromContext('missingChildParent'))),
             (builder: ProjectionBuilderFor<Model>) => builder.join(Recorded, join => join.on(model => model.occurred).usingKeyFromContext('missingJoinKey')),
             (builder: ProjectionBuilderFor<Model>) => builder.removedWith(Removed, removed => removed.usingKeyFromContext('missingRemovalKey'))
         ];

package/projections/eventContractPath.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ContractEventType } from './declarative/ProjectionBuilderCore.js';
+
+/** Stable, generation-aware path shared by provenance and capability diagnostics. */
+export function eventContractPath(section: string, eventType: ContractEventType): string {
+    return `${section}[${eventType.Id}:${eventType.Generation}]`;
+}

package/projections/modelBound/childrenAndNestedBuilder.ts

@@ -48,6 +48,8 @@ export interface ChildrenDefinitionLike {
     NoAutoMapProperties: string[];
 }
 
+const aggregateExpressions = ['$count', '$increment', '$decrement', '$add', '$subtract'];
+
 /**
  * Resolves the contract event type for a decorated event constructor.
  * @param eventTypeConstructor - The event class constructor.
@@ -209,23 +211,20 @@ export function resolveNestedType(type: Function, property: string): Function |
 
 /**
  * Discovers the child model property used to identify instances, by convention: a property
- * named `id` (case-insensitive), matching the C# client's fallback once no `[Key]` attribute
- * is present (TypeScript has no `[Key]` decorator equivalent).
+ * named `id` (case-insensitive), or a property matching the event key when no id is found.
+ * TypeScript has no `[Key]` decorator equivalent.
  * @param childType - The child/nested model type, when resolvable.
+ * @param eventKey - The configured event key, when present.
  * @returns The discovered property name, or undefined when no convention match is found.
  */
-function discoverIdentifiedBy(childType: Function | undefined): string | undefined {
+function discoverIdentifiedBy(childType: Function | undefined, eventKey: string | undefined): string | undefined {
     if (!childType) {
         return undefined;
     }
 
-    for (const name of TypeIntrospector.getMembers(childType).keys()) {
-        if (name.toLowerCase() === 'id') {
-            return name;
-        }
-    }
-
-    return undefined;
+    const members = [...TypeIntrospector.getMembers(childType).keys()];
+    return members.find(name => name.toLowerCase() === 'id') ??
+        (eventKey !== undefined ? members.find(name => name.toLowerCase() === eventKey.toLowerCase()) : undefined);
 }
 
 /**
@@ -325,7 +324,7 @@ export function buildChildrenEntry(type: Function, property: string, metadataLis
     const definition = createEmptyChildrenDefinition(type, childType);
 
     const explicitIdentifiedBy = metadataList.find(metadata => metadata.identifiedBy)?.identifiedBy;
-    definition.IdentifiedBy = explicitIdentifiedBy ?? discoverIdentifiedBy(childType) ?? '$eventSourceId';
+    definition.IdentifiedBy = explicitIdentifiedBy ?? discoverIdentifiedBy(childType, metadataList[0]?.key) ?? '$eventSourceId';
 
     for (const metadata of metadataList) {
         const eventType = toContractEventType(metadata.eventType);
@@ -340,6 +339,41 @@ export function buildChildrenEntry(type: Function, property: string, metadataLis
     }
 
     populateFromType(definition, childType);
+
+    // For non-aggregate-only creating events, populate an unmapped child identifier from
+    // the creating event's key. IdentifiedBy selects the child property; it is not itself
+    // a property mapping. TypeScript has no [Key] decorator, so an explicit identifiedBy
+    // plays the same role as a discovered id for this default.
+    const identifier = definition.IdentifiedBy;
+    if (definition.AutoMap === AutoMap.Enabled && identifier !== '$eventSourceId') {
+        const prototype = childType?.prototype;
+        const hasExplicitMapping = prototype !== undefined && (
+            getSetFromMetadata(prototype, identifier).length > 0 ||
+            getSetFromContextMetadata(prototype, identifier).length > 0 ||
+            getSetValueMetadata(prototype, identifier).length > 0 ||
+            getAddFromMetadata(prototype, identifier).length > 0 ||
+            getSubtractFromMetadata(prototype, identifier).length > 0);
+        if (!hasExplicitMapping) {
+            for (const metadata of metadataList) {
+                const entry = definition.From.find(candidate => getEventTypeMapKey(candidate.Key) === getEventTypeMapKey(toContractEventType(metadata.eventType)))!;
+                const mappings = Object.values(entry.Value.Properties);
+                // Preserve the kernel's aggregate-only AutoMap exemption: Changeset.AddChild already
+                // initializes the child identifier from the resolved key before applying property mappers.
+                if (mappings.length > 0 && mappings.every(expression =>
+                    aggregateExpressions.some(aggregate => expression.startsWith(aggregate)))) {
+                    continue;
+                }
+                // Child property mappings may replace the creating key (for example, a constant-key count).
+                const key = entry.Value.Key;
+                // When an event property is also the identifier, AutoMap can fill it directly.
+                if (key.toLowerCase() !== identifier.toLowerCase() && !(identifier in entry.Value.Properties)) {
+                    entry.Value.Properties[identifier] = key === '$eventSourceId'
+                        ? eventContextPropertyExpression('eventSourceId')
+                        : key;
+                }
+            }
+        }
+    }
     return definition;
 }
 

package/reactors/Reactors.ts

@@ -28,6 +28,7 @@ import type { ActivatedArtifact } from '../artifacts/ActivatedArtifact.js';
 import { ArtifactKind } from '../artifacts/ArtifactKind.js';
 import { ArtifactDelivery } from '../artifacts/ArtifactDelivery.js';
 import { withActivatedArtifact, runActivated } from '../artifacts/withActivatedArtifact.js';
+import { ArtifactCompletionFailed } from '../artifacts/ArtifactCompletionFailed.js';
 
 /** Expression used to partition reactor observations by event source ID. */
 const EVENT_SOURCE_ID_KEY = '$eventSourceId';
@@ -306,12 +307,16 @@ export class Reactors implements IReactors {
                             signal: controller.signal, delivery: ArtifactDelivery.ReplayNotification,
                             replayState: eventsToObserve.ReplayState
                         }, this._artifactActivator, artifact => runActivated(artifact, () =>
-                            notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition)));
+                            notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition),
+                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }));
                     } else if (reactorInstance) {
                         await notifyReplayLifecycle(reactorInstance, eventsToObserve.ReplayState, eventsToObserve.Partition);
                     }
                 } catch (err) {
                     this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: String(err) });
+                    if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
+                        exceptionMessages.push(String(err.processingError));
+                    }
                     exceptionMessages.push(String(err));
                     exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                     state = ObservationState.Failed;
@@ -368,7 +373,7 @@ export class Reactors implements IReactors {
                                 const handlerResult = await artifact.instance[methodName](content, context, services);
                                 await dispatchReactorSideEffects(this._eventLog, handlerResult, context, reactorType as Function,
                                     this._eventStoreName, this._namespace, this._resultHandler);
-                            });
+                            }, { delivery: ArtifactDelivery.Events, eventContext: context, methodName });
 
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
@@ -398,8 +403,13 @@ export class Reactors implements IReactors {
                     } catch (err) {
                         this._logger.error('Error activating reactor', { reactorId: id, error: String(err) });
                         exceptionMessages.push(String(err));
-                        exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
+                        const completionStack = err instanceof Error ? (err.stack ?? '') : '';
+                        exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
+                            ? `${exceptionStackTrace}\n${completionStack}` : completionStack;
                         state = ObservationState.Failed;
+                        if (err instanceof ArtifactCompletionFailed) {
+                            lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
+                        }
                     }
                 } else {
                     await processEvents({ instance: reactorInstance ?? {} });