@cratis/chronicle 6.16.0 → 6.17.0

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/eventContractPath.ts

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

package/projections/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/Reactors.ts

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

package/reactors/for_Reactors/when_delivering/with_activation.spec.ts

@@ -11,6 +11,7 @@ import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifac
 import { ArtifactDelivery } from '../../../artifacts/ArtifactDelivery.js';
 import { ArtifactKind } from '../../../artifacts/ArtifactKind.js';
 import type { ArtifactActivationContext } from '../../../artifacts/ArtifactActivationContext.js';
+import type { ArtifactInvocationContext } from '../../../artifacts/ArtifactInvocationContext.js';
 import type { ClientArtifactsActivator } from '../../../artifacts/ClientArtifactsActivator.js';
 import type { IEventStore } from '../../../IEventStore.js';
 import type { IEventLog } from '../../../eventSequences/IEventLog.js';
@@ -159,10 +160,11 @@ describe('when delivering reactor batches', () => {
         observed.length = 0;
         serviceReferences.length = 0;
         const contexts: ArtifactActivationContext[] = [];
+        const invocations: ArtifactInvocationContext[] = [];
         const boundaries: string[] = [];
         const activator: ClientArtifactsActivator = (type, context) => {
             contexts.push(context);
-            return { instance: new type(), run: async callback => { boundaries.push('enter');
+            return { instance: new type(), run: async (callback, invocation) => { invocations.push(invocation!); boundaries.push('enter');
                 try { return await callback(); } finally { boundaries.push('exit'); } },
             dispose: () => { boundaries.push('dispose'); } };
         };
@@ -177,6 +179,11 @@ describe('when delivering reactor batches', () => {
         contexts[0].readModels.should.equal(result.store.readModels);
         if (contexts[0].delivery === ArtifactDelivery.Events) contexts[0].eventContext.sequenceNumber.should.equal(1n);
         boundaries.should.deep.equal(['enter', 'exit', 'enter', 'exit', 'dispose', 'enter', 'exit', 'dispose']);
+        invocations.map(invocation => invocation.delivery).should.deep.equal([ArtifactDelivery.Events, ArtifactDelivery.Events, ArtifactDelivery.Events]);
+        invocations.map(invocation => invocation.delivery === ArtifactDelivery.Events ? invocation.eventContext.sequenceNumber : 0n)
+            .should.deep.equal([1n, 2n, 3n]);
+        invocations.map(invocation => invocation.delivery === ArtifactDelivery.Events ? invocation.methodName : '')
+            .should.deep.equal(['activationEvent', 'activationEvent', 'activationEvent']);
         observed.should.deep.equal(['one:book-1', 'two:book-1', 'three:book-1']);
         serviceReferences.every(services => services.eventStore === result.store && services.readModels === result.store.readModels).should.be.true;
     });
@@ -241,9 +248,16 @@ describe('when delivering reactor batches', () => {
     it('should notify separately before processing events in the same message', async () => {
         observed.length = 0;
         const contexts: ArtifactActivationContext[] = [];
-        const activator: ClientArtifactsActivator = (type, context) => { contexts.push(context); return { instance: new type() }; };
+        const invocations: ArtifactInvocationContext[] = [];
+        const activator: ClientArtifactsActivator = (type, context) => { contexts.push(context); return { instance: new type(),
+            run: async (callback, invocation) => { invocations.push(invocation!); return callback(); } }; };
         const result = await observe(ActivationReactor, [delivery([event('live', 1n)], ReplayState.BeginReplay)], 'tenant-a', activator);
         observed.should.deep.equal(['notification', 'live:book-1']);
+        invocations.should.deep.equal([
+            { delivery: ArtifactDelivery.ReplayNotification, replayState: ReplayState.BeginReplay },
+            { delivery: ArtifactDelivery.Events, eventContext: contexts[1].delivery === ArtifactDelivery.Events ? contexts[1].eventContext : undefined,
+                methodName: 'activationEvent' }
+        ]);
         contexts.map(context => context.delivery).should.deep.equal([ArtifactDelivery.ReplayNotification, ArtifactDelivery.Events]);
         result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
     });
@@ -370,6 +384,83 @@ describe('when delivering reactor batches', () => {
         reactors.dispose();
     });
 
+    it('should fail a replay notification when completion fails and suppress event handling', async () => {
+        observed.length = 0;
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = (type, context) => ({ instance: new type(),
+            complete: () => { steps.push('complete'); if (context.delivery === ArtifactDelivery.ReplayNotification) throw new Error('replay cleanup'); },
+            dispose: () => { steps.push('dispose'); } });
+        const result = await observe(ActivationReactor, [delivery([event('one', 1n)], ReplayState.BeginReplay)], 'tenant-a', activator);
+        observed.should.deep.equal(['notification']);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['ArtifactCompletionFailed: Artifact completion failed: Error: replay cleanup']);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+    });
+
+    it('should preserve both replay notification and completion errors', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: () => { steps.push('complete'); throw new Error('replay cleanup'); },
+            dispose: () => { steps.push('dispose'); } });
+        const result = await observe(FailingNotificationReactor, [delivery([event('one', 1n)], ReplayState.BeginReplay)], 'tenant-a', activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal([
+            'Error: notification failed', 'ArtifactCompletionFailed: Artifact completion failed: Error: replay cleanup'
+        ]);
+    });
+
+    it('should complete each successful lease before acknowledgement and then dispose it', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: () => { steps.push('complete'); }, dispose: () => { steps.push('dispose'); } });
+        const result = await observe(ActivationReactor, [delivery([event('one', 1n), event('two', 2n)])], 'tenant-a', activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
+    });
+
+    it('should complete after processing failure before acknowledgement and preserve the processing error', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: () => { steps.push('complete'); }, dispose: () => { steps.push('dispose'); } });
+        const result = await observe(AppendReactor, [delivery([event('one', 1n)])], 'tenant-a', activator, false);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['Error: append rejected']);
+    });
+
+    it('should fail completion distinctly without advancing a successful checkpoint and still dispose', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: async () => { steps.push('complete'); throw new Error('scope cleanup'); },
+            dispose: () => { steps.push('dispose'); } });
+        const result = await observe(ActivationReactor, [delivery([event('one', 1n), event('two', 2n)])], 'tenant-a', activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['ArtifactCompletionFailed: Artifact completion failed: Error: scope cleanup']);
+    });
+
+    it('should report both processing and completion errors without acknowledging earlier successful events', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: () => { steps.push('complete'); throw new Error('scope cleanup'); },
+            dispose: () => { steps.push('dispose'); } });
+        const result = await observe(AppendReactor, [delivery([event('one', 1n), event('two', 2n)])], 'tenant-a', activator, false);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal([
+            'Error: append rejected', 'ArtifactCompletionFailed: Artifact completion failed: Error: scope cleanup'
+        ]);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+    });
+
+    it('should leave a processing failure unchanged when legacy disposal also fails', async () => {
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            dispose: () => { throw new Error('legacy cleanup'); } });
+        const result = await observe(AppendReactor, [delivery([event('one', 1n)])], 'tenant-a', activator, false);
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Failed);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['Error: append rejected']);
+    });
+
     it('should log disposal failure without changing successful acknowledgement', async () => {
         const errors: string[] = [];
         diag.setLogger({ error: (...values: unknown[]) => { errors.push(values.map(String).join(' ')); } } as DiagLogger, DiagLogLevel.ERROR);

package/readModels/rootReadModelTypes.ts

@@ -4,6 +4,9 @@
 import { type Constructor } from '@cratis/fundamentals';
 import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
 import { getProjectionMetadata } from '../projections/declarative/projection.js';
+import { InvalidEventContextPropertyError } from '../projections/InvalidEventContextPropertyError.js';
+import { invalidEventContextPropertyInProjection } from '../projections/invalidEventContextPropertyInProjection.js';
+import { getReadModelId } from './readModel.js';
 import { ProjectionBuilderFor } from '../projections/declarative/ProjectionBuilderFor.js';
 import type { ChildrenDefinitionLike } from '../projections/declarative/ProjectionBuilderCore.js';
 import type { IProjectionFor } from '../projections/declarative/IProjectionFor.js';
@@ -53,7 +56,14 @@ function inspectReadModelTypes(artifacts: IClientArtifactsProvider): { models: C
         if (!model) continue;
         inspect(model);
         const builder = new ProjectionBuilderFor<unknown>();
-        (new type() as IProjectionFor<unknown>).define(builder);
+        try {
+            (new type() as IProjectionFor<unknown>).define(builder);
+        } catch (error) {
+            if (error instanceof InvalidEventContextPropertyError) {
+                throw invalidEventContextPropertyInProjection(error, type.name, getReadModelId(model));
+            }
+            throw error;
+        }
         inspectDeclarative(model, builder.getSubobjectDefinitions());
     }
     for (const type of artifacts.reducers) {