@cratis/chronicle 6.16.1 → 6.18.0

package/projections/ProjectionDefinitionCompiler.ts

@@ -5,6 +5,7 @@ import { AutoMap, ReadModelObserverType, type ProjectionDefinition } from '@crat
 import { Constructor } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { getEventTypeFor, getEventTypeJsonSchemaFor } from '../events/eventTypeDecorator.js';
 import { getReadModelMetadata } from '../readModels/index.js';
 import { getReadModelId } from '../readModels/readModel.js';
 import { buildReadModelDefinition } from '../readModels/buildReadModelDefinition.js';
@@ -14,6 +15,11 @@ import { WellKnownSinks } from '../sinks/index.js';
 import { TypeIntrospector } from '../types/index.js';
 import { canonicalStringify } from './canonicalStringify.js';
 import { CompiledProjectionDefinitions } from './CompiledProjectionDefinitions.js';
+import { captureProjectionProvenance } from './captureProjectionProvenance.js';
+import { eventContractPath } from './eventContractPath.js';
+import { getProjectionBuilderProvenance } from './declarative/projectionBuilderProvenance.js';
+import type { ProjectionCapabilityProvenance } from './ProjectionCapabilityProvenance.js';
+import type { ProjectionEventSchema } from './ProjectionEventSchema.js';
 import { constantValueExpression } from './constantValueExpression.js';
 import { eventContextPropertyExpression } from './eventContextPropertyExpression.js';
 import { InvalidEventContextPropertyError } from './InvalidEventContextPropertyError.js';
@@ -42,6 +48,14 @@ import { getRemovedWithJoinClassMetadata, getRemovedWithJoinPropertyMetadata } f
 import { getVariantOfMetadata } from './modelBound/variantOf.js';
 import { getEntersOnMetadata } from './modelBound/entersOn.js';
 import { getGlobalForMetadata } from './modelBound/globalFor.js';
+import { getSetFromMetadata } from './modelBound/setFrom.js';
+import { getSetFromContextMetadata } from './modelBound/setFromContext.js';
+import { getSetValueMetadata } from './modelBound/setValue.js';
+import { getAddFromMetadata } from './modelBound/addFrom.js';
+import { getSubtractFromMetadata } from './modelBound/subtractFrom.js';
+import { getCountMetadata } from './modelBound/count.js';
+import { getIncrementMetadata } from './modelBound/increment.js';
+import { getDecrementMetadata } from './modelBound/decrement.js';
 import type { JoinRecord } from './declarative/ProjectionBuilderCore.js';
 import { BuiltProjection, crossWireGroups, mergeGlobalHandlers, reclassify, VariantDeclaration } from './VariantReclassifier.js';
 
@@ -79,12 +93,53 @@ export class ProjectionDefinitionCompiler {
         // existing sparse wire objects: adding those default-valued fields would change the payload.
         // Evaluators must tolerate absent optional contract fields (for example NoAutoMapProperties).
         const definitions = builtProjections.map(built => built.definition as unknown as ProjectionDefinition);
+        const provenance = new Map<ProjectionDefinition, readonly ProjectionCapabilityProvenance[]>();
+        const eventSchemas = new Map<ProjectionDefinition, ReadonlyMap<string, ProjectionEventSchema>>();
+        const availableEvents = new Map<string, Constructor>(this._clientArtifacts.eventTypes.map(type => {
+            const event = getEventTypeFor(type);
+            return [`${event.id.value}:${event.generation.value}`, type] as const;
+        }));
+        for (let index = 0; index < definitions.length; index++) {
+            provenance.set(definitions[index], builtProjections[index].provenance ?? []);
+            eventSchemas.set(definitions[index], this.buildEventSchemaCatalog(definitions[index], availableEvents));
+        }
         return {
             definitions,
-            readModels: this.buildReadModelDefinitions(definitions)
+            readModels: this.buildReadModelDefinitions(definitions),
+            provenance,
+            eventSchemas
         };
     }
 
+    private buildEventSchemaCatalog(definition: ProjectionDefinition, availableEvents: ReadonlyMap<string, Constructor>): ReadonlyMap<string, ProjectionEventSchema> {
+        const catalog = new Map<string, ProjectionEventSchema>();
+        const collect = (node: Record<string, unknown>) => {
+            for (const section of ['From', 'Join', 'RemovedWith', 'RemovedWithJoin'] as const) {
+                for (const entry of node[section] as Array<{ Key: ContractEventType }> ?? []) {
+                    const eventType = entry.Key;
+                    const key = getEventTypeMapKey(eventType);
+                    const type = availableEvents.get(`${eventType.Id}:${eventType.Generation}`);
+                    if (type && !catalog.has(key)) {
+                        // Registration uses this exact schema path. Clone it so a compile or consumer
+                        // cannot mutate metadata or another compile's catalog.
+                        catalog.set(key, { eventType: { ...eventType }, schema: structuredClone(getEventTypeJsonSchemaFor(type)) });
+                    }
+                }
+            }
+            const fromEventProperty = node.FromEventProperty as { Event?: ContractEventType } | undefined;
+            if (fromEventProperty?.Event) {
+                const key = getEventTypeMapKey(fromEventProperty.Event);
+                const type = availableEvents.get(`${fromEventProperty.Event.Id}:${fromEventProperty.Event.Generation}`);
+                if (type && !catalog.has(key)) catalog.set(key, { eventType: { ...fromEventProperty.Event }, schema: structuredClone(getEventTypeJsonSchemaFor(type)) });
+            }
+            for (const section of ['Children', 'Nested'] as const) {
+                for (const child of Object.values(node[section] as Record<string, Record<string, unknown>> ?? {})) collect(child);
+            }
+        };
+        collect(definition as unknown as Record<string, unknown>);
+        return catalog;
+    }
+
     private buildWithContextValidation(type: Constructor, build: () => BuiltProjection, readModelType?: Constructor): BuiltProjection {
         try {
             return build();
@@ -165,6 +220,12 @@ export class ProjectionDefinitionCompiler {
             }
         }
 
+        const declarations = getProjectionBuilderProvenance(builder);
+        const provenance = captureProjectionProvenance(definition, false,
+            new Map([...declarations.keys, ...declarations.children]));
+        if (declarations.fromEvery && !provenance.some(entry => entry.contractPath === 'All')) {
+            provenance.push({ contractPath: 'All', declaration: '.fromEvery' });
+        }
         let variant: VariantDeclaration | undefined;
         const variantDeclaration = builder.getVariantDeclaration();
         if (variantDeclaration) {
@@ -174,8 +235,11 @@ export class ProjectionDefinitionCompiler {
             definition.From = reclassified.from;
             definition.Join = reclassified.join;
             variant = variantDeclaration;
+            provenance.push({ contractPath: 'Variant', declaration: '.variantOf' });
+            provenance.push({ contractPath: 'Variant.Key', declaration: '.variantOf' });
+            for (const entering of variant.enteringEventTypes) provenance.push({ contractPath: eventContractPath('EntersOn', entering), declaration: '.entersOn' });
         }
-        return { typeName: type.name, definition, variant };
+        return { typeName: type.name, definition, variant, provenance };
     }
 
     private inferReadModelIdentifier(mappedProperties: string[]): string | undefined {
@@ -203,6 +267,16 @@ export class ProjectionDefinitionCompiler {
         const eventSequenceId = getEventSequenceMetadata(type);
         const properties = TypeIntrospector.getTrackedProperties(type);
         const prototype = type.prototype;
+        const overrides = new Map<string, string>();
+        const declaredFrom = new Set(getFromEventMetadata(type).map(entry => getEventTypeMapKey(toContractEventType(entry.eventType))));
+        const recordMappings = (property: string, metadata: Array<{ eventType: Function }>, declaration: string) => {
+            for (const mapping of metadata) {
+                const eventType = toContractEventType(mapping.eventType);
+                const path = eventContractPath('From', eventType);
+                overrides.set(`${path}.Properties.${property}`, declaration);
+                if (!declaredFrom.has(getEventTypeMapKey(eventType)) && !overrides.has(path)) overrides.set(path, declaration);
+            }
+        };
 
         const fromByEventType = new Map<string, FromRecord>();
         const joinByEventType = new Map<string, { Key: ContractEventType; Value: { On: string; Properties: Record<string, string>; Key: string } }>();
@@ -244,6 +318,23 @@ export class ProjectionDefinitionCompiler {
         }
 
         for (const property of properties) {
+            recordMappings(property, getSetFromMetadata(prototype, property), '@setFrom');
+            recordMappings(property, getSetFromContextMetadata(prototype, property), '@setFromContext');
+            recordMappings(property, getSetValueMetadata(prototype, property), '@setValue');
+            recordMappings(property, getAddFromMetadata(prototype, property), '@addFrom');
+            recordMappings(property, getSubtractFromMetadata(prototype, property), '@subtractFrom');
+            recordMappings(property, getIncrementMetadata(prototype, property), '@increment');
+            recordMappings(property, getDecrementMetadata(prototype, property), '@decrement');
+            recordMappings(property, getCountMetadata(prototype, property), '@count');
+            for (const [declaration, mappings] of [
+                ['@increment', getIncrementMetadata(prototype, property)],
+                ['@decrement', getDecrementMetadata(prototype, property)],
+                ['@count', getCountMetadata(prototype, property)]
+            ] as const) {
+                for (const mapping of mappings) {
+                    if (mapping.constantKey) overrides.set(`${eventContractPath('From', toContractEventType(mapping.eventType))}.Key`, declaration);
+                }
+            }
             applyPropertyMappings(prototype, property, fromByEventType);
             for (const mapping of getJoinMetadata(prototype, property)) {
                 const entry = this.ensureJoinEntry(joinByEventType, mapping.eventType);
@@ -278,6 +369,7 @@ export class ProjectionDefinitionCompiler {
                 for (const clearWith of getClearWithPropertyMetadata(prototype, property)) {
                     const entry = ensureFromEntry(fromByEventType, clearWith.eventType);
                     entry.Value.Properties[property] = '$null';
+                    overrides.set(`${eventContractPath('From', toContractEventType(clearWith.eventType))}.Properties.${property}`, '@clearWith');
                 }
             }
         }
@@ -294,6 +386,8 @@ export class ProjectionDefinitionCompiler {
 
         let from = Array.from(fromByEventType.values());
         let join = Array.from(joinByEventType.values());
+        let preLoweringFrom = from;
+        let preLoweringJoin = join;
         let variant: VariantDeclaration | undefined;
         const variantMetadata = getVariantOfMetadata(type);
         if (variantMetadata) {
@@ -303,6 +397,7 @@ export class ProjectionDefinitionCompiler {
                 if (entersOn.key) {
                     const entry = ensureFromEntry(fromByEventType, entersOn.eventType);
                     entry.Value.Key = entersOn.key;
+                    overrides.set(`${eventContractPath('From', contractType)}.Key`, '@entersOn');
                 }
                 return contractType;
             });
@@ -311,11 +406,21 @@ export class ProjectionDefinitionCompiler {
             for (const handlerType of this._clientArtifacts.globalForHandlers) {
                 const globalForMetadata = getGlobalForMetadata(handlerType);
                 if (globalForMetadata?.identity === variantMetadata.identity) {
-                    globalHandlers.set(handlerType.name, this.buildFromRecordsForType(handlerType));
+                    const records = this.buildFromRecordsForType(handlerType);
+                    globalHandlers.set(handlerType.name, records);
+                    for (const record of records) {
+                        const path = eventContractPath('From', record.Key);
+                        overrides.set(path, `@globalFor(${handlerType.name})`);
+                        for (const property of Object.keys(record.Value.Properties)) {
+                            overrides.set(`${path}.Properties.${property}`, `@globalFor(${handlerType.name})`);
+                        }
+                    }
                 }
             }
             const memberNames = new Set(getReadModelMetadata(type)?.members.keys() ?? TypeIntrospector.getMembers(type).keys());
             const merged = mergeGlobalHandlers(type.name, memberNames, from, globalHandlers);
+            preLoweringFrom = merged;
+            preLoweringJoin = join;
             const reclassified = reclassify(type.name, merged, join, enteringEventTypes, variantMetadata.key);
             from = reclassified.from;
             join = reclassified.join;
@@ -346,7 +451,25 @@ export class ProjectionDefinitionCompiler {
             NoAutoMapProperties: properties.filter(property => isPropertyNoAutoMap(prototype, property)),
             Nested: nestedByProperty
         };
-        return { typeName: type.name, definition, variant };
+        const provenance = captureProjectionProvenance({ ...definition, From: preLoweringFrom, Join: preLoweringJoin }, true, overrides);
+        if (Object.keys(allProperties).length && Object.keys(allProperties).every(property =>
+            getFromAllMetadata(prototype, property) && !getFromEveryMetadata(prototype, property))) {
+            const index = provenance.findIndex(entry => entry.contractPath === 'All');
+            if (index >= 0) provenance[index] = { contractPath: 'All', declaration: '@fromAll' };
+        }
+        for (const property of Object.keys(allProperties)) {
+            if (getFromAllMetadata(prototype, property) && !getFromEveryMetadata(prototype, property)) {
+                const path = `All.Properties.${property}`;
+                const index = provenance.findIndex(entry => entry.contractPath === path);
+                if (index >= 0) provenance[index] = { contractPath: path, declaration: '@fromAll' };
+            }
+        }
+        if (variant) {
+            provenance.push({ contractPath: 'Variant', declaration: '@variantOf' });
+            provenance.push({ contractPath: 'Variant.Key', declaration: '@variantOf' });
+            for (const entering of variant.enteringEventTypes) provenance.push({ contractPath: eventContractPath('EntersOn', entering), declaration: '@entersOn' });
+        }
+        return { typeName: type.name, definition, variant, provenance };
     }
 
     /**

package/projections/ProjectionEventSchema.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { JsonSchema } from '../schemas/JsonSchema.js';
+import type { ContractEventType } from './declarative/ProjectionBuilderCore.js';
+
+/** Schema registered for one participating event type and generation. */
+export interface ProjectionEventSchema {
+    /** Event identifier, generation, and tombstone status. */
+    readonly eventType: ContractEventType;
+    /** Isolated copy of the schema registered for this event. */
+    readonly schema: JsonSchema;
+}

package/projections/Projections.childrenAndNested.spec.ts

@@ -10,7 +10,10 @@ import { ChronicleConnection } from '../connection/index.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import { childrenFrom } from './modelBound/childrenFrom.js';
 import { clearWith } from './modelBound/clearWith.js';
+import { count } from './modelBound/count.js';
+import { decrement } from './modelBound/decrement.js';
 import { fromEvent } from './modelBound/fromEvent.js';
+import { increment } from './modelBound/increment.js';
 import { nested } from './modelBound/nested.js';
 import { noAutoMap } from './modelBound/noAutoMap.js';
 import { setFrom } from './modelBound/setFrom.js';
@@ -22,6 +25,7 @@ import { Projections } from './Projections.js';
 class LineAdded {
     productId!: string;
     quantity!: number;
+    label!: string;
 }
 eventType()(LineAdded);
 
@@ -30,6 +34,11 @@ class LineQuantityChanged {
 }
 eventType()(LineQuantityChanged);
 
+class AlternateLineAdded {
+    alternateId!: string;
+}
+eventType()(AlternateLineAdded);
+
 class LineQuantityCleared {}
 eventType()(LineQuantityCleared);
 
@@ -71,6 +80,117 @@ setFrom(LineQuantityChanged)(OrderLine.prototype, 'quantity');
 noAutoMap(OrderLine.prototype, 'quantity');
 clearWith(LineQuantityCleared)(OrderLine.prototype, 'quantity');
 
+class ChildWithId {
+    id = '';
+    label = '';
+}
+class ChildWithUppercaseId {
+    Id = '';
+}
+class ChildWithExplicitId {
+    employeeNumber = '';
+    label = '';
+}
+class ChildWithMatchingEventKey {
+    productId = '';
+}
+class ChildWithMappedId {
+    id = '';
+}
+setFrom(LineAdded, 'productId')(ChildWithMappedId.prototype, 'id');
+class ChildWithoutAutoMap {
+    id = '';
+}
+noAutoMap(ChildWithoutAutoMap);
+class ChildWithNoAutoMappedId {
+    id = '';
+}
+noAutoMap(ChildWithNoAutoMappedId.prototype, 'id');
+class ChildWithConstantCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded, 'all')(ChildWithConstantCount.prototype, 'total');
+class ChildWithConstantIncrement {
+    id = '';
+    total = 0;
+    label = '';
+}
+increment(LineAdded, 'all')(ChildWithConstantIncrement.prototype, 'total');
+class ChildWithConstantDecrement {
+    id = '';
+    total = 0;
+    label = '';
+}
+decrement(LineAdded, 'all')(ChildWithConstantDecrement.prototype, 'total');
+class ChildWithPlainCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded)(ChildWithPlainCount.prototype, 'total');
+class ChildWithMappedLabelAndCount {
+    id = '';
+    total = 0;
+    label = '';
+}
+count(LineAdded)(ChildWithMappedLabelAndCount.prototype, 'total');
+setFrom(LineAdded)(ChildWithMappedLabelAndCount.prototype, 'label');
+class ChildWithEmptyKey {
+    [''] = '';
+}
+class ChildWithoutMatchingEmptyKey {
+    label = '';
+}
+class IdentifiedChildren {
+    byConvention!: ChildWithId[];
+    byUppercaseId!: ChildWithUppercaseId[];
+    byExplicitId!: ChildWithExplicitId[];
+    byExplicitIdWithoutChildType!: ChildWithId[];
+    byInferredEventKey!: ChildWithMatchingEventKey[];
+    byEventKey!: ChildWithId[];
+    byMatchingKey!: ChildWithId[];
+    withExplicitMapping!: ChildWithMappedId[];
+    withoutAutoMap!: ChildWithoutAutoMap[];
+    withNoAutoMappedId!: ChildWithNoAutoMappedId[];
+    withDifferentEventKeys!: ChildWithId[];
+    withConstantCount!: ChildWithConstantCount[];
+    withConstantIncrement!: ChildWithConstantIncrement[];
+    withConstantDecrement!: ChildWithConstantDecrement[];
+    withPlainCount!: ChildWithPlainCount[];
+    withMappedLabelAndCount!: ChildWithMappedLabelAndCount[];
+    withEmptyEventKey!: ChildWithEmptyKey[];
+    withoutMatchingEmptyKey!: ChildWithoutMatchingEmptyKey[];
+}
+childrenFrom(LineAdded, ChildWithId)(IdentifiedChildren.prototype, 'byConvention');
+childrenFrom(LineAdded, ChildWithUppercaseId)(IdentifiedChildren.prototype, 'byUppercaseId');
+childrenFrom(LineAdded, ChildWithExplicitId, 'employeeNumber')(IdentifiedChildren.prototype, 'byExplicitId');
+childrenFrom(LineAdded, undefined, 'id')(IdentifiedChildren.prototype, 'byExplicitIdWithoutChildType');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'byInferredEventKey');
+childrenFrom(LineAdded, 'productId', 'id')(IdentifiedChildren.prototype, 'byEventKey');
+childrenFrom(LineAdded, 'id', 'id')(IdentifiedChildren.prototype, 'byMatchingKey');
+childrenFrom(LineAdded, ChildWithMappedId)(IdentifiedChildren.prototype, 'withExplicitMapping');
+childrenFrom(LineAdded, ChildWithoutAutoMap)(IdentifiedChildren.prototype, 'withoutAutoMap');
+childrenFrom(LineAdded, ChildWithNoAutoMappedId)(IdentifiedChildren.prototype, 'withNoAutoMappedId');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+childrenFrom(AlternateLineAdded, 'alternateId')(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+childrenFrom(LineAdded, ChildWithConstantCount)(IdentifiedChildren.prototype, 'withConstantCount');
+childrenFrom(LineAdded, 'productId')(IdentifiedChildren.prototype, 'withConstantIncrement');
+field(Array, { enumerable: true, genericArguments: [ChildWithConstantIncrement] })(IdentifiedChildren.prototype, 'withConstantIncrement');
+childrenFrom(LineAdded, ChildWithConstantDecrement)(IdentifiedChildren.prototype, 'withConstantDecrement');
+childrenFrom(LineAdded, ChildWithPlainCount)(IdentifiedChildren.prototype, 'withPlainCount');
+childrenFrom(LineAdded, ChildWithMappedLabelAndCount)(IdentifiedChildren.prototype, 'withMappedLabelAndCount');
+childrenFrom(LineAdded, '')(IdentifiedChildren.prototype, 'withEmptyEventKey');
+childrenFrom(LineAdded, '')(IdentifiedChildren.prototype, 'withoutMatchingEmptyKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithMatchingEventKey] })(IdentifiedChildren.prototype, 'byInferredEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'byEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'byMatchingKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithId] })(IdentifiedChildren.prototype, 'withDifferentEventKeys');
+field(Array, { enumerable: true, genericArguments: [ChildWithEmptyKey] })(IdentifiedChildren.prototype, 'withEmptyEventKey');
+field(Array, { enumerable: true, genericArguments: [ChildWithoutMatchingEmptyKey] })(IdentifiedChildren.prototype, 'withoutMatchingEmptyKey');
+fromEvent(OrderCreated)(IdentifiedChildren);
+
 class OrderSummary {
     total!: number;
 }
@@ -140,10 +260,11 @@ noAutoMap(OrderWithoutAutoMap);
 fromEvent(OrderCreated)(OrderWithoutAutoMap);
 
 class Grandchild {
-    id!: string;
+    id = '';
 }
 
 class ChildWithGrandchildren {
+    id = '';
     grandchildren!: Grandchild[];
     detail!: Grandchild | undefined;
 }
@@ -248,6 +369,130 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             expect(updateEntry.Value.Properties.quantity).toBe('quantity');
         });
 
+        it('should map a convention or explicit child identifier from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.byConvention.IdentifiedBy).toBe('id');
+            expect(children.byConvention.From[0].Value.Properties).toEqual({ id: '$eventContext(EventSourceId)' });
+            expect(children.byUppercaseId.IdentifiedBy).toBe('Id');
+            expect(children.byUppercaseId.From[0].Value.Properties).toEqual({ Id: '$eventContext(EventSourceId)' });
+            expect(children.byExplicitId.IdentifiedBy).toBe('employeeNumber');
+            expect(children.byExplicitId.From[0].Value.Properties).toEqual({ employeeNumber: '$eventContext(EventSourceId)' });
+        });
+
+        it('should map an explicit identifier without child-type metadata from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.byExplicitIdWithoutChildType;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From[0].Value.Properties).toEqual({ id: '$eventContext(EventSourceId)' });
+        });
+
+        it('should map the child identifier from an explicit event key when it differs from the property name', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.byEventKey.From[0].Value.Properties.id).toBe('productId');
+            expect(children.byInferredEventKey.IdentifiedBy).toBe('productId');
+            expect(children.byInferredEventKey.From[0].Value.Properties).toEqual({});
+            expect(children.byMatchingKey.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should leave explicitly mapped identifiers and class-level disabled auto-mapping unchanged', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            expect(children.withExplicitMapping.From[0].Value.Properties).toEqual({ id: 'productId' });
+            expect(children.withoutAutoMap.AutoMap).toBe(AutoMap.Disabled);
+            expect(children.withoutAutoMap.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should map an identifier with property-level noAutoMap from the creating event source id', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withNoAutoMappedId;
+            expect(child.AutoMap).toBe(AutoMap.Enabled);
+            expect(child.NoAutoMapProperties).toContain('id');
+            expect(child.From[0].Value.Properties.id).toBe('$eventContext(EventSourceId)');
+        });
+
+        it('should map each creating event using its own key on a shared children collection', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withDifferentEventKeys;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From).toHaveLength(2);
+            expect(child.From.find(candidate => candidate.Key.Id === 'LineAdded')?.Value).toEqual({
+                Key: 'productId', ParentKey: '$eventSourceId', Properties: { id: 'productId' }
+            });
+            expect(child.From.find(candidate => candidate.Key.Id === 'AlternateLineAdded')?.Value).toEqual({
+                Key: 'alternateId', ParentKey: '$eventSourceId', Properties: { id: 'alternateId' }
+            });
+        });
+
+        it('should preserve aggregate-only child count, increment and decrement with constant keys', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const children = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children;
+            for (const [name, operation] of [
+                ['withConstantCount', '$count'],
+                ['withConstantIncrement', '$increment'],
+                ['withConstantDecrement', '$decrement']
+            ]) {
+                const child = children[name];
+                expect(child.IdentifiedBy).toBe('id');
+                expect(child.From[0].Value).toEqual({
+                    Key: '$value(all)', ParentKey: '$eventSourceId', Properties: { total: operation }
+                });
+            }
+        });
+
+        it('should preserve aggregate-only child count without a constant key', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withPlainCount;
+            expect(child.IdentifiedBy).toBe('id');
+            expect(child.From[0].Value).toEqual({
+                Key: '$eventSourceId', ParentKey: '$eventSourceId', Properties: { total: '$count' }
+            });
+        });
+
+        it('should still map the identifier when a child count also explicitly maps a label', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withMappedLabelAndCount;
+            expect(child.From[0].Value.Properties).toEqual({ total: '$count', label: 'label', id: '$eventContext(EventSourceId)' });
+        });
+
+        it('should discover a child property matching an explicitly empty event key', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withEmptyEventKey;
+            expect(child.IdentifiedBy).toBe('');
+            expect(child.From[0].Value.Key).toBe('');
+            expect(child.From[0].Value.Properties).toEqual({});
+        });
+
+        it('should not infer an identifier from an empty event key without a matching child property', async () => {
+            const { projections, registerMock } = createProjections([IdentifiedChildren]);
+            await projections.register();
+
+            const child = (registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition).Children.withoutMatchingEmptyKey;
+            expect(child.IdentifiedBy).toBe('$eventSourceId');
+            expect(child.From[0].Value.Key).toBe('');
+        });
+
         it('should clear only the child member through a From mapping', async () => {
             const { projections, registerMock } = createProjections([Order]);
             await projections.register();
@@ -324,6 +569,7 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const child = definition.Children.children;
             expect(child.AutoMap).toBe(AutoMap.Disabled);
             expect(child.Children.grandchildren.AutoMap).toBe(AutoMap.Disabled);
+            expect(child.Children.grandchildren.From[0].Value.Properties).toEqual({});
             expect(child.Nested.detail.AutoMap).toBe(AutoMap.Disabled);
         });
 
@@ -334,7 +580,10 @@ describe('Projections with childrenFrom, nested and clearWith', () => {
             const definition = registerMock.mock.calls[0][0].Projections[0] as BuiltDefinition;
             const child = definition.Children.children;
             expect(child.AutoMap).toBe(AutoMap.Disabled);
+            expect(child.From[0].Value.Properties).toEqual({});
             expect(child.Children.grandchildren.AutoMap).toBe(AutoMap.Enabled);
+            expect(child.Children.grandchildren.IdentifiedBy).toBe('id');
+            expect(child.Children.grandchildren.From[0].Value.Properties.id).toBe('$eventContext(EventSourceId)');
             expect(child.Nested.detail.AutoMap).toBe(AutoMap.Enabled);
         });
 

package/projections/VariantReclassifier.ts

@@ -3,6 +3,7 @@
 
 import { ContractEventType, FromRecord, JoinRecord } from './declarative/ProjectionBuilderCore.js';
 import { GlobalHandlerPropertyNotOnVariant } from './GlobalHandlerPropertyNotOnVariant.js';
+import type { ProjectionCapabilityProvenance } from './ProjectionCapabilityProvenance.js';
 import { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent.js';
 
 const EVENT_SOURCE_ID_KEY = '$eventSourceId';
@@ -28,6 +29,7 @@ export interface BuiltProjection {
     readonly typeName: string;
     readonly definition: Record<string, unknown>;
     readonly variant?: VariantDeclaration;
+    readonly provenance?: ProjectionCapabilityProvenance[];
 }
 
 function eventTypeKey(eventType: ContractEventType): string {

package/projections/captureProjectionProvenance.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ProjectionCapabilityProvenance } from './ProjectionCapabilityProvenance.js';
+import type { ContractEventType } from './declarative/ProjectionBuilderCore.js';
+import { eventContractPath } from './eventContractPath.js';
+
+/** Captures pre-lowering declarations without changing the registration contract. */
+export function captureProjectionProvenance(definition: Record<string, unknown>, modelBound: boolean, overrides: ReadonlyMap<string, string> = new Map()): ProjectionCapabilityProvenance[] {
+    const result: ProjectionCapabilityProvenance[] = [];
+    const add = (contractPath: string, declaration: string) => result.push({ contractPath, declaration: overrides.get(contractPath) ?? declaration });
+    const prefix = modelBound ? '@' : '.';
+    const from = definition.From as Array<{ Key: ContractEventType; Value: { Properties: Record<string, string>; Key: string; ParentKey: string } }> ?? [];
+    for (const entry of from) {
+        const path = eventContractPath('From', entry.Key);
+        add(path, `${prefix}${modelBound ? 'fromEvent' : 'from'}`);
+        add(`${path}.Key`, `${prefix}${modelBound ? 'fromEvent' : 'from().usingKey'}`);
+        add(`${path}.ParentKey`, `${prefix}${modelBound ? 'fromEvent' : 'from().usingParentKey'}`);
+        for (const [property, expression] of Object.entries(entry.Value.Properties ?? {})) {
+            const operation = expression.startsWith('$add(') ? 'addFrom' : expression.startsWith('$subtract(') ? 'subtractFrom'
+                : expression === '$count' ? 'count' : expression === '$increment' ? 'increment'
+                    : expression === '$decrement' ? 'decrement' : expression === '$null' ? 'clearWith'
+                        : expression.startsWith('$value(') ? 'setValue' : expression.startsWith('$eventContext(') ? 'setFromContext' : 'setFrom';
+            add(`${path}.Properties.${property}`, `${prefix}${modelBound ? operation : `from().${operation}`}`);
+        }
+    }
+    for (const section of ['Join', 'RemovedWith', 'RemovedWithJoin'] as const) {
+        for (const entry of definition[section] as Array<{ Key: ContractEventType; Value: { Properties?: Record<string, string>; Key?: string; ParentKey?: string } }> ?? []) {
+            const path = eventContractPath(section, entry.Key);
+            const declaration = modelBound ? `@${section[0].toLowerCase()}${section.slice(1)}` : `.${section[0].toLowerCase()}${section.slice(1)}`;
+            add(path, declaration);
+            if (entry.Value.Key !== undefined) add(`${path}.Key`, declaration);
+            if (entry.Value.ParentKey !== undefined) add(`${path}.ParentKey`, declaration);
+            for (const property of Object.keys(entry.Value.Properties ?? {})) add(`${path}.Properties.${property}`, declaration);
+        }
+    }
+    for (const section of ['Children', 'Nested'] as const) {
+        for (const property of Object.keys(definition[section] as Record<string, unknown> ?? {})) {
+            add(`${section}.${property}`, modelBound ? (section === 'Children' ? '@childrenFrom' : '@nested') : `.${section.toLowerCase()}`);
+        }
+    }
+    const all = definition.All as { Properties?: Record<string, string>; IncludeChildren?: boolean } | undefined;
+    if (all?.IncludeChildren || Object.keys(all?.Properties ?? {}).length) add('All', modelBound ? '@fromEvery' : '.fromEvery');
+    for (const property of Object.keys(all?.Properties ?? {})) add(`All.Properties.${property}`, modelBound ? '@fromEvery' : '.fromEvery');
+    if ((definition.FromEvery as unknown[] | undefined)?.length) add('FromEvery', modelBound ? '@fromEvery' : '.fromEvery');
+    if (definition.IsActive === false) add('IsActive', modelBound ? '@passive' : '.passive');
+    if (definition.EventSequenceId) add('EventSequenceId', modelBound ? '@eventSequence' : '.fromEventSequence');
+    if (definition.FromEventProperty) add('FromEventProperty', modelBound ? '@fromEvent' : '.from');
+    return result;
+}