@cratis/chronicle 6.22.1 → 6.24.0

package/testing/InProcessConstraints.ts

@@ -0,0 +1,148 @@
+// 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';
+// Only the key characters captured by the packaged oracle, not every valid event-content character.
+const provenString = /^[A-Za-z0-9 .@_:\-|{}$\u00e9]*$/;
+
+function kernelKeyString(value: unknown, name: string): string {
+    if (typeof value === 'string' && provenString.test(value)) return value;
+    if (typeof value === 'boolean') return value ? 'True' : 'False';
+    throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
+        'Only fixture-backed scalar string and boolean keys are supported.');
+}
+
+function keyHash(value: string): string {
+    return createHash('sha256').update(value).digest('hex');
+}
+
+/** Narrow, fixture-backed unscoped constraint validation over serialized event snapshots. */
+export class InProcessConstraints {
+    private readonly _constrainedProperties = new Map<string, Set<string>>();
+
+    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.');
+                }
+                for (const entry of unique.eventDefinitions) {
+                    const properties = this._constrainedProperties.get(entry.eventTypeId) ?? new Set<string>();
+                    properties.add(entry.properties[0]);
+                    this._constrainedProperties.set(entry.eventTypeId, properties);
+                }
+            } 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);
+            }
+        }
+    }
+
+    isConstrainedProperty(eventTypeId: string, property: string): boolean {
+        return this._constrainedProperties.get(eventTypeId)?.has(property) ?? false;
+    }
+
+    /** 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 = kernelKeyString(event.content[property], name);
+                    const key = keyHash(raw);
+                    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' && typeof priorValue !== 'boolean') throw this.unsupported(name, 'History has an unproven key.');
+                            const priorHash = keyHash(kernelKeyString(priorValue, name));
+                            owners.set(prior.context.eventSourceId, priorHash);
+                            claims.set(priorHash, {
+                                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);
@@ -169,8 +170,10 @@ export class InProcessEventSequence implements IEventSequence {
             let content: Record<string, unknown>;
             try {
                 prepared = prepareSingleAppend(event, this._correlationId ? { correlationId: this._correlationId() } : undefined);
-                content = JSON.parse(prepared.content) as Record<string, unknown>;
+                content = this.checkedContent(event, prepared.content, 'append.content',
+                    'Content differs from the flat scalar schema; null, missing and extra values are not proven.');
             } catch (error) {
+                if (error instanceof UnsupportedEventSequenceOperation) throw error;
                 throw this.unsupported('append.serialization', event.constructor.name, `Payload or metadata could not be serialized: ${String(error)}.`);
             }
             try {
@@ -183,13 +186,6 @@ export class InProcessEventSequence implements IEventSequence {
                 Object.keys(prepared.causationChain[0].properties).length !== 0) {
                 throw this.unsupported('append.context', event.constructor.name, 'Ambient identity or causation metadata is not fixture-backed.');
             }
-            const properties = metadata.schema.properties!;
-            if (!content || typeof content !== 'object' || Array.isArray(content) ||
-                Object.keys(content).length !== Object.keys(properties).length ||
-                Object.entries(properties).some(([key, property]) => typeof content[key] !== property.type ||
-                    (property.type === 'string' && !/^[\x20-\x21\x23-\x5b\x5d-\x7e\u00e9]*$/.test(content[key] as string)))) {
-                throw this.unsupported('append.content', event.constructor.name, 'Content differs from the flat scalar schema; null, missing and extra values are not proven.');
-            }
             const occurred = this._clock();
             // Date has millisecond precision; only the UTC year range representable by DateTimeOffset is supported.
             if (!(occurred instanceof Date) || Number.isNaN(occurred.getTime()) ||
@@ -212,9 +208,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 +308,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;
@@ -427,20 +427,37 @@ export class InProcessEventSequence implements IEventSequence {
         }
     }
 
-    private checkedContent(event: object, serialized: string, operation: string): Record<string, unknown> {
+    private checkedContent(event: object, serialized: string, operation: string,
+        mismatchReason = 'Content differs from the fixture-backed scalar schema.'): Record<string, unknown> {
         let content: Record<string, unknown>;
         try { content = JSON.parse(serialized) as Record<string, unknown>; }
         catch { throw this.unsupported(operation, event.constructor.name, 'Content must be valid JSON.'); }
-        const properties = this._catalog.get(event.constructor)!.schema.properties!;
+        const metadata = this._catalog.get(event.constructor)!;
+        const properties = metadata.schema.properties!;
         if (!content || typeof content !== 'object' || Array.isArray(content) ||
             Object.keys(content).length !== Object.keys(properties).length ||
             Object.entries(properties).some(([key, property]) => typeof content[key] !== property.type ||
+                (this._constraints?.isConstrainedProperty(metadata.eventType.id.value, key) &&
+                    (typeof Reflect.get(event, key) !== property.type || Reflect.get(event, key) !== content[key])) ||
                 (property.type === 'string' && !/^[\x20-\x21\x23-\x5b\x5d-\x7e\u00e9]*$/.test(content[key] as string)))) {
-            throw this.unsupported(operation, event.constructor.name, 'Content differs from the fixture-backed scalar schema.');
+            throw this.unsupported(operation, event.constructor.name, mismatchReason);
         }
         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);