@cratis/chronicle 6.31.4 → 6.32.0

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

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

@@ -0,0 +1,119 @@
+// 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 { unique } from '../../../events/constraints/unique.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+
+chai.should();
+@eventType('ScopedGuardClaim')
+class Claim { @field(String) key: string; @field(String) other = 'Other'; constructor(key: string) { this.key = key; } }
+@eventType('ScopedGuardFlag')
+class Flag { @field(Boolean) key = true; }
+@eventType('ScopedGuardRemoval')
+class Removed { @field(String) label = 'release'; }
+@eventType('ScopedGuardFieldless')
+class Fieldless {}
+
+function definition(configure: (builder: IConstraintBuilder) => void, name = 'ScopedGuard'): Function {
+    @constraint(name)
+    class Definition { define(builder: IConstraintBuilder) { configure(builder); } }
+    return Definition;
+}
+const scopedConstraint = definition(builder => builder.perEventStreamId().unique(value => value.on(Claim, event => event.key).removedWith(Removed)));
+const create = () => new EventScenario({ artifacts: { eventTypes: [Claim, Removed], constraints: [scopedConstraint] } });
+async function unsupported(action: () => unknown, reason: string): Promise<void> {
+    await Promise.resolve().then(action).then(() => { throw new Error('Unsupported operation succeeded'); }, error => {
+        (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+        (error as Error).message.should.include(reason);
+        (error as Error).message.should.include('Use a kernel-backed test.');
+    });
+}
+
+describe('when configuring unproven scoped property shapes', () => {
+    for (const [name, configure, reason] of [
+        ['composite', (builder: IConstraintBuilder) => builder.unique(value => value.on(Claim, event => event.key, event => event.other)), 'Scoped composite or case-insensitive property keys'],
+        ['casing', (builder: IConstraintBuilder) => builder.unique(value => value.on(Claim, event => event.key).ignoreCasing()), 'Scoped composite or case-insensitive property keys'],
+        ['boolean', (builder: IConstraintBuilder) => builder.unique(value => value.on(Flag, event => event.key)), 'Scoped property keys must be schema-backed strings'],
+        ['covered removal', (builder: IConstraintBuilder) => builder.unique(value => value.on(Claim, event => event.key).removedWith(Claim)), 'Scoped covered-and-removal property events'],
+        ['fieldless removal', (builder: IConstraintBuilder) => builder.unique(value => value.on(Claim, event => event.key).removedWith(Fieldless)), 'Scoped fieldless removal events']
+    ] as const) {
+        it(`should reject ${name} with its specific boundary rather than a compiler failure`, async () => {
+            const eventTypes = name === 'fieldless removal' ? [Claim, Fieldless] : [Claim, Flag, Removed];
+            new EventScenario({ artifacts: { eventTypes, constraints: [definition(configure)] } }).should.be.instanceOf(EventScenario);
+            await unsupported(() => new EventScenario({ artifacts: { eventTypes,
+                constraints: [definition(builder => { builder.perEventSourceType(); configure(builder); })] } }), reason);
+        });
+    }
+
+    it('should reject a scoped definition alongside another nonoverlapping definition', async () => {
+        const other = definition(builder => builder.unique(value => value.on(Flag, event => event.key)), 'OtherGuard');
+        await unsupported(() => new EventScenario({ artifacts: { eventTypes: [Claim, Flag, Removed], constraints: [scopedConstraint, other] } }),
+            'Scoped constraints alongside other definitions');
+    });
+
+    it('should retain the production compiler conflict between scoped fluent and unscoped unique decorators', async () => {
+        @eventType('ScopedDecoratedConflict')
+        class Decorated { @field(String) @unique('Conflict') key = 'key'; }
+        const scoped = definition(builder => builder.perEventStreamId().unique(value => value.on(Decorated, event => event.key)), 'Conflict');
+        await unsupported(() => new EventScenario({ artifacts: { eventTypes: [Decorated], constraints: [scoped] } }),
+            "Conflicting scopes for constraint 'Conflict'");
+    });
+});
+
+describe('when a scoped append uses unsupported routes or metadata', () => {
+    it('should preserve claims, history, results, notifications and sequence after unsupported input', async () => {
+        const scenario = create();
+        (await scenario.append('A', new Claim('Alpha'), { streamId: 'West' })).isSuccess.should.be.true;
+        const before = scenario.appendedEvents;
+        const results = scenario.results;
+        const notifications = scenario.eventLog.appendOperations[Symbol.asyncIterator]();
+        const pending = notifications.next();
+        try {
+            for (const dimension of ['sourceType', 'streamType', 'streamId'] as const) {
+                for (const value of [' ', 'a|estt:b', '*', 'a:b', 'é', 'a\u0000b']) {
+                    const options = { [dimension]: value };
+                    await unsupported(() => scenario.append('B', new Claim('Beta'), options), `append.${dimension}`);
+                    await unsupported(() => scenario.appendMany('B', [new Claim('Beta')], options), `appendMany.${dimension}`);
+                }
+            }
+            for (const options of [{ tags: [] }, { subject: '' }, { occurred: new Date() }, { correlationId: '00000000-0000-0000-0000-000000000001' },
+                { concurrencyScopes: {} }, { eventSourceId: 'other' }, { arbitrary: true }]) {
+                await unsupported(() => scenario.append('B', new Claim('Beta'), options as AppendOptions), 'append.options');
+            }
+            await unsupported(() => scenario.appendMany([
+                { eventSourceId: 'A', event: new Removed(), eventStreamId: 'West' },
+                { eventSourceId: 'B', event: new Claim('Alpha'), eventStreamId: 'bad|route' }
+            ]), 'appendMany.streamId');
+            scenario.appendedEvents.should.deep.equal(before);
+            scenario.results.should.deep.equal(results);
+            (await scenario.eventLog.getNextSequenceNumber()).value.should.equal(1n);
+            const rejected = await scenario.append('B', new Claim('Alpha'), { streamId: 'West' });
+            rejected.isSuccess.should.be.false;
+            (await pending).value![0].result.should.equal(rejected);
+            (await scenario.append('B', new Claim('Beta'), { streamId: 'West' })).sequenceNumber.value.should.equal(1n);
+        } finally { await notifications.return?.(); }
+    });
+
+    it('should roll back default-route setup without disturbing another scope', async () => {
+        const scenario = create();
+        await scenario.append('A', new Claim('Alpha'), { streamId: 'West' });
+        await scenario.given.forEventSource('A').events(new Claim('DefaultKey'));
+        const before = scenario.appendedEvents;
+        const results = scenario.results;
+        await scenario.given.forEventSource('B').events(new Claim('Temporary'), new Claim('DefaultKey'))
+            .then(() => { throw new Error('Invalid setup succeeded'); }, error => {
+                (error as Error).message.should.include('EventScenario given setup failed');
+            });
+        scenario.appendedEvents.should.deep.equal(before);
+        scenario.results.should.deep.equal(results);
+        (await scenario.append('C', new Claim('Temporary'))).isSuccess.should.be.true;
+        (await scenario.append('C', new Claim('Alpha'), { streamId: 'West' })).isSuccess.should.be.false;
+    });
+});

package/testing/for_ReactorScenario/when_enforcing_scoped_constraints/with_default_input_routes.spec.ts

@@ -0,0 +1,70 @@
+// 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 type { EventContext } from '../../../events/EventContext.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { ReactorScenario } from '../../ReactorScenario.js';
+
+chai.should();
+@eventType('ScopedReactorFirst')
+class First { @field(String) label = 'First'; }
+@eventType('ScopedReactorSibling')
+class Sibling { @field(String) label = 'Sibling'; }
+@eventType('ScopedReactorRemoved')
+@removeConstraint('ScopedReactorCycle')
+class Removed { @field(String) label = 'Removed'; }
+@eventType('ScopedReactorExpired')
+@removeConstraint('ScopedReactorCycle')
+class Expired { @field(String) label = 'Expired'; }
+@eventType('ScopedReactorEffect')
+class Effect { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@constraint('ScopedReactorFirstCycle')
+class FirstCycle {
+    define(builder: IConstraintBuilder) { builder.perEventSourceType().perEventStreamType().perEventStreamId().uniqueFor(First, 'Occupied', 'ScopedReactorCycle'); }
+}
+@constraint('ScopedReactorSiblingCycle')
+class SiblingCycle {
+    define(builder: IConstraintBuilder) { builder.perEventSourceType().perEventStreamType().perEventStreamId().uniqueFor(Sibling, 'Occupied', 'ScopedReactorCycle'); }
+}
+
+describe('when enforcing scoped reactor constraints on default-route input', () => {
+    it('should deliver only accepted cycles and retain no effects or deliveries from rejected actions', async () => {
+        const calls: EventContext[] = [];
+        @reactor('ScopedReactor')
+        class Reactor {
+            first(event: First, context: EventContext) { calls.push(context); return new Effect(event.label); }
+            sibling(event: Sibling, context: EventContext) { calls.push(context); return new Effect(event.label); }
+        }
+        const scenario = new ReactorScenario(Reactor, { artifacts: {
+            eventTypes: [First, Sibling, Removed, Expired, Effect], constraints: [FirstCycle, SiblingCycle]
+        } });
+        await scenario.given.forEventSource('A').events(new First());
+        await scenario.when.forEventSource('A').events(new Sibling()).then(
+            () => { throw new Error('Conflicting cycle delivered'); }, error => {
+                (error as Error).message.should.include('ReactorScenario action append failed');
+                (error as Error).message.should.include('ScopedReactorCycle');
+            });
+        calls.length.should.equal(1);
+        scenario.produced.length.should.equal(1);
+        scenario.results.length.should.equal(1);
+        scenario.appendedEvents.length.should.equal(1);
+        await scenario.when.forEventSource('A').events(new Removed(), new Sibling());
+        await scenario.when.forEventSource('A').events(new Expired(), new First(), new Sibling()).then(
+            () => { throw new Error('Invalid batch delivered'); }, error => {
+                (error as Error).message.should.include('ReactorScenario action append failed');
+            });
+        calls.length.should.equal(2);
+        scenario.produced.length.should.equal(2);
+        scenario.results.length.should.equal(2);
+        scenario.appendedEvents.length.should.equal(3);
+        calls.map(context => [context.eventSourceType, context.eventStreamType, context.eventStreamId])
+            .should.deep.equal([['Default', 'All', 'Default'], ['Default', 'All', 'Default']]);
+    });
+});

package/testing/for_ReactorScenario/when_enforcing_scoped_constraints/with_routed_service_appends.spec.ts

@@ -0,0 +1,65 @@
+// 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 type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import { reactor } from '../../../reactors/reactor.js';
+import type { ReactorServices } from '../../../reactors/ReactorServices.js';
+import { ReactorScenario } from '../../ReactorScenario.js';
+import { UnsupportedEventSequenceOperation } from '../../UnsupportedEventSequenceOperation.js';
+
+chai.should();
+@eventType('ScopedServiceRequested')
+class Requested { @field(String) stream: string; constructor(stream: string) { this.stream = stream; } }
+@eventType('ScopedServiceClaimed')
+class Claimed { @field(String) key = 'Key'; }
+@eventType('ScopedServiceReturned')
+class Returned { @field(String) label = 'returned'; }
+@constraint('ScopedServiceKey')
+class Key { define(builder: IConstraintBuilder) { builder.perEventStreamId().unique(key => key.on(Claimed, event => event.key)); } }
+
+describe('when a reactor explicitly appends into a constraint scope', () => {
+    it('should preserve routed service appends without routing or recursively delivering the input', async () => {
+        const successes: boolean[] = [];
+        @reactor('ScopedServiceWriter')
+        class Writer {
+            async requested(event: Requested, context: EventContext, services: ReactorServices) {
+                successes.push((await services.eventStore.eventLog.append(context.eventSourceId, new Claimed(), { streamId: event.stream })).isSuccess);
+            }
+        }
+        const scenario = new ReactorScenario(Writer, { artifacts: { eventTypes: [Requested, Claimed], constraints: [Key] } });
+        await scenario.when.forEventSource('A').events(new Requested('West'));
+        await scenario.when.forEventSource('B').events(new Requested('East'));
+        await scenario.when.forEventSource('C').events(new Requested('West'));
+        successes.should.deep.equal([true, true, false]);
+        scenario.appendedEvents.map(event => event.context.eventStreamId).should.deep.equal(['Default', 'West', 'Default', 'East', 'Default']);
+        scenario.results.length.should.equal(3);
+        scenario.produced.length.should.equal(0);
+    });
+
+    it('should fail a delivery that swallows an unsupported route and record no returned effect', async () => {
+        @reactor('ScopedServiceUnsupportedWriter')
+        class Writer {
+            async requested(_event: Requested, context: EventContext, services: ReactorServices) {
+                try { await services.eventStore.eventLog.append(context.eventSourceId, new Claimed(), { streamId: 'bad|route' }); }
+                catch { /* The harness must latch unsupported appends even if the handler swallows them. */ }
+                return new Returned();
+            }
+        }
+        const scenario = new ReactorScenario(Writer, { artifacts: { eventTypes: [Requested, Claimed, Returned], constraints: [Key] } });
+        await scenario.when.forEventSource('A').events(new Requested('West')).then(
+            () => { throw new Error('Unsupported route was swallowed'); }, error => {
+                (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+                (error as Error).message.should.include('append.streamId');
+            });
+        scenario.appendedEvents.length.should.equal(1);
+        scenario.produced.length.should.equal(0);
+        scenario.sideEffects.length.should.equal(0);
+        scenario.results[0].completed.should.be.false;
+    });
+});