@cratis/chronicle 6.16.1 → 6.17.0

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

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

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

@@ -27,6 +27,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 reducer observations by event source ID. */
 const EVENT_SOURCE_ID_KEY = '$eventSourceId';
@@ -367,12 +368,16 @@ export class Reducers implements IReducers {
                             signal: controller.signal, delivery: ArtifactDelivery.ReplayNotification,
                             replayState: operation.ReplayState
                         }, this._artifactActivator, artifact => runActivated(artifact, () =>
-                            notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition)));
+                            notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition),
+                            { delivery: ArtifactDelivery.ReplayNotification, replayState: operation.ReplayState }));
                     } else if (reducerInstance) {
                         await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
                     }
                 } catch (err) {
                     this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: 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;
@@ -409,7 +414,8 @@ export class Reducers implements IReducers {
                                 hasState: currentState !== undefined
                             });
 
-                            currentState = await runActivated(artifact, () => dispatcher.invoke(artifact.instance, entry, content, currentState, context));
+                            currentState = await runActivated(artifact, () => dispatcher.invoke(artifact.instance, entry, content, currentState, context),
+                                { delivery: ArtifactDelivery.Events, eventContext: context, methodName: entry.methodName });
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
                             this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
@@ -437,8 +443,13 @@ export class Reducers implements IReducers {
                     } catch (err) {
                         this._logger.error('Error activating reducer', { reducerId: 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: reducerInstance ?? {} });

package/reducers/for_Reducers/when_delivering/with_activation.spec.ts

@@ -9,6 +9,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 { eventType } from '../../../events/eventTypeDecorator.js';
@@ -92,10 +93,11 @@ describe('when delivering reducer batches', () => {
         instances.length = 0;
         notifications.length = 0;
         const contexts: ArtifactActivationContext[] = [];
+        const invocations: ArtifactInvocationContext[] = [];
         const steps: string[] = [];
         const activator: ClientArtifactsActivator = (type, context) => {
             contexts.push(context);
-            return { instance: new type(), run: async callback => { steps.push('enter');
+            return { instance: new type(), run: async (callback, invocation) => { invocations.push(invocation!); steps.push('enter');
                 try { return await callback(); } finally { steps.push('exit'); } },
             dispose: () => { steps.push('dispose'); } };
         };
@@ -108,6 +110,11 @@ describe('when delivering reducer batches', () => {
         if (contexts[1].delivery === ArtifactDelivery.Events) contexts[1].eventContext.sequenceNumber.should.equal(1n);
         notifications.should.deep.equal(['begin']);
         steps.should.deep.equal(['enter', 'exit', 'dispose', 'enter', 'exit', 'enter', 'exit', 'dispose', 'enter', 'exit', 'dispose']);
+        invocations[0].should.deep.equal({ delivery: ArtifactDelivery.ReplayNotification, replayState: ReplayState.BeginReplay });
+        invocations.slice(1).map(invocation => invocation.delivery === ArtifactDelivery.Events ? invocation.eventContext.sequenceNumber : 0n)
+            .should.deep.equal([1n, 2n, 3n]);
+        invocations.slice(1).map(invocation => invocation.delivery === ArtifactDelivery.Events ? invocation.methodName : '')
+            .should.deep.equal(['reductionEvent', 'reductionEvent', 'reductionEvent']);
         result.acknowledgements[0]?.ReadModelState.should.equal('{"count":3}');
     });
 
@@ -166,6 +173,65 @@ describe('when delivering reducer batches', () => {
         }
     });
 
+    it('should fail a replay notification on completion failure without processing events or publishing state', async () => {
+        notifications.length = 0;
+        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(CountingReducer, [batch([event(1, 1n)], ReplayState.BeginReplay)], activator);
+        notifications.should.deep.equal(['begin']);
+        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);
+        result.acknowledgements[0]?.ReadModelState.should.equal('');
+    });
+
+    it('should complete once per successful lease before publishing reduced state and then dispose', async () => {
+        const steps: string[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(),
+            complete: () => { steps.push('complete'); }, dispose: () => { steps.push('dispose'); } });
+        const result = await observe(CountingReducer, [batch([event(1, 1n), event(2, 2n)])], activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ReadModelState.should.equal('{"count":3}');
+    });
+
+    it('should complete after handler failure 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(FailingReducer, [batch([event(1, 1n)])], activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal(['Error: reduction failed']);
+    });
+
+    it('should fail completion distinctly, discard the tentative state and checkpoint, then 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(CountingReducer, [batch([event(1, 1n), event(2, 2n)])], activator);
+        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: scope cleanup']);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(4294967295n);
+        result.acknowledgements[0]?.ReadModelState.should.equal('');
+    });
+
+    it('should preserve both failures when completion also fails after processing', 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(FailingReducer, [batch([event(1, 1n)])], activator);
+        steps.should.deep.equal(['complete', 'dispose']);
+        result.acknowledgements[0]?.ExceptionMessages.should.deep.equal([
+            'Error: reduction failed', 'ArtifactCompletionFailed: Artifact completion failed: Error: scope cleanup'
+        ]);
+        result.acknowledgements[0]?.ReadModelState.should.equal('');
+    });
+
     it('should dispose after handler failure without acknowledging the failed event', async () => {
         let disposed = 0;
         const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: () => { disposed++; } });

package/testing/projections/ProjectionCapabilities.ts

@@ -0,0 +1,213 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AutoMap, type ProjectionDefinition } from '@cratis/chronicle.contracts';
+import { EventSequenceId } from '../../eventSequences/EventSequenceId.js';
+import type { CompiledProjectionDefinitions } from '../../projections/CompiledProjectionDefinitions.js';
+import { eventContractPath } from '../../projections/eventContractPath.js';
+import { eventContextPropertyExpression } from '../../projections/eventContextPropertyExpression.js';
+import { InvalidEventContextPropertyError } from '../../projections/InvalidEventContextPropertyError.js';
+import type { ContractEventType, FromRecord, RemovedWithRecord } from '../../projections/declarative/ProjectionBuilderCore.js';
+import { getEventTypeMapKey } from '../../projections/modelBound/childrenAndNestedBuilder.js';
+import type { JsonSchema } from '../../schemas/JsonSchema.js';
+import { UnsupportedProjectionOperation } from './UnsupportedProjectionOperation.js';
+
+/** Validates *all* subscribed operations against the bounded scenario subset, before replay. */
+export class ProjectionCapabilities {
+    /**
+     * Throws with the original declaration and contract path for the first unsupported operation.
+     * @param compiled - Definitions and their schema/provenance evidence.
+     * @param definition - The compiled contract to validate.
+     */
+    static validate(compiled: CompiledProjectionDefinitions, definition: ProjectionDefinition): void {
+        const model = String(definition.ReadModel ?? definition.Identifier ?? '<unknown>');
+        const wire = definition as unknown as Record<string, unknown>;
+        const reject = (path: string, reason: string, fallback?: string) : never => {
+            const source = compiled.provenance.get(definition)?.find(entry => entry.contractPath.startsWith('From['))?.declaration ?? '.from';
+            const declaration = compiled.provenance.get(definition)?.find(entry => entry.contractPath === path)?.declaration
+                ?? fallback ?? (path.includes('.AutoMap.') ? `${source} (AutoMap)`
+                    : path.startsWith('InitialModelState') ? '.withInitialValues'
+                        : path.startsWith('ReadModel') ? source : 'contract');
+            throw new UnsupportedProjectionOperation(model, path, declaration, reason);
+        };
+        if (!compiled.definitions.includes(definition)) reject('Definition', 'definition is not part of this compile');
+        const provenance = compiled.provenance.get(definition) ?? reject('Definition', 'capability provenance is unavailable');
+        const catalog = compiled.eventSchemas.get(definition) ?? reject('Definition', 'event-schema catalog is unavailable');
+        const variant = provenance.find(entry => entry.contractPath === 'Variant');
+        if (variant) reject('Variant', 'variants require a kernel-backed test');
+        if (wire.IsActive === false) reject('IsActive', 'passive projections require a kernel-backed test');
+        if (wire.EventSequenceId !== EventSequenceId.eventLog.value) reject('EventSequenceId', 'non-default event sequences require a kernel-backed test');
+        for (const section of ['Join', 'Children', 'Nested', 'RemovedWithJoin'] as const) {
+            const value = wire[section];
+            const paths = Array.isArray(value) ? value.map((entry: { Key: ContractEventType }) => eventContractPath(section, entry.Key))
+                : Object.keys(value as Record<string, unknown> ?? {}).map(property => `${section}.${property}`);
+            if (paths.length) reject(paths[0], `${section === 'Children' ? 'children projections' : section === 'Nested' ? 'nested projections' : section === 'Join' ? 'joins' : 'removedWithJoin'} require a kernel-backed test`);
+        }
+        if ((wire.FromEvery as unknown[] | undefined)?.length) reject('FromEvery', 'derivative projections require a kernel-backed test');
+        if (wire.FromEventProperty) reject('FromEventProperty', 'event-property subscriptions require a kernel-backed test');
+        const all = wire.All as { Properties?: Record<string, string>; IncludeChildren?: boolean; AutoMap?: AutoMap } | undefined;
+        if (provenance.some(entry => entry.contractPath === 'All') || all?.IncludeChildren ||
+            Object.keys(all?.Properties ?? {}).length || all?.AutoMap === AutoMap.Enabled) {
+            reject('All', 'fromEvery/all subscriptions require a kernel-backed test');
+        }
+
+        const readModel = compiled.readModels.find(candidate => candidate.Type.Identifier === model)
+            ?? reject('ReadModel', 'a single registered read-model schema is required');
+        let schema: JsonSchema;
+        try {
+            schema = JSON.parse(readModel.Schema) as JsonSchema;
+        } catch {
+            reject('ReadModel.Schema', 'read-model schema is not valid JSON');
+        }
+        const identifier = schema!.properties?.id ?? schema!.properties?.Id ?? { type: 'string' };
+        if (!((identifier.type === 'string' && (!identifier.format || identifier.format === 'guid')) ||
+            (identifier.type === 'number' && (!identifier.format || identifier.format === 'double')) ||
+            (identifier.type === 'integer' && ['int32', 'uint32'].includes(identifier.format ?? '')))) {
+            reject('ReadModel.Schema.id', 'identifier schema must be string, number, or GUID (int32/uint32 identifiers are supported)');
+        }
+        let initial: unknown;
+        try { initial = JSON.parse(String(wire.InitialModelState ?? '{}')); } catch { reject('InitialModelState', 'initial values must be a JSON object'); }
+        if (initial === null || typeof initial !== 'object' || Array.isArray(initial)) reject('InitialModelState', 'initial values must be a JSON object');
+        for (const [property, value] of Object.entries(initial as Record<string, unknown>)) {
+            const target = schema!.properties?.[property]
+                ?? reject(`InitialModelState.${property}`, 'initial value has no read-model schema');
+            this.checkSchema(target, `InitialModelState.${property}`, reject);
+            if (typeof value === 'number') {
+                const outsideIntegerRange = !Number.isSafeInteger(value) ||
+                    (target.format === 'int32' && (value < -2147483648 || value > 2147483647)) ||
+                    (target.format === 'uint32' && (value < 0 || value > 4294967295));
+                if (!Number.isFinite(value) || (target.type === 'integer' && outsideIntegerRange)) {
+                    reject(`InitialModelState.${property}`, 'initial numeric value is outside the supported finite/integer range');
+                }
+            }
+        }
+        const generations = new Map<string, number>();
+        const requireEventSchema = (eventType: ContractEventType, path: string): JsonSchema => {
+            const previous = generations.get(eventType.Id);
+            if (previous !== undefined && previous !== eventType.Generation) reject(path, 'multiple generations of the same event-type id require a kernel-backed test');
+            generations.set(eventType.Id, eventType.Generation);
+            const event = catalog.get(getEventTypeMapKey(eventType)) ?? reject(path, 'participating event schema is unavailable');
+            return event.schema;
+        };
+        const from = wire.From as FromRecord[] ?? [];
+        const removedWith = wire.RemovedWith as RemovedWithRecord[] ?? [];
+        for (const entry of [...from, ...removedWith]) {
+            const section = from.includes(entry as FromRecord) ? 'From' : 'RemovedWith';
+            const path = eventContractPath(section, entry.Key);
+            const eventSchema = requireEventSchema(entry.Key, path);
+            if (entry.Value.Key !== '$eventSourceId') reject(`${path}.Key`, 'only $eventSourceId keys are supported');
+            if (entry.Value.ParentKey) reject(`${path}.ParentKey`, 'parent keys require a kernel-backed test');
+            if (section === 'RemovedWith') continue;
+            const properties = (entry as FromRecord).Value.Properties ?? {};
+            for (const [property, expression] of Object.entries(properties)) {
+                const mappingPath = `${path}.Properties.${property}`;
+                this.checkMapping(schema!, eventSchema, property, expression, mappingPath, reject);
+            }
+            const expressions = Object.values(properties);
+            const aggregateOnly = expressions.length > 0 && expressions.every(expression =>
+                /^(?:\$add\([^()]+\)|\$subtract\([^()]+\)|\$count|\$increment|\$decrement)$/.test(expression));
+            if (wire.AutoMap === AutoMap.Enabled && !aggregateOnly) {
+                this.checkAutoMap(schema!, eventSchema, properties, wire.NoAutoMapProperties as string[] ?? [], path, reject);
+            }
+        }
+    }
+
+    private static checkAutoMap(
+        modelSchema: JsonSchema, eventSchema: JsonSchema, explicit: Record<string, string>, exclusions: string[],
+        path: string, reject: (path: string, reason: string) => never
+    ): void {
+        for (const [destination] of Object.entries(modelSchema.properties ?? {})) {
+            if (destination in explicit || exclusions.includes(destination)) continue;
+            const candidates = Object.keys(eventSchema.properties ?? {}).filter(source => source.toLowerCase() === destination.toLowerCase());
+            if (candidates.length > 1) reject(`${path}.AutoMap.${destination}`, `inferred AutoMap source is ambiguous: ${candidates.join(', ')}`);
+            if (candidates.length) this.checkMapping(modelSchema, eventSchema, destination, candidates[0], `${path}.AutoMap.${destination}`, reject);
+        }
+    }
+
+    private static checkMapping(
+        modelSchema: JsonSchema, eventSchema: JsonSchema, destination: string, expression: string,
+        path: string, reject: (path: string, reason: string) => never
+    ): void {
+        const fail = (reason: string): never => reject(path, `expression '${expression}': ${reason}`);
+        const target = modelSchema.properties?.[destination]
+            ?? fail('dynamic or unknown destination paths require a kernel-backed test');
+        if (destination.includes('.') || destination.includes('$')) fail('dynamic or unknown destination paths require a kernel-backed test');
+        this.checkSchema(target, path, (_path, reason) => fail(reason));
+        if (expression === '$eventSourceId' || expression === '$null') return;
+        if (expression.startsWith('$eventContext(')) {
+            if (/^\$eventContext\(.+\(\)\)$/.test(expression)) fail('derived event-context functions require a kernel-backed test');
+            const path = /^\$eventContext\(([^()]*)\)$/.exec(expression)?.[1];
+            if (path) {
+                try {
+                    if (eventContextPropertyExpression(path) === expression) return;
+                } catch (error) {
+                    if (!(error instanceof InvalidEventContextPropertyError)) throw error;
+                }
+            }
+            fail('event-context path is not supported by the client');
+        }
+        if (/^\$value\([\p{L}\p{Mn}\p{Nd}\p{Pc} ._/:*+-]*\)$/u.test(expression)) {
+            const text = expression.slice(7, -1);
+            if (target.format === 'date-time') fail('$value date-time literals require a kernel-backed test');
+            if (this.numeric(target)) {
+                if (!/^[+-]?(?:\d+(?:\.\d+)?|\.\d+)$/.test(text) || !Number.isFinite(Number(text)) ||
+                    (target.type === 'integer' && (!Number.isSafeInteger(Number(text)) ||
+                        (target.format === 'int32' && (Number(text) < -2147483648 || Number(text) > 2147483647)) ||
+                        (target.format === 'uint32' && (Number(text) < 0 || Number(text) > 4294967295))))) {
+                    fail('$value numeric literal is outside the supported finite/integer range');
+                }
+            } else if (target.type === 'boolean' && !/^(?:true|false)$/i.test(text)) {
+                fail('$value boolean literal must be true or false');
+            } else if (target.format === 'guid' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text)) {
+                fail('$value GUID literal is not canonical');
+            } else if (target.type === 'object' || target.type === 'array') {
+                fail('$value object/array literals require a kernel-backed test');
+            }
+            return;
+        }
+        const operation = /^(\$add|\$subtract)\(([^()]+)\)$/.exec(expression);
+        const arithmetic = operation || ['$count', '$increment', '$decrement'].includes(expression);
+        if (arithmetic) {
+            if (!this.numeric(target)) fail('arithmetic requires a supported finite number/double or int32/uint32 schema (not float, decimal, duration, or int64)');
+            if (operation) {
+                const operand = this.propertyAt(eventSchema, operation[2]);
+                if (!operand || !this.numeric(operand)) fail('arithmetic operand requires a supported numeric event schema');
+            }
+            return;
+        }
+        if (/^[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)*$/.test(expression)) {
+            const source = this.propertyAt(eventSchema, expression);
+            if (!source) return fail(`event property '${expression}' is absent from the participating event schema`);
+            this.checkSchema(source, path, (_path, reason) => fail(reason));
+            return;
+        }
+        if (expression.startsWith('$context.')) {
+            return fail('is a legacy expression the kernel does not resolve; event-context mappings use $eventContext(...)');
+        }
+        fail('requires a kernel-backed test');
+    }
+
+    private static propertyAt(schema: JsonSchema, path: string): JsonSchema | undefined {
+        return path.split('.').reduce<JsonSchema | undefined>((current, segment) => current?.properties?.[segment], schema);
+    }
+
+    private static numeric(schema: JsonSchema): boolean {
+        return (schema.type === 'number' && (!schema.format || schema.format === 'double')) ||
+            (schema.type === 'integer' && ['int32', 'uint32'].includes(schema.format ?? ''));
+    }
+
+    private static checkSchema(schema: JsonSchema, path: string, reject: (path: string, reason: string) => never): void {
+        if (!schema.type || schema.type === 'null' || (schema.format && !['guid', 'date-time', 'double', 'int32', 'uint32'].includes(schema.format)) ||
+            (schema.format === 'date-time' && schema.type !== 'string') ||
+            (schema.format === 'guid' && schema.type !== 'string') ||
+            (schema.format === 'double' && schema.type !== 'number') ||
+            (['int32', 'uint32'].includes(schema.format ?? '') && schema.type !== 'integer')) {
+            reject(path, `schema type/format '${schema.type ?? 'unknown'}${schema.format ? `/${schema.format}` : ''}' requires a kernel-backed test`);
+        }
+        if (schema.type === 'integer' && !this.numeric(schema)) reject(path, 'integer width requires a kernel-backed test');
+        if (schema.type === 'array' && schema.items) this.checkSchema(schema.items, path, reject);
+        if (schema.type === 'object') {
+            for (const property of Object.values(schema.properties ?? {})) this.checkSchema(property, path, reject);
+        }
+    }
+}