@cratis/chronicle 6.16.0 → 6.17.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,7 +15,15 @@ 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';
+import { invalidEventContextPropertyInProjection } from './invalidEventContextPropertyInProjection.js';
 import { getProjectionMetadata } from './declarative/projection.js';
 import { ProjectionBuilderFor } from './declarative/ProjectionBuilderFor.js';
 import type { IProjectionFor } from './declarative/IProjectionFor.js';
@@ -39,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';
 
@@ -61,8 +78,9 @@ export class ProjectionDefinitionCompiler {
      */
     compile(declarative: Iterable<Constructor>, modelBound: Iterable<Constructor>): CompiledProjectionDefinitions {
         const builtProjections: BuiltProjection[] = [
-            ...Array.from(declarative, type => this.buildDeclarativeDefinition(type)),
-            ...Array.from(modelBound, type => this.buildModelBoundDefinition(type))
+            ...Array.from(declarative, type => this.buildWithContextValidation(type, () => this.buildDeclarativeDefinition(type),
+                getProjectionMetadata(type)?.readModelType)),
+            ...Array.from(modelBound, type => this.buildWithContextValidation(type, () => this.buildModelBoundDefinition(type), type))
         ];
         // A sibling's entering event adds RemovedWith to each variant. Hash only after
         // every variant has been cross-wired, so repeated registrations remain stable.
@@ -75,12 +93,65 @@ 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();
+        } catch (error) {
+            if (error instanceof InvalidEventContextPropertyError) {
+                const readModel = readModelType ? getReadModelId(readModelType) : type.name;
+                throw invalidEventContextPropertyInProjection(error, type.name, readModel);
+            }
+            throw error;
+        }
+    }
+
     private buildReadModelDefinitions(projections: ProjectionDefinition[]): ReturnType<typeof buildReadModelDefinition>[] {
         const byReadModel = new Map<string, ReturnType<typeof buildReadModelDefinition>>();
         for (const projection of projections) {
@@ -149,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) {
@@ -158,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 {
@@ -187,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 } }>();
@@ -228,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);
@@ -262,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');
                 }
             }
         }
@@ -271,13 +379,15 @@ export class ProjectionDefinitionCompiler {
             const fromEvery = getFromEveryMetadata(prototype, property) ?? getFromAllMetadata(prototype, property);
             if (fromEvery) {
                 allProperties[property] = fromEvery.contextProperty
-                    ? fromEvery.contextProperty
+                    ? eventContextPropertyExpression(fromEvery.contextProperty)
                     : (fromEvery.property ?? property);
             }
         }
 
         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) {
@@ -287,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;
             });
@@ -295,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;
@@ -330,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/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;
+}

package/projections/declarative/AllSetBuilder.ts

@@ -3,6 +3,7 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { IAllSetBuilder } from './IAllSetBuilder.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 
 /**
  * Concrete implementation of {@link IAllSetBuilder} for fromEvery mappings.
@@ -27,7 +28,7 @@ export class AllSetBuilder<TReadModel, TParentBuilder> implements IAllSetBuilder
 
     /** @inheritdoc */
     toEventContextProperty(contextPropertyName: string): TParentBuilder {
-        this._setProperty(this._targetProperty, `$context.${contextPropertyName}`);
+        this._setProperty(this._targetProperty, eventContextPropertyExpression(contextPropertyName));
         return this._parent;
     }
 

package/projections/declarative/CompositeKeyBuilder.spec.ts

@@ -101,7 +101,7 @@ describe('CompositeKeyBuilder', () => {
             expect(() => builder.join(OrderLineJoined, join => join
                 .on(model => model.id)
                 .usingParentKey(event => event.orderId)
-                .usingParentKeyFromContext('someContextProperty')
+                .usingParentKeyFromContext('eventSourceId')
                 .usingParentCompositeKey<CompositeKey>(key => key.set(target => target.orderId, event => event.orderId))
                 .usingConstantParentKey('constant')
             )).not.toThrow();

package/projections/declarative/FromBuilder.ts

@@ -3,6 +3,7 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { constantValueExpression } from '../constantValueExpression.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 import { AddBuilder } from './AddBuilder.js';
 import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder.js';
 import { CompositeKeyBuilder } from './CompositeKeyBuilder.js';
@@ -14,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.
@@ -57,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 = `$context.${contextPropertyName}`;
+        this.entry.key = eventContextPropertyExpression(contextPropertyName);
+        recordKeyDeclaration(this, 'Key', '.from().usingKeyFromContext');
         return this;
     }
 
@@ -72,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 = `$context.${contextPropertyName}`;
+        this.entry.parentKey = eventContextPropertyExpression(contextPropertyName);
+        recordKeyDeclaration(this, 'ParentKey', '.from().usingParentKeyFromContext');
         return this;
     }
 
@@ -86,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;
     }
 
@@ -94,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;
     }
 

package/projections/declarative/JoinBuilder.ts

@@ -3,6 +3,7 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { constantValueExpression } from '../constantValueExpression.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 import { AddBuilder } from './AddBuilder.js';
 import { AddChildBuilder, ChildAdditionEntry } from './AddChildBuilder.js';
 import { CompositeKeyBuilder } from './CompositeKeyBuilder.js';
@@ -72,7 +73,7 @@ export class JoinBuilder<TReadModel, TEvent> implements IJoinBuilder<TReadModel,
 
     /** @inheritdoc */
     usingKeyFromContext(contextPropertyName: string): this {
-        this.entry.key = `$context.${contextPropertyName}`;
+        this.entry.key = eventContextPropertyExpression(contextPropertyName);
         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 = {

package/projections/declarative/ProjectionBuilderFor.spec.ts

@@ -227,19 +227,19 @@ describe('ProjectionBuilderFor', () => {
         };
 
         it('should change the hash when a From property expression changes', () => {
-            expect(hashFor(false, 'one', 'source')).not.toBe(hashFor(true, 'one', 'source'));
+            expect(hashFor(false, 'one', 'eventSourceId')).not.toBe(hashFor(true, 'one', 'eventSourceId'));
         });
 
         it('should change the hash when a Join key changes', () => {
-            expect(hashFor(false, 'one', 'source')).not.toBe(hashFor(false, 'two', 'source'));
+            expect(hashFor(false, 'one', 'eventSourceId')).not.toBe(hashFor(false, 'two', 'eventSourceId'));
         });
 
         it('should change the hash when a RemovedWith key changes', () => {
-            expect(hashFor(false, 'one', 'source')).not.toBe(hashFor(false, 'one', 'correlationId'));
+            expect(hashFor(false, 'one', 'eventSourceId')).not.toBe(hashFor(false, 'one', 'correlationId'));
         });
 
         it('should give identical definitions identical hashes', () => {
-            expect(hashFor(false, 'one', 'source')).toBe(hashFor(false, 'one', 'source'));
+            expect(hashFor(false, 'one', 'eventSourceId')).toBe(hashFor(false, 'one', 'eventSourceId'));
         });
 
         it('should give reordered property mappings the same hash', () => {

package/projections/declarative/RemovedWithBuilder.ts

@@ -3,6 +3,7 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { IRemovedWithBuilder } from './IRemovedWithBuilder.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 
 /**
  * Accumulated removal configuration for a removedWith clause.
@@ -34,7 +35,7 @@ export class RemovedWithBuilder<TReadModel, TEvent> implements IRemovedWithBuild
 
     /** @inheritdoc */
     usingKeyFromContext(contextPropertyName: string): this {
-        this.entry.key = `$context.${contextPropertyName}`;
+        this.entry.key = eventContextPropertyExpression(contextPropertyName);
         return this;
     }
 }

package/projections/declarative/SetBuilder.ts

@@ -4,6 +4,7 @@
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { ISetBuilder } from './ISetBuilder.js';
 import { constantValueExpression } from '../constantValueExpression.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 
 /**
  * Concrete implementation of {@link ISetBuilder} that records the property mapping
@@ -35,7 +36,7 @@ export class SetBuilder<TEvent, TParentBuilder> implements ISetBuilder<TEvent, T
 
     /** @inheritdoc */
     toEventContextProperty(contextPropertyName: string): TParentBuilder {
-        this._setProperty(this._readModelProperty, `$context.${contextPropertyName}`);
+        this._setProperty(this._readModelProperty, eventContextPropertyExpression(contextPropertyName));
         return this._parent;
     }
 

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);
+}