@cratis/chronicle 6.31.3 → 6.32.0

package/testing/for_EventScenario/when_appending_concept_fields/concept_scenario_behaviors.fixture.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, type Constructor } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi, type Assertion } from 'vitest';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { EventSequence } from '../../../eventSequences/EventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import type { AppendResult } from '../../../eventSequences/AppendResult.js';
+import type { IUnitOfWorkManager } from '../../../transactions/IUnitOfWorkManager.js';
+import { EventScenario, ReactorScenario, ReadModelScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+
+chai.should();
+
+// Keep fluent should assertions typed without adding global Object declarations.
+function should(value: unknown): Assertion {
+    return (value as { should: Assertion }).should;
+}
+
+class InvalidKey extends ConceptAs<unknown> {}
+
+export function conceptScenarioBehaviors(fixtures: {
+    eventTypes: Constructor[];
+    constraints: Constructor[];
+    registered: (name: string) => object;
+    flag: (value: boolean) => object;
+    composite: (first: string, last: string) => object;
+    model: Constructor<{ id: string; name: string }>;
+    reactor: Constructor;
+}): void {
+    const artifacts = { eventTypes: fixtures.eventTypes, constraints: fixtures.constraints, reducers: [], projections: [] };
+    let scenario: EventScenario;
+    beforeEach(() => { scenario = new EventScenario({ artifacts }); });
+
+    describe('when appending a concept-valued unique property', () => {
+        let result: AppendResult;
+        let connectedContent: string;
+        beforeEach(async () => {
+            const append = vi.fn().mockResolvedValue({ Response: { SequenceNumber: 0n, ConstraintViolations: [], Errors: [] } });
+            const connected = new EventSequence(EventSequenceId.eventLog, 'store', 'Default',
+                { eventSequences: { append } } as unknown as ChronicleConnection, {} as IUnitOfWorkManager);
+            const event = fixtures.registered('Ada');
+            await connected.append('author-1', event);
+            connectedContent = append.mock.calls[0][0].Content as string;
+            result = await scenario.append('author-1', event);
+        });
+        it('should accept the same event as the connected client', () => { should(result.isSuccess).be.true; });
+        it('should store the same primitive content as the connected client', () => {
+            should(scenario.appendedEvents[0].content).deep.equal(JSON.parse(connectedContent));
+            should(scenario.appendedEvents[0].content).deep.equal({ name: 'Ada' });
+        });
+    });
+
+    describe('when appending an empty string concept key', () => {
+        let result: AppendResult;
+        beforeEach(async () => { result = await scenario.append('author-1', fixtures.registered('')); });
+        it('should preserve the empty primitive value', () => {
+            should(result.isSuccess).be.true;
+            should(scenario.appendedEvents[0].content).deep.equal({ name: '' });
+        });
+    });
+
+    for (const value of [new InvalidKey(42), new InvalidKey('É'), new Date('2025-01-02T00:00:00.000Z')]) {
+        describe(`when a constrained string field contains an unsupported ${value.constructor.name} value`, () => {
+            let error: unknown;
+            beforeEach(async () => {
+                const event = fixtures.registered('Ada');
+                Object.assign(event, { name: value });
+                error = await scenario.append('author-1', event).then(() => undefined, reason => reason);
+            });
+            it('should reject before changing scenario state', () => {
+                should(error instanceof UnsupportedEventSequenceOperation).be.true;
+                should(scenario.appendedEvents).have.lengthOf(0);
+                should(scenario.results).have.lengthOf(0);
+            });
+        });
+    }
+
+    describe('when claiming a seeded concept key from another source', () => {
+        let result: AppendResult;
+        beforeEach(async () => {
+            await scenario.given.forEventSource('author-1').events(fixtures.registered('Ada'));
+            result = await scenario.append('author-2', fixtures.registered('Ada'));
+        });
+        it('should reject the duplicate primitive key', () => {
+            should(result.isSuccess).be.false;
+            should(result.constraintViolations[0].details).deep.equal({ PropertyName: 'name', PropertyValue: 'Ada' });
+        });
+        it('should preserve the seeded history', () => { should(scenario.appendedEvents).have.lengthOf(1); });
+    });
+
+    for (const mixed of [false, true]) {
+        describe(`when appending concept fields in a ${mixed ? 'mixed-source' : 'single-source'} batch`, () => {
+            let results: AppendResult[];
+            beforeEach(async () => {
+                const events = [fixtures.registered('Ada'), fixtures.registered('Grace')];
+                results = mixed
+                    ? await scenario.appendMany(events.map((event, index) => ({ eventSourceId: `author-${index}`, event })))
+                    : await scenario.appendMany('author-1', events);
+            });
+            it('should accept both serialized concept values', () => {
+                should(results.map(result => result.isSuccess)).deep.equal([true, true]);
+                should(scenario.appendedEvents.map(event => event.content)).deep.equal([{ name: 'Ada' }, { name: 'Grace' }]);
+            });
+        });
+    }
+
+    describe('when a batch claims the same concept key twice', () => {
+        let results: AppendResult[];
+        beforeEach(async () => {
+            results = await scenario.appendMany([
+                { eventSourceId: 'author-1', event: fixtures.registered('Ada') },
+                { eventSourceId: 'author-2', event: fixtures.registered('Ada') }
+            ]);
+        });
+        it('should reject the entire batch without committing events', () => {
+            should(results.map(result => result.isSuccess)).deep.equal([false, false]);
+            should(scenario.appendedEvents).have.lengthOf(0);
+        });
+    });
+
+    for (const value of [false, true]) {
+        describe(`when claiming the boolean concept key ${value} twice`, () => {
+            let accepted: AppendResult;
+            let duplicate: AppendResult;
+            beforeEach(async () => {
+                accepted = await scenario.append('flag-1', fixtures.flag(value));
+                duplicate = await scenario.append('flag-2', fixtures.flag(value));
+            });
+            it('should accept and serialize the boolean concept', () => {
+                should(accepted.isSuccess).be.true;
+                should(scenario.appendedEvents[0].content).deep.equal({ active: value });
+            });
+            it('should report the duplicate boolean key', () => {
+                should(duplicate.isSuccess).be.false;
+                should(duplicate.constraintViolations[0].details).deep.equal({ PropertyName: 'active', PropertyValue: value ? 'True' : 'False' });
+            });
+        });
+    }
+
+    describe('when a composite concept key differs only in casing', () => {
+        let duplicate: AppendResult;
+        beforeEach(async () => {
+            await scenario.append('name-1', fixtures.composite('Ada', 'Lovelace'));
+            duplicate = await scenario.append('name-2', fixtures.composite('ADA', 'LOVELACE'));
+        });
+        it('should compare serialized components and retain original values in violations', () => {
+            should(duplicate.isSuccess).be.false;
+            should(duplicate.constraintViolations.map(violation => violation.details.PropertyValue)).deep.equal(['ADA', 'LOVELACE']);
+        });
+    });
+
+    describe('when observing accepted concept fields in a read model', () => {
+        let name: string;
+        beforeEach(async () => {
+            const models = new ReadModelScenario(fixtures.model, artifacts).observe(scenario);
+            await scenario.append('author-1', fixtures.registered('Ada'));
+            name = (await models.instanceForEventSourceId('author-1'))!.name;
+        });
+        it('should project the serialized primitive', () => { should(name).equal('Ada'); });
+    });
+
+    describe('when delivering concept fields through a reactor and observing its explicit append', () => {
+        let reactorScenario: ReactorScenario;
+        let name: string;
+        beforeEach(async () => {
+            reactorScenario = new ReactorScenario(fixtures.reactor, { artifacts });
+            const models = new ReadModelScenario(fixtures.model, artifacts).observe(reactorScenario);
+            await reactorScenario.when.forEventSource('author-1').events(fixtures.registered('Ada'));
+            name = (await models.instanceForEventSourceId('author-1'))!.name;
+        });
+        it('should complete the delivery and explicit concept append', () => {
+            should(reactorScenario.results[0].completed).be.true;
+            should(reactorScenario.appendedEvents.map(event => event.content)).deep.equal([{ name: 'Ada' }, { name: 'Ada' }]);
+        });
+        it('should expose the serialized primitive to the observing read model', () => { should(name).equal('Ada'); });
+    });
+}

package/testing/for_EventScenario/when_appending_concept_fields/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { unique } from '../../../events/constraints/unique.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { reactor } from '../../../reactors/reactor.js';
+import type { ReactorServices } from '../../../reactors/ReactorServices.js';
+import { conceptScenarioBehaviors } from './concept_scenario_behaviors.fixture.js';
+
+class AuthorName extends ConceptAs<string> { static readonly valueType = String; }
+class Active extends ConceptAs<boolean> { static readonly valueType = Boolean; }
+
+@eventType('concept-legacy-registered')
+class AuthorRegistered {
+    @field(AuthorName) @unique('concept-legacy-name') name: AuthorName;
+    constructor(name: string) { this.name = new AuthorName(name); }
+}
+
+@eventType('concept-legacy-flag')
+class FlagRecorded {
+    @field(Active) @unique('concept-legacy-active') active: Active;
+    constructor(active: boolean) { this.active = new Active(active); }
+}
+
+@eventType('concept-legacy-composite')
+class FullNameRegistered {
+    @field(AuthorName) first: AuthorName;
+    @field(AuthorName) last: AuthorName;
+    constructor(first: string, last: string) { this.first = new AuthorName(first); this.last = new AuthorName(last); }
+}
+
+@constraint('concept-legacy-full-name')
+class FullName {
+    define(builder: IConstraintBuilder) {
+        builder.unique(key => key.on(FullNameRegistered, event => event.first, event => event.last).ignoreCasing());
+    }
+}
+
+@eventType('concept-legacy-welcomed')
+class AuthorWelcomed {
+    @field(AuthorName) @unique('concept-legacy-welcome') name: AuthorName;
+    constructor(name: string) { this.name = new AuthorName(name); }
+}
+
+@fromEvent(AuthorWelcomed)
+@fromEvent(AuthorRegistered)
+class Author {
+    @field(String) id = '';
+    @field(String) name = '';
+}
+
+@reactor('concept-legacy-welcomer')
+class Welcomer {
+    async authorRegistered(event: AuthorRegistered, context: { eventSourceId: string }, services: ReactorServices) {
+        await services.eventStore.eventLog.append(context.eventSourceId, new AuthorWelcomed(String(event.name)));
+    }
+}
+
+describe('when appending concept fields with legacy decorators', () => {
+    conceptScenarioBehaviors({
+        eventTypes: [AuthorRegistered, FlagRecorded, FullNameRegistered, AuthorWelcomed],
+        constraints: [FullName],
+        registered: name => new AuthorRegistered(name),
+        flag: value => new FlagRecorded(value),
+        composite: (first, last) => new FullNameRegistered(first, last),
+        model: Author,
+        reactor: Welcomer
+    });
+});

package/testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConceptAs, field } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { unique } from '../../../events/constraints/unique.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { fromEvent } from '../../../projections/modelBound/fromEvent.js';
+import { reactor } from '../../../reactors/reactor.js';
+import type { ReactorServices } from '../../../reactors/ReactorServices.js';
+import { conceptScenarioBehaviors } from './concept_scenario_behaviors.fixture.js';
+
+class AuthorName extends ConceptAs<string> { static readonly valueType = String; }
+class Active extends ConceptAs<boolean> { static readonly valueType = Boolean; }
+
+@eventType('concept-standard-registered')
+class AuthorRegistered {
+    @field(AuthorName) @unique('concept-standard-name') name: AuthorName;
+    constructor(name: string) { this.name = new AuthorName(name); }
+}
+
+@eventType('concept-standard-flag')
+class FlagRecorded {
+    @field(Active) @unique('concept-standard-active') active: Active;
+    constructor(active: boolean) { this.active = new Active(active); }
+}
+
+@eventType('concept-standard-composite')
+class FullNameRegistered {
+    @field(AuthorName) first: AuthorName;
+    @field(AuthorName) last: AuthorName;
+    constructor(first: string, last: string) { this.first = new AuthorName(first); this.last = new AuthorName(last); }
+}
+
+@constraint('concept-standard-full-name')
+class FullName {
+    define(builder: IConstraintBuilder) {
+        builder.unique(key => key.on(FullNameRegistered, event => event.first, event => event.last).ignoreCasing());
+    }
+}
+
+@eventType('concept-standard-welcomed')
+class AuthorWelcomed {
+    @field(AuthorName) @unique('concept-standard-welcome') name: AuthorName;
+    constructor(name: string) { this.name = new AuthorName(name); }
+}
+
+@fromEvent(AuthorWelcomed)
+@fromEvent(AuthorRegistered)
+class Author {
+    @field(String) id = '';
+    @field(String) name = '';
+}
+
+@reactor('concept-standard-welcomer')
+class Welcomer {
+    async authorRegistered(event: AuthorRegistered, context: { eventSourceId: string }, services: ReactorServices) {
+        await services.eventStore.eventLog.append(context.eventSourceId, new AuthorWelcomed(String(event.name)));
+    }
+}
+
+describe('when appending concept fields with standard decorators', () => {
+    conceptScenarioBehaviors({
+        eventTypes: [AuthorRegistered, FlagRecorded, FullNameRegistered, AuthorWelcomed],
+        constraints: [FullName],
+        registered: name => new AuthorRegistered(name),
+        flag: value => new FlagRecorded(value),
+        composite: (first, last) => new FullNameRegistered(first, last),
+        model: Author,
+        reactor: Welcomer
+    });
+});

package/testing/for_EventScenario/when_appending_scoped_constraints/scope_scenario_behaviors.fixture.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { chai, describe, it, vi, type Assertion } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import { getEventTypeMetadata } from '../../../events/eventTypeDecorator.js';
+import type { ConstraintScopeCapture } from '../../../events/constraints/ConstraintBuilder.js';
+import { compileConstraints } from '../../../events/constraints/Constraints.js';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import type { AppendedEventWithResult } from '../../../eventSequences/AppendedEventWithResult.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+import { InProcessConstraints } from '../../InProcessConstraints.js';
+
+chai.should();
+function should(value: unknown): Assertion { return (value as { should: Assertion }).should; }
+
+type Entry = { source: string; type: string; value: string; sourceType?: string; streamType?: string; streamId?: string };
+type Definition = { kind: string; name: string; scope: ConstraintScopeCapture; events?: Array<{ type: string; properties: string[] }>;
+    eventTypes?: string[]; ignoreCasing?: boolean; removedWithEventTypeIds: string[]; message: string };
+type History = { sequence: string; source: string; sourceType?: string; streamType?: string; streamId?: string;
+    type: string; content: Record<string, unknown>; hash?: string };
+type Outcome = { success: boolean; sequences: string[]; errors: string[];
+    wireViolations: Array<{ EventTypeId: string; SequenceNumber: string; ConstraintType: number; ConstraintName: string; Message: string; Details: Record<string, string> }>;
+    violations: Array<{ id: string; message: string; details: Record<string, string> }>; history: History[]; next: string };
+type ScopeCase = { name: string; kind: string; eventSchemas: Record<string, { eventTypeId: string; properties: Record<string, string> }>;
+    constraintDefinitions: Definition[];
+    isolatedConstraintOperations: Array<{ label: string; mode: string; overload?: string; options?: AppendOptions; events: Entry[] }> };
+type Fixture = { scopeCases: ScopeCase[]; expected: { cases: Array<{ name: string; result: { outcomes: Outcome[] } }> } };
+
+export function scopeScenarioBehaviors(
+    types: Record<string, new (value: string) => object>,
+    constraints: (scope: ConstraintScopeCapture, kind: string) => Constructor[]
+): void {
+    const fixture = JSON.parse(readFileSync(new URL('../../fixtures/constraints-scopes.json', import.meta.url), 'utf8')) as Fixture;
+    const historyOf = (scenario: EventScenario): History[] => scenario.appendedEvents.map(event => ({
+        sequence: event.context.sequenceNumber.toString(), source: event.context.eventSourceId,
+        sourceType: event.context.eventSourceType, streamType: event.context.eventStreamType, streamId: event.context.eventStreamId,
+        type: event.eventType.id.value, content: event.content, hash: event.context.hash
+    }));
+    const aliases = Object.fromEntries(Object.entries(types).map(([alias, type]) => [getEventTypeMetadata(type)!.eventType.id.value, alias]));
+
+    it('should retain all seven scope combinations for both constraint kinds and the alias guards', () => {
+        should(fixture.scopeCases.map(test => test.name)).deep.equal([
+            ...Array.from({ length: 7 }, (_, index) => ['property', 'cycle', 'once'].map(kind => `${kind}-${index + 1}`)).flat(),
+            'property-delimiter-alias', 'cycle-delimiter-alias'
+        ]);
+        should(fixture.expected.cases.map(test => test.name)).deep.equal(fixture.scopeCases.map(test => test.name));
+    });
+
+    for (const [caseIndex, test] of fixture.scopeCases.entries()) {
+        describe(`with ${test.name}`, () => {
+            it(test.kind === 'oracleGuard' ? 'should reject delimiter routes before mutation' :
+                'should match kernel violations, routes, hashes, atomic history and notifications', async () => {
+                const definition = test.constraintDefinitions[0];
+                const selected = Object.keys(test.eventSchemas).map(alias => types[alias]);
+                const selectedConstraints = constraints(definition.scope, test.name.split('-')[0]);
+                const compiled = compileConstraints({ eventTypes: selected, constraints: selectedConstraints });
+                should(Object.fromEntries(Object.entries(test.eventSchemas).map(([alias]) => {
+                    const metadata = getEventTypeMetadata(types[alias])!;
+                    return [alias, { eventTypeId: metadata.eventType.id.value,
+                        properties: Object.fromEntries(Object.entries(metadata.schema.properties!).map(([key, property]) => [key, property.type])) }];
+                }))).deep.equal(test.eventSchemas);
+                should([...compiled].map(([name, capture]) => ({
+                    kind: capture.uniqueConstraint ? 'uniqueProperty' : 'uniqueEventType', name,
+                    ...(capture.uniqueConstraint ? {
+                        events: capture.uniqueConstraint.eventDefinitions.map(entry => ({ type: aliases[entry.eventTypeId], properties: entry.properties })),
+                        ignoreCasing: capture.uniqueConstraint.ignoreCasing
+                    } : { eventTypes: (capture.uniqueEventType!.eventTypeIds ?? [capture.uniqueEventType!.eventTypeId]).map(id => aliases[id]) }),
+                    removedWithEventTypeIds: (capture.uniqueConstraint?.removedWithEventTypeIds ?? capture.uniqueEventType?.removedWithEventTypeIds ?? []).map(id => aliases[id]),
+                    message: capture.uniqueConstraint?.message ?? capture.uniqueEventType?.message ?? '', scope: capture.scope
+                }))).deep.equal(test.constraintDefinitions);
+                const scenario = new EventScenario({ artifacts: { eventTypes: selected, constraints: selectedConstraints } });
+                const notifications = scenario.eventLog.appendOperations[Symbol.asyncIterator]();
+                if (test.kind === 'oracleGuard') {
+                    const pending = notifications.next();
+                    try {
+                        for (const operation of test.isolatedConstraintOperations) {
+                            const entry = operation.events[0];
+                            await scenario.append(entry.source, new types[entry.type](entry.value), operation.options)
+                                .then(() => { throw new Error('Unsupported route succeeded'); }, error => {
+                                    should(error instanceof UnsupportedEventSequenceOperation).be.true;
+                                    should((error as Error).message).include('Only simple routing identifiers');
+                                    should((error as Error).message).include('Use a kernel-backed test.');
+                                });
+                            should(scenario.appendedEvents.length).equal(0);
+                            should(scenario.results.length).equal(0);
+                            should((await scenario.eventLog.getNextSequenceNumber()).value).equal(0n);
+                        }
+                        const accepted = await scenario.append('Safe', new types[test.isolatedConstraintOperations[0].events[0].type]('Safe'));
+                        should(accepted.isSuccess).be.true;
+                        should(((await pending).value as AppendedEventWithResult[])[0].result).equal(accepted);
+                    } finally { await notifications.return?.(); }
+                    return;
+                }
+                const validate = vi.spyOn(InProcessConstraints.prototype, 'validate');
+                const expected = fixture.expected.cases[caseIndex].result.outcomes;
+                should(expected.length).equal(test.isolatedConstraintOperations.length);
+                let resultCount = 0;
+                try {
+                    for (const [index, operation] of test.isolatedConstraintOperations.entries()) {
+                        const before = historyOf(scenario);
+                        const nextNotification = notifications.next();
+                        const entries = operation.events.map(entry => ({ eventSourceId: entry.source, event: new types[entry.type](entry.value),
+                            eventSourceType: entry.sourceType, eventStreamType: entry.streamType, eventStreamId: entry.streamId }));
+                        const results = operation.mode === 'single'
+                            ? [await scenario.append(entries[0].eventSourceId, entries[0].event, operation.options)]
+                            : operation.overload === 'source'
+                                ? await scenario.appendMany(entries[0].eventSourceId, entries.map(entry => entry.event), operation.options)
+                                : await scenario.appendMany(entries, operation.options);
+                        const outcome = expected[index];
+                        const raw = validate.mock.results.at(-1)!.value as ReturnType<InProcessConstraints['validate']>;
+                        should(raw.map(({ SequenceNumber, ...violation }) => ({ ...violation, SequenceNumber: SequenceNumber.toString() })))
+                            .deep.equal(outcome.wireViolations, operation.label);
+                        should(results.length).equal(operation.events.length);
+                        for (const [position, result] of results.entries()) {
+                            should(result.isSuccess).equal(outcome.success, operation.label);
+                            should(result.sequenceNumber.value.toString()).equal(outcome.success ? outcome.sequences[position] : '0');
+                            should(result.constraintViolations.map(violation => ({ id: violation.constraintId, message: violation.message, details: violation.details })))
+                                .deep.equal(outcome.violations, operation.label);
+                            should(result.errors.map(error => error.message)).deep.equal(outcome.errors);
+                        }
+                        const notification = (await nextNotification).value as AppendedEventWithResult[];
+                        should(notification.length).equal(results.length);
+                        notification.forEach((entry, position) => should(entry.result).equal(results[position]));
+                        resultCount += results.length;
+                        should(scenario.results.length).equal(resultCount);
+                        if (!outcome.success) should(historyOf(scenario)).deep.equal(before, operation.label);
+                        should(historyOf(scenario)).deep.equal(outcome.history, operation.label);
+                        should((await scenario.eventLog.getNextSequenceNumber()).value.toString()).equal(outcome.next);
+                    }
+                } finally {
+                    validate.mockRestore();
+                    await notifications.return?.();
+                }
+            });
+        });
+    }
+}

package/testing/for_EventScenario/when_appending_scoped_constraints/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,57 @@
+// 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 { field, type Constructor } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import { removeConstraint } from '../../../events/constraints/removeConstraint.js';
+import type { ConstraintScopeCapture } from '../../../events/constraints/ConstraintBuilder.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { scopeScenarioBehaviors } from './scope_scenario_behaviors.fixture.js';
+
+@eventType('OracleDomainText')
+class Text { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainShared')
+class Shared { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainRemoved')
+class Removed { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleDomainExpired')
+class Expired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleFirst')
+class First { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleSibling')
+class Sibling { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleRemoved')
+@removeConstraint('OracleScopedCycle')
+class CycleRemoved { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleExpired')
+@removeConstraint('OracleScopedCycle')
+class CycleExpired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+
+function constraints(scope: ConstraintScopeCapture, kind: string): Constructor[] {
+    function apply(builder: IConstraintBuilder): IConstraintBuilder {
+        if (scope.perEventSourceType) builder.perEventSourceType();
+        if (scope.perEventStreamType) builder.perEventStreamType();
+        if (scope.perEventStreamId) builder.perEventStreamId();
+        return builder;
+    }
+    @constraint('OracleScopedKey')
+    class Key {
+        define(builder: IConstraintBuilder) {
+            apply(builder).unique(key => key.on(Text, event => event.key).on(Shared, event => event.key)
+                .removedWith(Removed).removedWith(Expired).withMessage('Taken: {PropertyValue}'));
+        }
+    }
+    @constraint('OracleScopedFirst')
+    class FirstCycle { define(builder: IConstraintBuilder) { apply(builder).uniqueFor(First, 'Cycle occupied', 'OracleScopedCycle'); } }
+    @constraint('OracleScopedSibling')
+    class SiblingCycle { define(builder: IConstraintBuilder) { apply(builder).uniqueFor(Sibling, 'Cycle occupied', 'OracleScopedCycle'); } }
+    return kind === 'property' ? [Key] : kind === 'once' ? [FirstCycle] : [FirstCycle, SiblingCycle];
+}
+
+describe('when appending scoped constraints with legacy decorators', () => {
+    scopeScenarioBehaviors({ string: Text, shared: Shared, removed: Removed, expired: Expired,
+        first: First, sibling: Sibling, cycleRemoved: CycleRemoved, cycleExpired: CycleExpired }, constraints);
+});

package/testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field, type Constructor } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import { removeConstraint } from '../../../events/constraints/removeConstraint.js';
+import type { ConstraintScopeCapture } from '../../../events/constraints/ConstraintBuilder.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { scopeScenarioBehaviors } from './scope_scenario_behaviors.fixture.js';
+
+@eventType('OracleDomainText')
+class Text { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainShared')
+class Shared { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainRemoved')
+class Removed { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleDomainExpired')
+class Expired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleFirst')
+class First { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleSibling')
+class Sibling { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleRemoved')
+@removeConstraint('OracleScopedCycle')
+class CycleRemoved { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleExpired')
+@removeConstraint('OracleScopedCycle')
+class CycleExpired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+
+function constraints(scope: ConstraintScopeCapture, kind: string): Constructor[] {
+    function apply(builder: IConstraintBuilder): IConstraintBuilder {
+        if (scope.perEventSourceType) builder.perEventSourceType();
+        if (scope.perEventStreamType) builder.perEventStreamType();
+        if (scope.perEventStreamId) builder.perEventStreamId();
+        return builder;
+    }
+    @constraint('OracleScopedKey')
+    class Key {
+        define(builder: IConstraintBuilder) {
+            apply(builder).unique(key => key.on(Text, event => event.key).on(Shared, event => event.key)
+                .removedWith(Removed).removedWith(Expired).withMessage('Taken: {PropertyValue}'));
+        }
+    }
+    @constraint('OracleScopedFirst')
+    class FirstCycle { define(builder: IConstraintBuilder) { apply(builder).uniqueFor(First, 'Cycle occupied', 'OracleScopedCycle'); } }
+    @constraint('OracleScopedSibling')
+    class SiblingCycle { define(builder: IConstraintBuilder) { apply(builder).uniqueFor(Sibling, 'Cycle occupied', 'OracleScopedCycle'); } }
+    return kind === 'property' ? [Key] : kind === 'once' ? [FirstCycle] : [FirstCycle, SiblingCycle];
+}
+
+describe('when appending scoped constraints with standard decorators', () => {
+    scopeScenarioBehaviors({ string: Text, shared: Shared, removed: Removed, expired: Expired,
+        first: First, sibling: Sibling, cycleRemoved: CycleRemoved, cycleExpired: CycleExpired }, constraints);
+});

package/testing/for_EventScenario/when_appending_scoped_constraints/with_unproven_cycles.spec.ts

@@ -0,0 +1,48 @@
+// 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 { field } from '@cratis/fundamentals';
+import { chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import { removeConstraint } from '../../../events/constraints/removeConstraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+
+chai.should();
+@eventType('UnprovenScopedFirst')
+class First { @field(String) label = 'First'; }
+@eventType('UnprovenScopedSecond')
+class Second { @field(String) label = 'Second'; }
+@eventType('UnprovenScopedRenewed')
+@removeConstraint('UnprovenScopedCycle')
+class Renewed { @field(String) label = 'Renewed'; }
+@eventType('UnprovenScopedRemoved')
+@removeConstraint('UnprovenScopedCycle')
+class Removed { @field(String) label = 'Removed'; }
+@eventType('UnprovenScopedExpired')
+@removeConstraint('UnprovenScopedCycle')
+class Expired { @field(String) label = 'Expired'; }
+
+function constraints(scoped: boolean): Function[] {
+    return [First, Second, Renewed].map((type, index) => {
+        @constraint(`UnprovenScopedDeclaration${index}`)
+        class Cycle {
+            define(builder: IConstraintBuilder) {
+                if (scoped) builder.perEventStreamId();
+                builder.uniqueFor(type, 'Occupied', 'UnprovenScopedCycle');
+            }
+        }
+        return Cycle;
+    });
+}
+
+describe('when configuring a scoped covered-and-removal cycle', () => {
+    it('should reject that scoped interaction specifically while preserving its unscoped support', () => {
+        const eventTypes = [First, Second, Renewed, Removed, Expired];
+        new EventScenario({ artifacts: { eventTypes, constraints: constraints(false) } }).should.be.instanceOf(EventScenario);
+        (() => new EventScenario({ artifacts: { eventTypes, constraints: constraints(true) } }))
+            .should.throw(UnsupportedEventSequenceOperation, 'Scoped covered-and-removal event cycles are not fixture-backed.');
+    });
+});