@cratis/chronicle 6.16.0 → 6.17.0

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

package/testing/projections/UnsupportedProjectionOperation.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A compiled projection uses a kernel feature outside the infrastructure-free scenario boundary. */
+export class UnsupportedProjectionOperation extends Error {
+    /**
+     * @param model - The read model being evaluated.
+     * @param contractPath - Location of the unsupported operation in the compiled contract.
+     * @param declaration - Source declaration responsible for the operation.
+     * @param reason - Why an infrastructure-free evaluation cannot represent it.
+     */
+    constructor(model: string, contractPath: string, declaration: string, reason: string) {
+        super(`UnsupportedProjectionOperation: ${model}, ${contractPath} (${declaration}): ${reason}`);
+        this.name = 'UnsupportedProjectionOperation';
+    }
+}

package/testing/projections/for_ProjectionCapabilities/given/Changed.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../../../../events/eventTypeDecorator.js';
+
+export class Changed { name!: string; quantity!: number; labels!: string[]; details!: object; }
+field(String)(Changed.prototype, 'name');
+field(Number)(Changed.prototype, 'quantity');
+field(Array)(Changed.prototype, 'labels');
+field(Object)(Changed.prototype, 'details');
+eventType('capability-changed')(Changed);

package/testing/projections/for_ProjectionCapabilities/given/Model.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 { field } from '@cratis/fundamentals';
+
+export class Model { id!: string; name!: string; quantity!: number; total!: number; state!: string; labels!: string[]; details!: object; }
+field(String)(Model.prototype, 'id');
+field(String)(Model.prototype, 'name');
+field(Number)(Model.prototype, 'quantity');
+field(Number)(Model.prototype, 'total');
+field(String)(Model.prototype, 'state');
+field(Array)(Model.prototype, 'labels');
+field(Object)(Model.prototype, 'details');

package/testing/projections/for_ProjectionCapabilities/given/Removed.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventType } from '../../../../events/eventTypeDecorator.js';
+
+export class Removed {}
+eventType('capability-removed')(Removed);

package/testing/projections/for_ProjectionCapabilities/given/compile.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../../../../artifacts/index.js';
+import { IProjectionBuilderFor } from '../../../../projections/declarative/IProjectionBuilderFor.js';
+import { IProjectionFor } from '../../../../projections/declarative/IProjectionFor.js';
+import { projection } from '../../../../projections/declarative/projection.js';
+import { fromEvent } from '../../../../projections/modelBound/fromEvent.js';
+import { ProjectionDefinitionCompiler } from '../../../../projections/ProjectionDefinitionCompiler.js';
+import { Changed } from './Changed.js';
+import { Model } from './Model.js';
+import { Removed } from './Removed.js';
+
+function artifacts(model: Constructor, projections: Constructor[], eventTypes: Constructor[]): IClientArtifactsProvider {
+    return {
+        readModels: [model], projections, eventTypes: [Changed, Removed, ...eventTypes],
+        globalForHandlers: [], reducers: [], reactors: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+    };
+}
+
+export function compileModelBound(configure: (model: typeof Model) => void = () => {}, eventTypes: Constructor[] = []) {
+    class Candidate extends Model {}
+    fromEvent(Changed)(Candidate);
+    configure(Candidate);
+    const compiled = new ProjectionDefinitionCompiler(artifacts(Candidate, [], eventTypes), 'test-sink').compile([], [Candidate]);
+    return { compiled, definition: compiled.definitions[0] };
+}
+
+export function compileDeclarative(define: (builder: IProjectionBuilderFor<Model>) => void, eventTypes: Constructor[] = []) {
+    class Candidate extends Model {}
+    class CandidateProjection implements IProjectionFor<Model> {
+        define(builder: IProjectionBuilderFor<Model>): void { define(builder); }
+    }
+    projection('capability-projection', Candidate)(CandidateProjection);
+    const compiled = new ProjectionDefinitionCompiler(artifacts(Candidate, [CandidateProjection], eventTypes), 'test-sink')
+        .compile([CandidateProjection], []);
+    return { compiled, definition: compiled.definitions[0] };
+}

package/testing/projections/for_ProjectionCapabilities/when_compiling_capability_evidence.spec.ts

@@ -0,0 +1,68 @@
+// 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 { chai, describe, it } from 'vitest';
+import { childrenFrom } from '../../../projections/modelBound/childrenFrom.js';
+import { entersOn } from '../../../projections/modelBound/entersOn.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { variantOf } from '../../../projections/modelBound/variantOf.js';
+import { getEventTypeJsonSchemaFor } from '../../../events/eventTypeDecorator.js';
+import { ProjectionDefinitionCompiler } from '../../../projections/ProjectionDefinitionCompiler.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { Changed } from './given/Changed.js';
+import { Removed } from './given/Removed.js';
+import { Model } from './given/Model.js';
+import { compileDeclarative, compileModelBound } from './given/compile.js';
+
+chai.should();
+
+describe('when compiling capability evidence', () => {
+    it('should retain model-bound variant declarations before joins and sibling removal obscure them', () => {
+        class Identity {}
+        class First extends Model {}
+        class Second extends Model {}
+        fromEvent(Changed)(First);
+        fromEvent(Removed)(Second);
+        variantOf(Identity, 'id')(First);
+        variantOf(Identity, 'id')(Second);
+        entersOn(Changed)(First);
+        entersOn(Removed)(Second);
+        const artifacts: IClientArtifactsProvider = {
+            readModels: [First, Second], projections: [], eventTypes: [Changed, Removed], globalForHandlers: [],
+            reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [], eventTypeMigrations: []
+        };
+        const compiled = new ProjectionDefinitionCompiler(artifacts, 'test-sink').compile([], [First, Second]);
+        const first = compiled.definitions[0];
+        compiled.provenance.get(first)!.should.deep.include({ contractPath: 'Variant', declaration: '@variantOf' });
+        compiled.provenance.get(first)!.should.deep.include({ contractPath: 'EntersOn[capability-changed:1]', declaration: '@entersOn' });
+        compiled.eventSchemas.get(first)!.has('capability-removed:1:0').should.be.true;
+        (first.RemovedWith?.length ?? 0).should.equal(1);
+    });
+
+    it('should retain declarative variant provenance before update-only joins replace From', () => {
+        class Identity {}
+        const { compiled, definition } = compileDeclarative(builder => builder
+            .variantOf(Identity, model => model.id).entersOn(Changed).from(Changed).from(Removed));
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'Variant', declaration: '.variantOf' });
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'From[capability-removed:1]', declaration: '.from' });
+        (definition.Join?.length ?? 0).should.equal(1);
+        compiled.eventSchemas.get(definition)!.has('capability-removed:1:0').should.be.true;
+    });
+
+    it('should catalog child events even though no root From entry refers to them', () => {
+        const { compiled, definition } = compileModelBound(model => childrenFrom(Removed)(model.prototype, 'name'));
+        compiled.eventSchemas.get(definition)!.has('capability-removed:1:0').should.be.true;
+        compiled.provenance.get(definition)!.should.deep.include({ contractPath: 'Children.name', declaration: '@childrenFrom' });
+    });
+
+    it('should isolate event schemas from later compiles and registration metadata', () => {
+        const first = compileModelBound();
+        const second = compileModelBound();
+        const firstSchema = first.compiled.eventSchemas.get(first.definition)!.get('capability-changed:1:0')!.schema;
+        const secondSchema = second.compiled.eventSchemas.get(second.definition)!.get('capability-changed:1:0')!.schema;
+        firstSchema.properties!.name.type = 'boolean';
+        secondSchema.properties!.name.type.should.equal('string');
+        getEventTypeJsonSchemaFor(Changed).properties!.name.type.should.equal('string');
+    });
+});