@cratis/chronicle 6.15.0 → 6.16.1

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';
@@ -62,7 +63,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
 
     /** @inheritdoc */
     usingKeyFromContext(contextPropertyName: string): this {
-        this.entry.key = `$context.${contextPropertyName}`;
+        this.entry.key = eventContextPropertyExpression(contextPropertyName);
         return this;
     }
 
@@ -77,7 +78,7 @@ export class FromBuilder<TReadModel, TEvent> implements IFromBuilder<TReadModel,
 
     /** @inheritdoc */
     usingParentKeyFromContext(contextPropertyName: string): this {
-        this.entry.parentKey = `$context.${contextPropertyName}`;
+        this.entry.parentKey = eventContextPropertyExpression(contextPropertyName);
         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/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/eventContextExpressions.spec.ts

@@ -0,0 +1,273 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { Constructor, field } from '@cratis/fundamentals';
+import { chai, describe, expect, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { InvalidEventContextPropertyError } from '../index.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { ProjectionBuilderFor } from './declarative/ProjectionBuilderFor.js';
+import { projection } from './declarative/projection.js';
+import { childrenFrom } from './modelBound/childrenFrom.js';
+import { fromEvent } from './modelBound/fromEvent.js';
+import { fromEvery } from './modelBound/fromEvery.js';
+import { nested } from './modelBound/nested.js';
+import { setFromContext } from './modelBound/setFromContext.js';
+import { ProjectionDefinitionCompiler } from './ProjectionDefinitionCompiler.js';
+import { Projections } from './Projections.js';
+
+class Recorded { reference!: string; }
+eventType()(Recorded);
+class Removed {}
+eventType()(Removed);
+class Child { happened!: Date; }
+setFromContext(Recorded, 'occurred')(Child.prototype, 'happened');
+class Model { occurred!: Date; happened!: Date; viaAccessor!: Date; children!: Child[]; detail!: Child; }
+setFromContext(Recorded)(Model.prototype, 'occurred');
+setFromContext(Recorded, 'occurred')(Model.prototype, 'happened');
+setFromContext(Recorded, context => context.occurred)(Model.prototype, 'viaAccessor');
+childrenFrom(Recorded, Child)(Model.prototype, 'children');
+field(Child)(Model.prototype, 'detail');
+nested(Model.prototype, 'detail');
+fromEvery(undefined, 'sequenceNumber')(Model.prototype, 'happened');
+fromEvent(Recorded)(Model);
+
+interface FromRecord { Value: { Properties: Record<string, string>; Key: string; ParentKey: string } }
+interface JoinRecord { Value: { Properties: Record<string, string>; Key: string } }
+interface Definition {
+    From: FromRecord[];
+    Join: JoinRecord[];
+    All: { Properties: Record<string, string> };
+    RemovedWith: Array<{ Value: { Key: string } }>;
+    Children: Record<string, { From: FromRecord[] }>;
+    Nested: Record<string, { From: FromRecord[] }>;
+}
+
+function declarative(configure: (builder: ProjectionBuilderFor<Model>) => void): Definition {
+    const builder = new ProjectionBuilderFor<Model>();
+    configure(builder);
+    return builder.build('context-spec', 'Model') as unknown as Definition;
+}
+
+function modelBound(readModel: Constructor = Model): Definition {
+    const artifacts: IClientArtifactsProvider = {
+        projections: [], readModels: [readModel], globalForHandlers: [], eventTypes: [Recorded],
+        reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+    };
+    return new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile([], [readModel]).definitions[0] as unknown as Definition;
+}
+
+function compileDeclarative(configure: (builder: ProjectionBuilderFor<Model>) => void): void {
+    class InvalidDeclarativeProjection {
+        define(builder: ProjectionBuilderFor<Model>): void { configure(builder); }
+    }
+    projection('invalid-context', Model)(InvalidDeclarativeProjection);
+    const artifacts: IClientArtifactsProvider = {
+        projections: [InvalidDeclarativeProjection], readModels: [Model], globalForHandlers: [], eventTypes: [Recorded],
+        reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+    };
+    new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile([InvalidDeclarativeProjection], []);
+}
+
+function register(projections: Constructor[], readModels: Constructor[]): Promise<void> {
+    const artifacts: IClientArtifactsProvider = {
+        projections, readModels, globalForHandlers: [], eventTypes: [Recorded],
+        reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+    };
+    return new Projections('test-store', 'test-namespace', {} as ChronicleConnection, artifacts, 'test-sink').register();
+}
+
+chai.should();
+
+describe('event context expressions', () => {
+    it('should map a model-bound implicit context property to the kernel expression', () => {
+        modelBound().From[0].Value.Properties.occurred.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should map a model-bound explicit context property to the kernel expression', () => {
+        modelBound().From[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should map a model-bound context accessor to the kernel expression', () => {
+        modelBound().From[0].Value.Properties.viaAccessor.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should map a child model-bound context property to the kernel expression', () => {
+        modelBound().Children.children.From[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should map a nested model-bound context property to the kernel expression', () => {
+        modelBound().Nested.detail.From[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should map a model-bound fromEvery context property to the kernel expression', () => {
+        modelBound().All.Properties.happened.should.equal('$eventContext(SequenceNumber)');
+    });
+
+    it('should set an event context property on a declarative from mapping', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('occurred')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should set an event context property on a declarative join mapping', () => {
+        declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred).set(model => model.happened).toEventContextProperty('occurred')))
+            .Join[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+
+    it('should set an event context property on a declarative fromEvery mapping', () => {
+        declarative(builder => builder.fromEvery(all => all.set(model => model.happened).toEventContextProperty('sequenceNumber')))
+            .All.Properties.happened.should.equal('$eventContext(SequenceNumber)');
+    });
+
+    it('should preserve PascalCase and capitalize every nested context segment', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('CausedBy.subject')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(CausedBy.Subject)');
+    });
+
+    it('should allow a kernel-derived function on a known context property', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('occurred.week()')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(Occurred.Week())');
+    });
+
+    it('should normalize a mixed-case kernel-derived function', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('occurred.WEEK()')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(Occurred.Week())');
+    });
+
+    it('should reject the week function on a non-date property, in a nonterminal position, or without parentheses', () => {
+        for (const path of ['eventSourceId.week()', 'occurred.week.day', 'occurred.week', 'causedBy.subject.week()']) {
+            expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+                all.set(model => model.happened).toEventContextProperty(path))))
+                .toThrow(`Invalid event context property '${path}'`);
+        }
+    });
+
+    it('should reject a derived function the kernel does not recognize', () => {
+        expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+            all.set(model => model.happened).toEventContextProperty('occurred.ISOWeek()'))))
+            .toThrow(/Invalid event context property 'occurred.ISOWeek\(\)'.*'InvalidDeclarativeProjection'/);
+    });
+
+    it('should map the on-behalf-of identity as a whole', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('causedBy.onBehalfOf')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(CausedBy.OnBehalfOf)');
+    });
+
+    it('should reject unknown identity members and deeper onBehalfOf chains', () => {
+        for (const path of ['causedBy.unknown', 'causedBy.onBehalfOf.unknown', 'causedBy.subject.name',
+            'causedBy.onBehalfOf.userName', 'causedBy.onBehalfOf.onBehalfOf.userName', 'causedBy.onBehalfOf.onBehalfOf']) {
+            expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+                all.set(model => model.happened).toEventContextProperty(path))))
+                .toThrow(`Invalid event context property '${path}'`);
+        }
+    });
+
+    it('should map the whole causation collection', () => {
+        declarative(builder => builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('causation')))
+            .From[0].Value.Properties.happened.should.equal('$eventContext(Causation)');
+    });
+
+    it('should reject paths into the causation and tags collections', () => {
+        for (const path of ['causation.type', 'causation.unknown', 'causation.properties.unknown', 'tags.name']) {
+            expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+                all.set(model => model.happened).toEventContextProperty(path))))
+                .toThrow(`Invalid event context property '${path}'`);
+        }
+    });
+
+    it('should use a context property as a from key', () => {
+        declarative(builder => builder.from(Recorded, from => from.usingKeyFromContext('eventSourceId')))
+            .From[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+    });
+
+    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)');
+    });
+
+    it('should use a context property as a join key', () => {
+        declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred).usingKeyFromContext('eventSourceId')))
+            .Join[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+    });
+
+    it('should leave a join parent key unset because JoinDefinition has no parent key', () => {
+        declarative(builder => builder.join(Recorded, join => join.on(model => model.occurred).usingParentKeyFromContext('eventSourceId')))
+            .Join[0].Value.Key.should.equal('$eventSourceId');
+    });
+
+    it('should use a context property as a removal key', () => {
+        declarative(builder => builder.removedWith(Removed, removed => removed.usingKeyFromContext('eventSourceId')))
+            .RemovedWith[0].Value.Key.should.equal('$eventContext(EventSourceId)');
+    });
+
+    it('should name the model-bound projection and read model identifier on registration failure', async () => {
+        class InvalidModel { static readonly readModelId = 'invalid-model-id'; happened!: Date; }
+        setFromContext(Recorded, 'invalidProperty')(InvalidModel.prototype, 'happened');
+        fromEvent(Recorded)(InvalidModel);
+        const attempt = register([], [InvalidModel]);
+        await expect(attempt).rejects.toThrow("Invalid event context property 'invalidProperty' in projection 'InvalidModel' (read model 'invalid-model-id').");
+        await expect(attempt).rejects.toMatchObject({ cause: expect.any(InvalidEventContextPropertyError) });
+    });
+
+    it('should reject an unknown nested identity member in a model-bound projection', () => {
+        class InvalidIdentityModel { happened!: string; }
+        setFromContext(Recorded, 'causedBy.missing')(InvalidIdentityModel.prototype, 'happened');
+        fromEvent(Recorded)(InvalidIdentityModel);
+        expect(() => modelBound(InvalidIdentityModel))
+            .toThrow(/Invalid event context property 'causedBy.missing'.*'InvalidIdentityModel'/);
+    });
+
+    it('should reject an invalid implicit model-bound context property at registration', () => {
+        class ImplicitInvalidModel { unknown!: string; }
+        setFromContext(Recorded)(ImplicitInvalidModel.prototype, 'unknown');
+        fromEvent(Recorded)(ImplicitInvalidModel);
+        expect(() => modelBound(ImplicitInvalidModel)).toThrow(/Invalid event context property 'unknown'.*'ImplicitInvalidModel'/);
+    });
+
+    it('should name the declarative projection and read model identifier on registration failure', async () => {
+        class InvalidDeclarativeModel { static readonly readModelId = 'declarative-model-id'; happened!: Date; }
+        class InvalidDeclarativeProjection {
+            define(builder: ProjectionBuilderFor<InvalidDeclarativeModel>): void {
+                builder.from(Recorded, from => from.set(model => model.happened).toEventContextProperty('unknown'));
+            }
+        }
+        projection('invalid-context', InvalidDeclarativeModel)(InvalidDeclarativeProjection);
+        const attempt = register([InvalidDeclarativeProjection], [InvalidDeclarativeModel]);
+        await expect(attempt).rejects.toThrow("Invalid event context property 'unknown' in projection 'InvalidDeclarativeProjection' (read model 'declarative-model-id').");
+        await expect(attempt).rejects.toMatchObject({ cause: expect.any(InvalidEventContextPropertyError) });
+    });
+
+    it('should reject an invalid declarative all-set context property at registration', () => {
+        expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+            all.set(model => model.happened).toEventContextProperty('unknown'))))
+            .toThrow(/Invalid event context property 'unknown'.*'InvalidDeclarativeProjection'.*'Model'/);
+    });
+
+    it('should reject invalid context paths that the kernel cannot parse', () => {
+        expect(() => compileDeclarative(builder => builder.fromEvery(all =>
+            all.set(model => model.happened).toEventContextProperty('causedBy.subject[0]'))))
+            .toThrow(/Invalid event context property 'causedBy.subject\[0\]'.*'InvalidDeclarativeProjection'/);
+    });
+
+    it('should reject invalid context properties in key and parent-key APIs at registration', () => {
+        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.join(Recorded, join => join.on(model => model.occurred).usingKeyFromContext('missingJoinKey')),
+            (builder: ProjectionBuilderFor<Model>) => builder.removedWith(Removed, removed => removed.usingKeyFromContext('missingRemovalKey'))
+        ];
+        for (const configure of mappings) {
+            expect(() => compileDeclarative(configure)).toThrow(/Invalid event context property 'missing.*' in projection 'InvalidDeclarativeProjection'/);
+        }
+    });
+
+    it('should use a context property on a declarative child and child parent key', () => {
+        const child = declarative(builder => builder.children<Child>(model => model.children, children => children
+            .from(Recorded, from => from.usingParentKeyFromContext('eventSourceId')
+                .set(model => model.happened).toEventContextProperty('occurred'))));
+        child.Children.children.From[0].Value.ParentKey.should.equal('$eventContext(EventSourceId)');
+        child.Children.children.From[0].Value.Properties.happened.should.equal('$eventContext(Occurred)');
+    });
+});

package/projections/eventContextPropertyExpression.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventContext } from '../events/EventContext.js';
+import { InvalidEventContextPropertyError } from './InvalidEventContextPropertyError.js';
+
+// EventContext is an interface (erased at runtime). Keep this exhaustive against its keys so
+// additions/removals to the SDK type cannot silently leave registration validation out of date.
+const contextProperties = {
+    sequenceNumber: true,
+    eventSourceId: true,
+    eventStore: true,
+    namespace: true,
+    eventSourceType: true,
+    eventStreamType: true,
+    eventStreamId: true,
+    subject: true,
+    hash: true,
+    causedBy: true,
+    observationState: true,
+    eventType: true,
+    occurred: true,
+    correlationId: true,
+    causation: true,
+    tags: true
+} satisfies Record<keyof EventContext, true>;
+
+// Mirror the kernel's DerivedPropertyFunctions registry: Week() applies to dates only.
+const derivedFunctions: Record<string, string> = { week: 'Week' };
+const dateProperties = new Set(['occurred']);
+const identityProperties = new Set(['subject', 'name', 'userName']);
+
+function lower(segment: string): string {
+    return segment.charAt(0).toLowerCase() + segment.slice(1);
+}
+
+// Accept only paths the kernel can resolve: a root property or an identity member of causedBy.
+// causedBy.onBehalfOf is allowed only as a whole value: traversing it when it is missing makes the
+// kernel construct identities recursively. Nothing inside the causation or tags collections, which a
+// dotted path cannot traverse.
+function validNestedPath(root: string, segments: string[]): boolean {
+    if (segments.length === 0) return true;
+    if (root !== 'causedBy') return false;
+    const members = segments.map(lower);
+    return members.length === 1 && (identityProperties.has(members[0]) || members[0] === 'onBehalfOf');
+}
+
+/** Build the expression read by Chronicle's event-context resolver, using CLR property casing. */
+export function eventContextPropertyExpression(propertyPath: string): string {
+    // The kernel accepts dotted CLR paths (and terminal derived-property functions) using
+    // [A-Za-z.()]. Reject unsupported characters and unknown root properties before registration.
+    const segments = propertyPath.split('.');
+    const contextProperty = segments[0].charAt(0).toLowerCase() + segments[0].slice(1);
+    if (!/^[A-Za-z]+(?:\.[A-Za-z]+)*(?:\(\))?$/.test(propertyPath) ||
+        !Object.hasOwn(contextProperties, contextProperty)) {
+        throw new InvalidEventContextPropertyError(propertyPath);
+    }
+    const lastIndex = segments.length - 1;
+    const isFunction = segments[lastIndex].endsWith('()');
+    if (isFunction) {
+        const functionName = segments[lastIndex].slice(0, -2).toLowerCase();
+        if (!Object.hasOwn(derivedFunctions, functionName) || lastIndex !== 1 || !dateProperties.has(contextProperty)) {
+            throw new InvalidEventContextPropertyError(propertyPath);
+        }
+        segments[lastIndex] = derivedFunctions[functionName];
+    } else if (segments.some(segment => Object.hasOwn(derivedFunctions, segment.toLowerCase())) ||
+        !validNestedPath(contextProperty, segments.slice(1))) {
+        throw new InvalidEventContextPropertyError(propertyPath);
+    }
+    const clrPath = segments.map(segment => segment.charAt(0).toUpperCase() + segment.slice(1)).join('.');
+    return `$eventContext(${clrPath}${propertyPath.endsWith('()') ? '()' : ''})`;
+}

package/projections/index.ts

@@ -7,6 +7,7 @@ export { Projections } from './Projections.js';
 export type { ProjectionState } from './ProjectionState.js';
 export type { ProjectionQueryResult } from './ProjectionQueryResult.js';
 export { UnableToQueryProjection } from './UnableToQueryProjection.js';
+export { InvalidEventContextPropertyError } from './InvalidEventContextPropertyError.js';
 export { VariantMustDeclareEntersOnEvent } from './VariantMustDeclareEntersOnEvent.js';
 export { GlobalHandlerPropertyNotOnVariant } from './GlobalHandlerPropertyNotOnVariant.js';
 export * from './declarative/index.js';

package/projections/invalidEventContextPropertyInProjection.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 { InvalidEventContextPropertyError } from './InvalidEventContextPropertyError.js';
+
+/** Add projection and read-model context to a rejected event-context path. */
+export function invalidEventContextPropertyInProjection(
+    error: InvalidEventContextPropertyError,
+    projectionName: string,
+    readModelId: string
+): Error {
+    return new Error(`Invalid event context property '${error.propertyPath}' in projection '${projectionName}' (read model '${readModelId}').`, { cause: error });
+}

package/projections/modelBound/childrenAndNestedBuilder.ts

@@ -6,6 +6,7 @@ import { AutoMap } from '@cratis/chronicle.contracts';
 import { Constructor, Fields } from '@cratis/fundamentals';
 import { TypeIntrospector } from '../../types/index.js';
 import { constantValueExpression } from '../constantValueExpression.js';
+import { eventContextPropertyExpression } from '../eventContextPropertyExpression.js';
 import { notSetPropertyPath } from '../notSetPropertyPath.js';
 import { getEventTypeFor } from '../../events/eventTypeDecorator.js';
 import { getAddFromMetadata } from './addFrom.js';
@@ -109,7 +110,7 @@ export function applyPropertyMappings(prototype: object, property: string, fromB
 
     for (const mapping of getSetFromContextMetadata(prototype, property)) {
         const entry = ensureFromEntry(fromByEventType, mapping.eventType);
-        entry.Value.Properties[property] = mapping.contextPropertyName ?? property;
+        entry.Value.Properties[property] = eventContextPropertyExpression(mapping.contextPropertyName ?? property);
     }
 
     for (const mapping of getSetValueMetadata(prototype, property)) {

package/reactors/ReactorServices.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { IEventStore } from '../IEventStore.js';
+import type { IReadModels } from '../readModels/IReadModels.js';
+
+/** Services for the observation's owning store and namespace, not an application default store. */
+export interface ReactorServices {
+    /** The event store that owns this reactor observation. */
+    readonly eventStore: IEventStore;
+    /** The read models from the same event store (`eventStore.readModels`). */
+    readonly readModels: IReadModels;
+    /** Aborted when the observation disconnects or the client is disposed. */
+    readonly signal: AbortSignal;
+}