@cratis/chronicle 6.22.1 → 6.23.0

package/testing/EventScenario.ts

@@ -3,6 +3,7 @@
 
 import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
 import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import { TypeIntrospector } from '../types/TypeIntrospector.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { AppendResult } from '../eventSequences/AppendResult.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
@@ -10,8 +11,12 @@ import type { AppendedEvent } from '../events/AppendedEvent.js';
 import type { IEventSequence } from '../eventSequences/IEventSequence.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
-import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getEventTypeFor, getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { compileConstraints } from '../events/constraints/Constraints.js';
 import { getUniqueEventMetadata, getUniquePropertyMetadata } from '../events/constraints/unique.js';
+import { getRemovedConstraintNames } from '../events/constraints/removeConstraint.js';
+import { getConstraintMetadata } from '../events/constraints/constraint.js';
+import { InProcessConstraints } from './InProcessConstraints.js';
 import type { EventScenarioOptions } from './EventScenarioOptions.js';
 import { EventScenarioGivenBuilder } from './EventScenarioGivenBuilder.js';
 import { EventScenarioWhenBuilder } from './EventScenarioWhenBuilder.js';
@@ -19,6 +24,11 @@ import { InProcessEventSequence } from './InProcessEventSequence.js';
 import { registerScenarioSeed } from './EventScenarioSeed.js';
 import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
 
+function hasConstraintDecorators(type: Function): boolean {
+    return getUniqueEventMetadata(type) !== undefined || getRemovedConstraintNames(type).length > 0 ||
+        TypeIntrospector.getTrackedProperties(type).some(property => getUniquePropertyMetadata(type, property) !== undefined);
+}
+
 /** A kernel-free, fixture-bounded append scenario. No observer runs automatically. */
 export class EventScenario {
     readonly eventSequence: IEventSequence;
@@ -26,25 +36,76 @@ export class EventScenario {
     readonly when: EventScenarioWhenBuilder;
 
     constructor(options: EventScenarioOptions = {}) {
-        const artifacts = options.artifacts ?? new DefaultClientArtifactsProvider(TypeDiscoverer.default);
+        const selectedArtifacts = options.artifacts;
+        const selectedConstraints = selectedArtifacts?.constraints;
+        const artifacts = selectedArtifacts ?? new DefaultClientArtifactsProvider(TypeDiscoverer.default);
         const eventTypes = [...artifacts.eventTypes];
-        if (options.artifacts?.constraints?.length === 0 && options.constraints !== 'disabled') {
+        if (selectedConstraints?.length === 0 && options.constraints !== 'disabled') {
             throw new UnsupportedEventSequenceOperation('artifacts.constraints', 'empty constraint catalog',
                 'An empty selected catalog cannot silently disable constraint discovery; set constraints: disabled explicitly.');
         }
-        const discovered = options.artifacts?.constraints ?? new DefaultClientArtifactsProvider(TypeDiscoverer.default).constraints;
-        if (options.constraints !== 'disabled' && (discovered.length || eventTypes.some(type => {
-            const metadata = getEventTypeMetadata(type);
-            return getUniqueEventMetadata(type) || [...(metadata?.members.keys() ?? [])].some(key => getUniquePropertyMetadata(type, key));
-        }))) {
-            throw new UnsupportedEventSequenceOperation('artifacts.constraints', discovered.map(type => type.name).join(', ') || 'event metadata',
-                'Constraint definitions are rejected until kernel-backed constraint fixtures are available.');
+        const discoveredArtifacts = selectedArtifacts && selectedConstraints === undefined
+            ? new DefaultClientArtifactsProvider(TypeDiscoverer.default) : undefined;
+        const discovered = selectedConstraints ?? discoveredArtifacts?.constraints ?? artifacts.constraints;
+        let constraints: InProcessConstraints | undefined;
+        if (options.constraints !== 'disabled') {
+            for (const type of discovered ?? []) {
+                if (!getConstraintMetadata(type)) throw new UnsupportedEventSequenceOperation('artifacts.constraints', type.name,
+                    'Every selected constraint must have @constraint metadata.');
+            }
+            try {
+                // Keep global decorator contributions. A shadowed ID is accepted only when neither
+                // constructor has constraint decorators, so either one compiles to the same constraints.
+                const compiledEventTypes = [...new Set([...(discoveredArtifacts?.eventTypes ?? []), ...eventTypes])];
+                const constructorsById = new Map<string, (typeof eventTypes)[number]>();
+                for (const type of compiledEventTypes) {
+                    const id = getEventTypeFor(type).id.value;
+                    const previous = constructorsById.get(id);
+                    if (previous && previous !== type && (hasConstraintDecorators(previous) || hasConstraintDecorators(type))) {
+                        throw new UnsupportedEventSequenceOperation('artifacts.eventTypes', id,
+                            'Conflicting constructors share an event type ID; constraint discovery cannot choose one.');
+                    }
+                    constructorsById.set(id, type);
+                }
+                const compiled = compileConstraints({ eventTypes: [...constructorsById.values()], constraints: discovered ?? [] });
+                const selectedIds = new Set(eventTypes.map(type => getEventTypeFor(type).id.value));
+                const definitions = discoveredArtifacts ? new Map([...compiled].filter(([, capture]) => {
+                    const constrained = capture.uniqueConstraint?.eventDefinitions.map(entry => entry.eventTypeId) ??
+                        capture.uniqueEventType?.eventTypeIds ?? [capture.uniqueEventType?.eventTypeId];
+                    const removedWith = [...(capture.uniqueConstraint?.removedWithEventTypeIds ?? []),
+                        capture.uniqueConstraint?.removedWithEventTypeId,
+                        ...(capture.uniqueEventType?.removedWithEventTypeIds ?? [])];
+                    return [...constrained, ...removedWith].some(id => id !== undefined && selectedIds.has(id));
+                })) : compiled;
+                constraints = new InProcessConstraints(definitions);
+                for (const [name, capture] of definitions) {
+                    const ids = capture.uniqueConstraint?.eventDefinitions.map(entry => entry.eventTypeId) ??
+                        capture.uniqueEventType?.eventTypeIds ?? [capture.uniqueEventType?.eventTypeId];
+                    const removedWith = [...(capture.uniqueConstraint?.removedWithEventTypeIds ?? []),
+                        capture.uniqueConstraint?.removedWithEventTypeId,
+                        ...(capture.uniqueEventType?.removedWithEventTypeIds ?? [])];
+                    if ([...ids, ...removedWith].some(id => id !== undefined && !selectedIds.has(id))) {
+                        throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
+                            'Every constrained event type must be in the selected catalog.');
+                    }
+                    for (const entry of capture.uniqueConstraint?.eventDefinitions ?? []) {
+                        const type = eventTypes.find(type => getEventTypeFor(type).id.value === entry.eventTypeId)!;
+                        if (getEventTypeMetadata(type)?.schema.properties?.[entry.properties[0]]?.type !== 'string') {
+                            throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
+                                'The constrained property must be a schema-backed string.');
+                        }
+                    }
+                }
+            } catch (error) {
+                if (error instanceof UnsupportedEventSequenceOperation) throw error;
+                throw new UnsupportedEventSequenceOperation('artifacts.constraints', 'compiler', `Invalid constraint definition: ${String(error)}.`);
+            }
         }
         if (artifacts.eventTypeMigrations?.length) {
             throw new UnsupportedEventSequenceOperation('artifacts.eventTypeMigrations', artifacts.eventTypeMigrations.map(type => type.name).join(', '),
                 'Migrations are not fixture-backed.');
         }
-        const sequence = new InProcessEventSequence(options, eventTypes);
+        const sequence = new InProcessEventSequence(options, eventTypes, constraints);
         this.eventSequence = sequence;
         registerScenarioSeed(this, (source, events) => sequence.seed(source, events));
         this.given = new EventScenarioGivenBuilder(this);

package/testing/InProcessConstraints.ts

@@ -0,0 +1,127 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createHash } from 'node:crypto';
+import type { ConstraintViolation as ContractsConstraintViolation } from '@cratis/chronicle.contracts';
+import type { AppendedEvent } from '../events/AppendedEvent.js';
+import type { ConstraintCapture } from '../events/constraints/ConstraintBuilder.js';
+import { resolveConstraintMessage } from '../events/constraints/Constraints.js';
+import type { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+export type WireConstraintViolation = ContractsConstraintViolation;
+
+const unavailable = '18446744073709551615';
+
+/** Narrow, fixture-backed unscoped constraint validation over serialized event snapshots. */
+export class InProcessConstraints {
+    constructor(private readonly _definitions: ReadonlyMap<string, ConstraintCapture>) {
+        const coveredTypes = new Set<string>();
+        for (const [name, capture] of _definitions) {
+            if (capture.uniqueConstraint && capture.uniqueEventType) {
+                throw this.unsupported(name, 'A definition with both constraint kinds is not fixture-backed.');
+            }
+            if (capture.scope.perEventSourceType || capture.scope.perEventStreamType || capture.scope.perEventStreamId) {
+                throw this.unsupported(name, 'Scoped constraints are not fixture-backed.');
+            }
+            if (capture.uniqueConstraint) {
+                const unique = capture.uniqueConstraint;
+                if (unique.ignoreCasing || unique.removedWithEventTypeId || unique.removedWithEventTypeIds?.length ||
+                    unique.eventDefinitions.length === 0 || unique.eventDefinitions.some(entry => entry.properties.length !== 1 ||
+                        !/^[a-z][a-zA-Z0-9]*$/.test(entry.properties[0]))) {
+                    throw this.unsupported(name, 'Case folding, removal and composite or nested keys are not fixture-backed.');
+                }
+            } else if (capture.uniqueEventType) {
+                const unique = capture.uniqueEventType;
+                if (unique.removedWithEventTypeIds?.length || (unique.eventTypeIds?.length ?? 1) !== 1) {
+                    throw this.unsupported(name, 'Removal and multi-type unique event cycles are not fixture-backed.');
+                }
+            } else {
+                throw this.unsupported(name, 'Unknown constraint definition.');
+            }
+            const ids = capture.uniqueConstraint?.eventDefinitions.map(entry => entry.eventTypeId) ??
+                capture.uniqueEventType?.eventTypeIds ?? [capture.uniqueEventType!.eventTypeId];
+            for (const id of ids) {
+                if (coveredTypes.has(id)) throw this.unsupported(name, 'Overlapping constraints are not fixture-backed.');
+                coveredTypes.add(id);
+            }
+        }
+    }
+
+    /** Validate against committed history and all earlier entries of this append, without changing state. */
+    validate(history: readonly AppendedEvent[], incoming: readonly AppendedEvent[]): WireConstraintViolation[] {
+        const violations: WireConstraintViolation[] = [];
+        const stagedKeys = new Map<string, string>();
+        const stagedTypes = new Set<string>();
+        for (const event of incoming) {
+            const type = event.eventType.id.value;
+            const source = event.context.eventSourceId;
+            for (const [name, definition] of this._definitions) {
+                const property = definition.uniqueConstraint?.eventDefinitions.find(entry => entry.eventTypeId === type)?.properties[0];
+                if (property !== undefined) {
+                    const raw = event.content[property];
+                    // The oracle proves ordinal ASCII casing and significant spaces; no .NET Unicode folding or conversion is inferred.
+                    if (typeof raw !== 'string' || !/^[A-Za-z ]+$/.test(raw)) {
+                        throw this.unsupported(name, 'Only nonempty ASCII letter and space string keys are fixture-backed.');
+                    }
+                    const key = createHash('sha256').update(raw).digest('hex');
+                    const claims = new Map<string, { source: string; sequence: string }>();
+                    const owners = new Map<string, string>();
+                    for (const prior of history) {
+                        const priorProperty = definition.uniqueConstraint!.eventDefinitions.find(entry =>
+                            entry.eventTypeId === prior.eventType.id.value)?.properties[0];
+                        if (priorProperty !== undefined) {
+                            const priorValue = prior.content[priorProperty];
+                            if (typeof priorValue !== 'string') throw this.unsupported(name, 'History has an unproven key.');
+                            owners.set(prior.context.eventSourceId, createHash('sha256').update(priorValue).digest('hex'));
+                            claims.set(createHash('sha256').update(priorValue).digest('hex'), {
+                                source: prior.context.eventSourceId, sequence: prior.context.sequenceNumber.toString()
+                            });
+                        }
+                    }
+                    const ownerKey = owners.get(source);
+                    if (ownerKey !== undefined && ownerKey !== key) {
+                        throw this.unsupported(name, 'Replacing a unique key is not fixture-backed.');
+                    }
+                    const stagedOwner = stagedKeys.get(`${name}\u0000${source}`);
+                    if (stagedOwner !== undefined && stagedOwner !== key) {
+                        throw this.unsupported(name, 'Replacing a key within one batch is not fixture-backed.');
+                    }
+                    const existing = claims.get(key);
+                    const batchOwner = stagedKeys.get(`${name}\u0001${key}`);
+                    if (existing && existing.source !== source || batchOwner && batchOwner !== source) {
+                        const details = { PropertyName: property, PropertyValue: raw };
+                        violations.push({ EventTypeId: type, SequenceNumber: BigInt(existing?.sequence ?? unavailable), ConstraintType: 1,
+                            ConstraintName: name,
+                            Message: `Event '${type}' on member '${property}' violated a unique constraint on sequence number ${existing?.sequence ?? unavailable}`,
+                            Details: details });
+                    } else {
+                        stagedKeys.set(`${name}\u0000${source}`, key);
+                        stagedKeys.set(`${name}\u0001${key}`, source);
+                    }
+                }
+                const uniqueType = definition.uniqueEventType;
+                if (uniqueType && (uniqueType.eventTypeIds ?? [uniqueType.eventTypeId]).includes(type)) {
+                    const first = history.find(prior => prior.context.eventSourceId === source &&
+                        (uniqueType.eventTypeIds ?? [uniqueType.eventTypeId]).includes(prior.eventType.id.value));
+                    const staged = stagedTypes.has(`${name}\u0000${source}`);
+                    if (first || staged) {
+                        violations.push({ EventTypeId: type, SequenceNumber: first?.context.sequenceNumber ?? BigInt(unavailable), ConstraintType: 2,
+                            ConstraintName: name,
+                            Message: `Event '${type}' violated a unique event type constraint on sequence number ${first?.context.sequenceNumber.toString() ?? unavailable}`,
+                            Details: {} });
+                    } else stagedTypes.add(`${name}\u0000${source}`);
+                }
+            }
+        }
+        return violations;
+    }
+
+    resolveMessage(violation: ConstraintViolation): ConstraintViolation {
+        return resolveConstraintMessage(this._definitions, violation);
+    }
+
+    private unsupported(name: string, reason: string): UnsupportedEventSequenceOperation {
+        return new UnsupportedEventSequenceOperation('artifacts.constraints', name, reason);
+    }
+}

package/testing/InProcessEventSequence.ts

@@ -6,6 +6,7 @@ import { EventObservationState } from '@cratis/chronicle.contracts';
 import { AppendOperationsBroadcaster } from '../eventSequences/AppendOperationsBroadcaster.js';
 import { prepareBatchAppend } from '../eventSequences/prepareBatchAppend.js';
 import { createAppendNotification, mapAppendNotificationCausation } from '../eventSequences/createAppendNotification.js';
+import { createAppendResult } from '../eventSequences/createAppendResult.js';
 import { Guid, type Constructor } from '@cratis/fundamentals';
 import { getEventTypeMetadata, getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
@@ -26,8 +27,8 @@ import type { ITransactionalEventSequence } from '../eventSequences/ITransaction
 import type { CompleteStreamResult } from '../eventSequences/CompleteStreamResult.js';
 import { prepareSingleAppend } from '../eventSequences/prepareSingleAppend.js';
 import { toContractsGuid } from '../connection/Guid.js';
-import { getUniqueEventMetadata, getUniquePropertyMetadata } from '../events/constraints/unique.js';
 import { getRemovedConstraintNames } from '../events/constraints/removeConstraint.js';
+import { InProcessConstraints, type WireConstraintViolation } from './InProcessConstraints.js';
 import type { EventScenarioOptions } from './EventScenarioOptions.js';
 import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
 
@@ -64,7 +65,7 @@ export class InProcessEventSequence implements IEventSequence {
     private readonly _results: AppendResult[] = [];
     readonly appendOperations = new AppendOperationsBroadcaster<AppendedEventWithResult[]>();
 
-    constructor(options: EventScenarioOptions, eventTypes: Constructor[]) {
+    constructor(options: EventScenarioOptions, eventTypes: Constructor[], private readonly _constraints?: InProcessConstraints) {
         if (options.eventSequenceId && options.eventSequenceId.value !== EventSequenceId.eventLog.value) {
             throw this.unsupported('options.eventSequenceId', options.eventSequenceId.value, 'Custom sequences are not fixture-backed.');
         }
@@ -93,9 +94,8 @@ export class InProcessEventSequence implements IEventSequence {
             if (eventType.generation.value !== 1 || eventType.tombstone) {
                 throw this.unsupported('artifacts.eventTypes', type.name, 'Only generation 1, non-tombstone events are proven.');
             }
-            if (options.constraints !== 'disabled' && (getUniqueEventMetadata(type) || getRemovedConstraintNames(type).length ||
-                [...metadata.members.keys()].some(key => getUniquePropertyMetadata(type, key)))) {
-                throw this.unsupported('artifacts.eventTypes.constraints', type.name, 'Constraint metadata is not supported in this increment.');
+            if (options.constraints !== 'disabled' && getRemovedConstraintNames(type).length) {
+                throw this.unsupported('artifacts.eventTypes.constraints', type.name, 'Constraint removal is not fixture-backed.');
             }
             if (getTagsFor(type).length) throw this.unsupported('artifacts.eventTypes.tags', type.name, 'Tagged events are not fixture-backed.');
             // Validate the complete schema, not only properties present on a particular event.
@@ -132,7 +132,8 @@ export class InProcessEventSequence implements IEventSequence {
                 try { pending = this.append(source, event); }
                 finally { this._allowSeedAppend = false; }
                 const result = await pending;
-                if (!result.isSuccess) throw new Error(`EventScenario given setup failed: ${JSON.stringify(result)}`);
+                if (!result.isSuccess) throw new Error(`EventScenario given setup failed: ${JSON.stringify(result, (_, value) =>
+                    typeof value === 'bigint' ? value.toString() : value)}`);
             }
             for (const [index, stored] of this._stagedSeeds.entries()) {
                 this._history.push(stored);
@@ -212,9 +213,12 @@ export class InProcessEventSequence implements IEventSequence {
                     tags: prepared.tags.map(tag => new Tag(tag))
                 }
             };
-            if (this._stagedSeeds) this._stagedSeeds.push(this.snapshot(stored));
-            else this._history.push(this.snapshot(stored));
-            const result = this.success(sequenceNumber, event.constructor.name);
+            const violations = this.validateConstraints([...this._history, ...(this._stagedSeeds ?? [])], [stored]);
+            const result = violations.length ? this.rejected(violations) : this.success(sequenceNumber, event.constructor.name);
+            if (result.isSuccess) {
+                if (this._stagedSeeds) this._stagedSeeds.push(this.snapshot(stored));
+                else this._history.push(this.snapshot(stored));
+            }
             if (!this._setup) this._results.push(result);
             if (this._stagedNotifications || this.appendOperations.hasSubscribers) {
                 const notification = [createAppendNotification(eventSourceId, event, result,
@@ -309,15 +313,16 @@ export class InProcessEventSequence implements IEventSequence {
                 } };
                 return { stored, result: this.success(sequenceNumber, event.constructor.name) };
             });
-            // Stage and validate every entry before committing any event or result.
-            this._history.push(...staged.map(item => this.snapshot(item.stored)));
-            const results = staged.map(item => item.result);
+            // The kernel validates the entire batch before persisting any events or allocating sequences.
+            const violations = this.validateConstraints(this._history, staged.map(item => item.stored));
+            const results = violations.length ? staged.map(() => this.rejected(violations)) : staged.map(item => item.result);
+            if (!violations.length) this._history.push(...staged.map(item => this.snapshot(item.stored)));
             this._results.push(...results);
             if (this.appendOperations.hasSubscribers) {
                 const occurredAt = new Date();
                 const causationEntries = mapAppendNotificationCausation(batchCausationChain);
-                this.appendOperations.publish(staged.map(({ result }, index) =>
-                    createAppendNotification(eventsForEventSourceIds[index].eventSourceId, eventsForEventSourceIds[index].event, result,
+                this.appendOperations.publish(staged.map((_, index) =>
+                    createAppendNotification(eventsForEventSourceIds[index].eventSourceId, eventsForEventSourceIds[index].event, results[index],
                         correlationId.toString(), causationEntries, eventsToAppend[index].Tags, occurredAt)));
             }
             return results;
@@ -441,6 +446,19 @@ export class InProcessEventSequence implements IEventSequence {
         return content;
     }
 
+    private validateConstraints(history: readonly AppendedEvent[], incoming: readonly AppendedEvent[]): WireConstraintViolation[] {
+        try { return this._constraints?.validate(history, incoming) ?? []; }
+        catch (error) {
+            if (error instanceof UnsupportedEventSequenceOperation) unsupportedObservers.get(this)?.(error);
+            throw error;
+        }
+    }
+
+    private rejected(violations: WireConstraintViolation[]): AppendResult {
+        return createAppendResult(18446744073709551615n, violations, [], undefined,
+            violation => this._constraints!.resolveMessage(violation), async () => ({ isSuccess: true, failedPartitions: [] }));
+    }
+
     private success(sequenceNumber: EventSequenceNumber, artifact: string): AppendResult {
         return Object.freeze({ sequenceNumber: Object.freeze(sequenceNumber), constraintViolations: Object.freeze([]),
             errors: Object.freeze([]), isSuccess: true,

package/testing/ReactorScenario.ts

@@ -178,7 +178,9 @@ export class ReactorScenario {
                 await this._events.given.forEventSource(sourceId).events(...input);
             } else {
                 const results = await this._events.when.forEventSource(sourceId).events(...input);
-                if (results.some(result => !result.isSuccess)) throw new Error('ReactorScenario action append failed.');
+                const failures = results.filter(result => !result.isSuccess);
+                if (failures.length) throw new Error(`ReactorScenario action append failed: ${JSON.stringify(failures, (_, value) =>
+                    typeof value === 'bigint' ? value.toString() : value)}`);
             }
             const events = this._events.appendedEvents.slice(before);
             if (events.length) await this.process(sourceId, events);