@cratis/chronicle 6.19.0 → 6.21.0

package/testing/EventScenario.fixtures.spec.ts

@@ -0,0 +1,260 @@
+// 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 { readFileSync, readdirSync } from 'node:fs';
+import { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { unique } from '../events/constraints/unique.js';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber.js';
+import { CorrelationId, correlationIdManager } from '../correlation/index.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+
+class OracleEventRecorded {
+    @field(String) name: string;
+    @field(Boolean) active: boolean;
+    constructor(name: string, active: boolean) { this.name = name; this.active = active; }
+}
+eventType('OracleEventRecorded')(OracleEventRecorded);
+class AlternateRecorded {
+    @field(String) label: string;
+    constructor(label: string) { this.label = label; }
+}
+eventType('AlternateRecorded')(AlternateRecorded);
+class BoundaryRecorded {
+    @field(String) firstName: string;
+    @field(String) label: string;
+    constructor(firstName: string, label: string) { this.firstName = firstName; this.label = label; }
+}
+eventType('BoundaryRecorded')(BoundaryRecorded);
+class UnknownEvent {}
+class UnprovenNumber {
+    @field(Number) amount = 1;
+}
+eventType('UnprovenNumber')(UnprovenNumber);
+class ConstrainedEvent {
+    @field(String) value = 'value';
+}
+eventType('ConstrainedEvent')(ConstrainedEvent);
+unique()(ConstrainedEvent);
+
+interface Fixture {
+    actions: Array<{ type?: string; source: string; name?: string; firstName?: string; active?: boolean; label?: string; occurred?: string; correlationId?: string; clientCausation?: boolean }>;
+    expected: {
+        results: Array<{ success: boolean; sequenceNumber: string; violations: number; errors: number;
+            concurrencyViolation: boolean; waitError: string }>;
+        history: Array<{ sequenceNumber: string; source: string; sourceType: string; streamType: string; streamId: string;
+            subject: string; store: string; namespace: string; eventType: string; generation: number; hash: string; content: object;
+            occurredValid: boolean; correlationValid: boolean; explicitOccurred: string | null; explicitCorrelation: string | null;
+            tagsCount: number; causedByName: string; observationState: number; causationCount: number;
+            causation: Array<{ type: string; properties: Record<string, string> }> }>;
+        next: string; tail: string; tailA: string; hasSourceA: boolean; sourceA: string[]; fromOne: string[]; byType: string[];
+    };
+}
+const directory = new URL('./fixtures/', import.meta.url);
+const fixtures = readdirSync(directory).filter(name => name.endsWith('.json') &&
+    !['batches.json', 'batch-omitted-routes.json', 'batch-rollback.json', 'builders.json'].includes(name)).map(name => ({
+    name, fixture: JSON.parse(readFileSync(new URL(name, directory), 'utf8')) as Fixture
+}));
+const artifacts = { eventTypes: [OracleEventRecorded, AlternateRecorded, BoundaryRecorded], constraints: [] };
+const makeScenario = (action?: Fixture['actions'][number]) => new EventScenario({
+    artifacts, constraints: 'disabled',
+    clock: action?.occurred ? () => new Date(action.occurred!) : undefined,
+    correlationId: action?.correlationId ? () => action.correlationId! : undefined
+});
+
+async function unsupportedAsync(action: () => Promise<unknown>, operation: string): Promise<void> {
+    await action().then(
+        () => { throw new Error(`Expected ${operation} rejection`); },
+        error => {
+            (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+            (error as Error).message.should.include(operation);
+            (error as Error).message.should.include('Use a kernel-backed test.');
+        }
+    );
+}
+
+function unsupported(action: () => unknown, operation: string): void {
+    try { action(); throw new Error('Expected rejection'); }
+    catch (error) {
+        (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+        (error as Error).message.should.include(operation);
+        (error as Error).message.should.include('Use a kernel-backed test.');
+    }
+}
+
+describe('when appending against committed kernel event fixtures', () => {
+    it('should include a non-vacuous empty sequence, single append, alternate schema and interleaved sources', () => {
+        fixtures.map(item => item.name).should.deep.equal(['alternate.json', 'boundary.json', 'client-causation.json', 'empty.json', 'explicit-metadata.json', 'interleaved.json', 'single.json', 'source-tail-before-global.json']);
+    });
+
+    for (const { name, fixture } of fixtures) {
+        it(`should match the accepted event and essential read snapshots for ${name}`, async () => {
+            const scenario = makeScenario(fixture.actions[0]);
+            for (const action of fixture.actions) {
+                const event = action.type === 'alternate'
+                    ? new AlternateRecorded(action.label!) : action.type === 'boundary'
+                        ? new BoundaryRecorded(action.firstName!, action.label!) : new OracleEventRecorded(action.name!, action.active!);
+                const result = await scenario.append(action.source, event);
+                result.isSuccess.should.equal(true);
+            }
+            scenario.results.map(item => ({ success: item.isSuccess, sequenceNumber: item.sequenceNumber.value.toString(),
+                violations: item.constraintViolations.length, errors: item.errors.length,
+                concurrencyViolation: item.concurrencyViolation !== undefined }))
+                .should.deep.equal(fixture.expected.results.map(({ waitError: _waitError, ...result }) => result));
+            for (const [index, result] of scenario.results.entries()) {
+                fixture.expected.results[index].waitError.should.equal('CannotWaitForObserverCompletion');
+                await result.waitForCompletion().then(
+                    () => { throw new Error('Observers did not run but completion succeeded'); },
+                    error => { (error instanceof UnsupportedEventSequenceOperation).should.be.true; }
+                );
+            }
+            const history = scenario.appendedEvents;
+            history.length.should.equal(fixture.expected.history.length);
+            for (let index = 0; index < history.length; index++) {
+                const actual = history[index];
+                const expected = fixture.expected.history[index];
+                ({ sequenceNumber: actual.context.sequenceNumber.toString(), source: actual.context.eventSourceId,
+                    sourceType: actual.context.eventSourceType, streamType: actual.context.eventStreamType,
+                    streamId: actual.context.eventStreamId, subject: actual.context.subject,
+                    store: actual.context.eventStore, namespace: actual.context.namespace,
+                    eventType: actual.eventType.id.value, generation: actual.eventType.generation.value,
+                    hash: actual.context.hash, content: actual.content }).should.deep.equal({
+                    sequenceNumber: expected.sequenceNumber, source: expected.source,
+                    sourceType: expected.sourceType, streamType: expected.streamType, streamId: expected.streamId,
+                    subject: expected.subject, store: expected.store, namespace: expected.namespace,
+                    eventType: expected.eventType, generation: expected.generation, hash: expected.hash, content: expected.content
+                });
+                (actual.context.occurred instanceof Date && !Number.isNaN(actual.context.occurred.getTime())).should.equal(expected.occurredValid);
+                /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(actual.context.correlationId)
+                    .should.equal(expected.correlationValid);
+                actual.context.tags.length.should.equal(expected.tagsCount);
+                actual.context.causedBy!.name.should.equal(expected.causedByName);
+                actual.context.observationState!.should.equal(expected.observationState);
+                const causation = actual.context.causation.map(item => ({ type: item.type, properties: item.properties }));
+                if (fixture.actions[index].clientCausation) {
+                    causation.should.deep.equal(expected.causation);
+                    causation.length.should.equal(expected.causationCount);
+                } else {
+                    // The .NET client's default root is Unknown; the TS client prepares Root + Append.
+                    expected.causation.should.deep.equal([{ type: 'Unknown', properties: {} }]);
+                    causation.should.deep.equal([
+                        { type: 'Root', properties: {} },
+                        { type: 'TypeScriptClient.Append', properties: { eventType: expected.eventType } }
+                    ]);
+                }
+                if (expected.explicitOccurred) {
+                    actual.context.occurred.toISOString().slice(0, 19).should.equal(expected.explicitOccurred.slice(0, 19));
+                    actual.context.correlationId.should.equal(expected.explicitCorrelation);
+                }
+            }
+            (await scenario.eventSequence.getNextSequenceNumber()).value.toString().should.equal(fixture.expected.next);
+            (await scenario.eventSequence.getTailSequenceNumber()).value.toString().should.equal(fixture.expected.tail);
+            (await scenario.eventSequence.getTailSequenceNumber('A')).value.toString().should.equal(fixture.expected.tailA);
+            if (name === 'source-tail-before-global.json') {
+                fixture.expected.tailA.should.not.equal(fixture.expected.tail);
+            }
+            (await scenario.eventSequence.hasEventsFor('A')).should.equal(fixture.expected.hasSourceA);
+            const sourceEvents = await scenario.eventSequence.getFromSequenceNumber(EventSequenceNumber.first, 'A');
+            sourceEvents.map(item => item.context.sequenceNumber.toString()).should.deep.equal(fixture.expected.sourceA);
+            sourceEvents.map(item => item.context.observationState).should.deep.equal(
+                fixture.expected.history.filter(item => item.source === 'A').map(item => item.observationState));
+            (await scenario.eventSequence.getFromSequenceNumber(new EventSequenceNumber(1n)))
+                .map(item => item.context.sequenceNumber.toString()).should.deep.equal(fixture.expected.fromOne);
+            const byType = await scenario.eventSequence.getForEventSourceIdAndEventTypes('A', [OracleEventRecorded]);
+            byType.map(item => item.context.sequenceNumber.toString()).should.deep.equal(fixture.expected.byType);
+            byType.map(item => item.context.observationState).should.deep.equal(
+                fixture.expected.history.filter(item => item.source === 'A' && item.eventType === 'OracleEventRecorded')
+                    .map(item => item.observationState));
+        });
+    }
+
+    it('should keep setup out of results, protect history, and allow a single when action', async () => {
+        const scenario = makeScenario();
+        const seed = new OracleEventRecorded('seed', true);
+        await scenario.given.forEventSource('A').events(seed);
+        seed.name = 'changed';
+        (await scenario.when.forEventSource('B').event(new AlternateRecorded('act'))).isSuccess.should.be.true;
+        scenario.results.length.should.equal(1);
+        scenario.then.results.should.deep.equal(scenario.results);
+        scenario.appendedEvents[0].content.should.deep.equal({ name: 'seed', active: true });
+        (scenario.appendedEvents[0].content as { name: string }).name = 'changed again';
+        scenario.appendedEvents[0].content.should.deep.equal({ name: 'seed', active: true });
+        (await scenario).should.equal(scenario);
+        scenario.eventLog.should.equal(scenario.eventSequence);
+    });
+
+
+    it('should reject unproven schemas, event registrations and constraints before appending', async () => {
+        unsupported(() => new EventScenario({ artifacts: { eventTypes: [UnprovenNumber] }, constraints: 'disabled' }), 'schema');
+        unsupported(() => new EventScenario({ artifacts: { eventTypes: [ConstrainedEvent] } }), 'constraints');
+        unsupported(() => new EventScenario({ artifacts }), 'empty constraint catalog');
+        unsupported(() => new EventScenario({ artifacts, constraints: 'disabled', eventStore: 'other-store' }), 'eventStore');
+        const scenario = makeScenario();
+        try { await scenario.append('A', new UnknownEvent()); throw new Error('Expected rejection'); }
+        catch (error) { (error instanceof UnsupportedEventSequenceOperation).should.be.true; }
+        scenario.appendedEvents.length.should.equal(0);
+    });
+
+    it('should reject an act that overlaps unfinished setup without losing its result', async () => {
+        const scenario = makeScenario();
+        const pending = scenario.given.forEventSource('A').events(new OracleEventRecorded('seed', true));
+        await scenario.append('B', new AlternateRecorded('act')).then(
+            () => { throw new Error('Overlapping append succeeded'); },
+            error => { (error instanceof UnsupportedEventSequenceOperation).should.be.true; }
+        );
+        await pending;
+        scenario.results.length.should.equal(0);
+        scenario.appendedEvents.length.should.equal(1);
+    });
+
+    it('should reject prototype getters and non-enumerable append metadata without mutation', async () => {
+        const scenario = makeScenario();
+        class OptionsWithGetters {
+            get subject() { return 'different-subject'; }
+            get streamId() { return 'different-stream'; }
+        }
+        await unsupportedAsync(() => scenario.append('A', new OracleEventRecorded('one', true), new OptionsWithGetters()), 'append.options');
+        const hidden = Object.defineProperty({}, 'subject', { value: 'different-subject', enumerable: false });
+        await unsupportedAsync(() => scenario.append('A', new OracleEventRecorded('one', true), hidden), 'append.options');
+        scenario.appendedEvents.length.should.equal(0);
+        scenario.results.length.should.equal(0);
+    });
+
+    it('should reject malformed hook and ambient correlation IDs before mutation', async () => {
+        const malformed = 'zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz';
+        const fromHook = new EventScenario({ artifacts, constraints: 'disabled', correlationId: () => malformed });
+        await unsupportedAsync(() => fromHook.append('A', new OracleEventRecorded('one', true)), 'append.correlationId');
+        fromHook.appendedEvents.length.should.equal(0);
+        fromHook.results.length.should.equal(0);
+        const fromAmbient = makeScenario();
+        await correlationIdManager.run(new CorrelationId(malformed), () =>
+            unsupportedAsync(() => fromAmbient.append('A', new OracleEventRecorded('one', true)), 'append.correlationId'));
+        fromAmbient.appendedEvents.length.should.equal(0);
+        fromAmbient.results.length.should.equal(0);
+    });
+
+    it('should reject unproven blank and padded read source filters', async () => {
+        const scenario = makeScenario();
+        await scenario.append('A', new OracleEventRecorded('one', true));
+        for (const source of ['', ' ', ' A ']) {
+            await unsupportedAsync(() => scenario.eventSequence.hasEventsFor(source), 'hasEventsFor.source');
+            await unsupportedAsync(() => scenario.eventSequence.getTailSequenceNumber(source), 'getTailSequenceNumber.source');
+            await unsupportedAsync(() => scenario.eventSequence.getFromSequenceNumber(EventSequenceNumber.first, source), 'getFromSequenceNumber.source');
+            await unsupportedAsync(() => scenario.eventSequence.getForEventSourceIdAndEventTypes(source, [OracleEventRecorded]), 'getForEventSourceIdAndEventTypes.source');
+        }
+        scenario.appendedEvents.length.should.equal(1);
+        scenario.results.length.should.equal(1);
+    });
+
+    it('should record direct act-phase append calls without reporting setup results', async () => {
+        const scenario = makeScenario();
+        await scenario.given.forEventSource('A').events(new OracleEventRecorded('seed', true));
+        await scenario.eventSequence.append('B', new AlternateRecorded('act'));
+        scenario.results.length.should.equal(1);
+        scenario.appendedEvents.length.should.equal(2);
+    });
+});

package/testing/EventScenario.rejections.spec.ts

@@ -0,0 +1,273 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { causationManager, CausationType } from '../auditing/index.js';
+import { identityProvider, Identity } from '../identity/index.js';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { tag } from '../events/tagDecorator.js';
+import { unique } from '../events/constraints/unique.js';
+import { removeConstraint } from '../events/constraints/removeConstraint.js';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+
+class Recorded {
+    @field(String) name = 'recorded';
+}
+eventType('Recorded')(Recorded);
+class PropertyUnique {
+    @field(String) @unique() name = 'value';
+}
+eventType('PropertyUnique')(PropertyUnique);
+class RemovesConstraint {
+    @field(String) name = 'value';
+}
+eventType('RemovesConstraint')(RemovesConstraint);
+removeConstraint('name')(RemovesConstraint);
+class Tagged {
+    @field(String) name = 'value';
+}
+eventType('Tagged')(Tagged);
+tag('tagged')(Tagged);
+class LaterGeneration {
+    @field(String) name = 'value';
+}
+eventType('LaterGeneration', 2)(LaterGeneration);
+class Tombstone {
+    @field(String) name = 'value';
+}
+eventType('Tombstone', 1, true)(Tombstone);
+class CommaId {
+    @field(String) name = 'value';
+}
+eventType('Odd,Type')(CommaId);
+class PaddedId {
+    @field(String) name = 'value';
+}
+eventType(' PaddedId ')(PaddedId);
+class NonAsciiPaddedId {
+    @field(String) name = 'value';
+}
+eventType('\u0085NonAsciiPaddedId\u0085')(NonAsciiPaddedId);
+class DuplicateId {
+    @field(String) name = 'value';
+}
+eventType('Recorded')(DuplicateId);
+
+const scenario = () => new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled' });
+const clean = (subject: EventScenario) => {
+    subject.results.length.should.equal(0);
+    subject.appendedEvents.length.should.equal(0);
+};
+function rejected(action: () => unknown, operation: string): void {
+    try { action(); throw new Error(`Expected ${operation} rejection`); }
+    catch (error) {
+        (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+        (error as Error).message.should.include(operation);
+        (error as Error).message.should.include('Use a kernel-backed test.');
+    }
+}
+async function rejects(action: () => Promise<unknown>, operation: string): Promise<void> {
+    await action().then(
+        () => { throw new Error(`Expected ${operation} rejection`); },
+        error => {
+            (error instanceof UnsupportedEventSequenceOperation).should.be.true;
+            (error as Error).message.should.include(operation);
+            (error as Error).message.should.include('Use a kernel-backed test.');
+        }
+    );
+}
+
+describe('when the fixture-bounded event sequence encounters unproven operations', () => {
+    for (const [type, operation] of [
+        [PropertyUnique, 'artifacts.constraints'], [RemovesConstraint, 'artifacts.eventTypes.constraints'], [Tagged, 'tags'],
+        [LaterGeneration, 'artifacts.eventTypes'], [Tombstone, 'artifacts.eventTypes'],
+        [CommaId, 'artifacts.eventTypes.id'], [PaddedId, 'artifacts.eventTypes.id'],
+        [NonAsciiPaddedId, 'artifacts.eventTypes.id']
+    ] as const) {
+        it(`should reject ${type.name} during catalog validation`, () => {
+            const subject = scenario();
+            rejected(() => new EventScenario({ artifacts: { eventTypes: [type] },
+                ...(type === PropertyUnique || type === RemovesConstraint ? {} : { constraints: 'disabled' as const }) }), operation);
+            clean(subject);
+        });
+    }
+
+    it('should reject duplicate event IDs in the catalog', () => {
+        const subject = scenario();
+        rejected(() => new EventScenario({ artifacts: { eventTypes: [Recorded, DuplicateId] }, constraints: 'disabled' }), 'artifacts.eventTypes');
+        clean(subject);
+    });
+    it('should reject migrations', () => {
+        const subject = scenario();
+        rejected(() => new EventScenario({ artifacts: { eventTypes: [Recorded], eventTypeMigrations: [class Migration {}] }, constraints: 'disabled' }), 'artifacts.eventTypeMigrations');
+        clean(subject);
+    });
+    it('should reject custom namespace', () => {
+        const subject = scenario();
+        rejected(() => new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled', namespace: 'other' }), 'options.namespace');
+        clean(subject);
+    });
+    it('should reject custom sequence ID', () => {
+        const subject = scenario();
+        rejected(() => new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled', eventSequenceId: new EventSequenceId('other') }), 'options.eventSequenceId');
+        clean(subject);
+    });
+    it('should reject transactional operations', () => {
+        const subject = scenario();
+        rejected(() => subject.eventSequence.transactional, 'transactional');
+        clean(subject);
+    });
+    it('should reject unproven route filters and unknown event types', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.getTailSequenceNumber('A', ' A '), 'getTailSequenceNumber.filters');
+        await rejects(() => subject.eventSequence.getTailSequenceNumber('A', undefined, undefined, undefined, [DuplicateId]), 'read.eventTypes');
+        await rejects(() => subject.eventSequence.getFromSequenceNumber(EventSequenceNumber.first, 'A', [DuplicateId]), 'read.eventTypes');
+        await rejects(() => subject.eventSequence.getForEventSourceIdAndEventTypes('A', [Recorded], ' A '), 'getForEventSourceIdAndEventTypes.filters');
+        clean(subject);
+    });
+    for (const value of [-1n, EventSequenceNumber.unset.value + 1n]) {
+        it(`should reject out-of-range sequence number ${value}`, async () => {
+            const subject = scenario();
+            await rejects(() => subject.eventSequence.getFromSequenceNumber(new EventSequenceNumber(value)), 'getFromSequenceNumber.sequenceNumber');
+            clean(subject);
+        });
+    }
+    it('should asynchronously reject redaction by sequence', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.redact(EventSequenceNumber.first, 'reason'), 'redact');
+        clean(subject);
+    });
+    it('should asynchronously reject redaction by source', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.redactForEventSource('A', 'reason'), 'redactForEventSource');
+        clean(subject);
+    });
+    it('should asynchronously reject stream completion', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.completeStream('All', 'Default'), 'completeStream');
+        clean(subject);
+    });
+    it('should asynchronously reject observer tail reads', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.getTailSequenceNumberForObserver(Recorded), 'getTailSequenceNumberForObserver');
+        clean(subject);
+    });
+    it('should reject ambient identity before append', async () => {
+        const subject = scenario();
+        await identityProvider.run(new Identity('user', 'User'), () => rejects(() => subject.append('A', new Recorded()), 'append.context'));
+        clean(subject);
+    });
+    it('should reject ambient causation before append', async () => {
+        const subject = scenario();
+        await causationManager.run(new CausationType('Command'), { value: 'test' }, () =>
+            rejects(() => subject.append('A', new Recorded()), 'append.context'));
+        clean(subject);
+    });
+    it('should reject an invalid scenario clock before append', async () => {
+        const subject = new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled', clock: () => new Date(NaN) });
+        await rejects(() => subject.append('A', new Recorded()), 'append.clock');
+        clean(subject);
+    });
+    for (const date of ['0000-12-31T23:59:59.999Z', '+010000-01-01T00:00:00.000Z']) {
+        it(`should reject out-of-range UTC occurrence ${date} without changing history or results`, async () => {
+            let clock = new Date('2024-01-01T00:00:00.000Z');
+            const subject = new EventScenario({ artifacts: { eventTypes: [Recorded] }, constraints: 'disabled', clock: () => clock });
+            await subject.append('A', new Recorded());
+            const history = subject.appendedEvents;
+            const results = subject.results;
+            clock = new Date(date);
+            await rejects(() => subject.append('B', new Recorded()), 'append.clock');
+            subject.appendedEvents.should.deep.equal(history);
+            subject.results.should.deep.equal(results);
+        });
+    }
+    for (const [name, value] of [
+        ['quote', '"'], ['backslash', '\\'], ['DEL', '\u007f'], ['uppercase accented letter', '\u00c9'],
+        ['decomposed accent', 'e\u0301'], ['Japanese', '日本'], ['tab', '\t']
+    ] as const) {
+        it(`should reject ${name} outside the fixture-backed content domain`, async () => {
+            const subject = scenario();
+            const event = new Recorded();
+            event.name = value;
+            await rejects(() => subject.append('A', event), 'append.content');
+            clean(subject);
+        });
+    }
+    for (const [name, value] of [['missing', undefined], ['numeric', 42]] as const) {
+        it(`should reject ${name} content`, async () => {
+            const subject = scenario();
+            const event = new Recorded();
+            Object.assign(event, { name: value });
+            await rejects(() => subject.append('A', event), 'append.content');
+            clean(subject);
+        });
+    }
+    it('should reject extra content fields', async () => {
+        const subject = scenario();
+        const event = Object.assign(new Recorded(), { extra: 'value' });
+        await rejects(() => subject.append('A', event), 'append.content');
+        clean(subject);
+    });
+    for (const source of ['a b', 'a|b', '\u00c9']) {
+        it(`should reject unsupported append source ${JSON.stringify(source)}`, async () => {
+            const subject = scenario();
+            await rejects(() => subject.append(source, new Recorded()), 'append.source');
+            clean(subject);
+        });
+    }
+    it('should reject plain correlation options', async () => {
+        const subject = scenario();
+        await rejects(() => subject.append('A', new Recorded(), { correlationId: '00000000-0000-0000-0000-000000000001' }), 'append.options');
+        clean(subject);
+    });
+    it('should reject plain subject options', async () => {
+        const subject = scenario();
+        await rejects(() => subject.append('A', new Recorded(), { subject: 'other' }), 'append.options');
+        clean(subject);
+    });
+    it('should reject empty source/type-read event types', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.getForEventSourceIdAndEventTypes('A', []), 'getForEventSourceIdAndEventTypes.filters');
+        clean(subject);
+    });
+    it('should reject unregistered source/type-read event types', async () => {
+        const subject = scenario();
+        await rejects(() => subject.eventSequence.getForEventSourceIdAndEventTypes('A', [DuplicateId]), 'read.eventTypes');
+        clean(subject);
+    });
+    it('should reject non-ASCII padded read sources before returning an incorrect result', async () => {
+        const subject = scenario();
+        await subject.append('A', new Recorded());
+        const history = subject.appendedEvents;
+        const results = subject.results;
+        for (const source of ['\u0085A\u0085', 'A\u00a0', 'A\u007f', 'A\u2000B']) {
+            await rejects(() => subject.eventSequence.hasEventsFor(source), 'hasEventsFor.source');
+            await rejects(() => subject.eventSequence.getTailSequenceNumber(source), 'getTailSequenceNumber.source');
+            await rejects(() => subject.eventSequence.getFromSequenceNumber(EventSequenceNumber.first, source), 'getFromSequenceNumber.source');
+            await rejects(() => subject.eventSequence.getForEventSourceIdAndEventTypes(source, [Recorded]), 'getForEventSourceIdAndEventTypes.source');
+        }
+        subject.appendedEvents.should.deep.equal(history);
+        subject.results.should.deep.equal(results);
+    });
+    it('should reject overlapping act appends, including separate act entry points', async () => {
+        const subject = scenario();
+        const [first, second] = await Promise.allSettled([
+            subject.append('A', new Recorded()),
+            subject.eventLog.append('B', new Recorded())
+        ]);
+        first.status.should.equal('fulfilled');
+        second.status.should.equal('rejected');
+        if (second.status === 'rejected') {
+            (second.reason instanceof UnsupportedEventSequenceOperation).should.be.true;
+            (second.reason as Error).message.should.include('append');
+        }
+        subject.appendedEvents.length.should.equal(1);
+        subject.results.length.should.equal(1);
+    });
+});

package/testing/EventScenario.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
+import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import type { AppendResult } from '../eventSequences/AppendResult.js';
+import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
+import type { AppendedEvent } from '../events/AppendedEvent.js';
+import type { IEventSequence } from '../eventSequences/IEventSequence.js';
+import type { IEventLog } from '../eventSequences/IEventLog.js';
+import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getUniqueEventMetadata, getUniquePropertyMetadata } from '../events/constraints/unique.js';
+import type { EventScenarioOptions } from './EventScenarioOptions.js';
+import { EventScenarioGivenBuilder } from './EventScenarioGivenBuilder.js';
+import { EventScenarioWhenBuilder } from './EventScenarioWhenBuilder.js';
+import { InProcessEventSequence } from './InProcessEventSequence.js';
+import { registerScenarioSeed } from './EventScenarioSeed.js';
+import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+/** A kernel-free, fixture-bounded append scenario. No observer runs automatically. */
+export class EventScenario {
+    readonly eventSequence: IEventSequence;
+    readonly given: EventScenarioGivenBuilder;
+    readonly when: EventScenarioWhenBuilder;
+
+    constructor(options: EventScenarioOptions = {}) {
+        const artifacts = options.artifacts ?? new DefaultClientArtifactsProvider(TypeDiscoverer.default);
+        const eventTypes = [...artifacts.eventTypes];
+        if (options.artifacts?.constraints?.length === 0 && options.constraints !== 'disabled') {
+            throw new UnsupportedEventSequenceOperation('artifacts.constraints', 'empty constraint catalog',
+                'An empty selected catalog cannot silently disable constraint discovery; set constraints: disabled explicitly.');
+        }
+        const discovered = options.artifacts?.constraints ?? new DefaultClientArtifactsProvider(TypeDiscoverer.default).constraints;
+        if (options.constraints !== 'disabled' && (discovered.length || eventTypes.some(type => {
+            const metadata = getEventTypeMetadata(type);
+            return getUniqueEventMetadata(type) || [...(metadata?.members.keys() ?? [])].some(key => getUniquePropertyMetadata(type, key));
+        }))) {
+            throw new UnsupportedEventSequenceOperation('artifacts.constraints', discovered.map(type => type.name).join(', ') || 'event metadata',
+                'Constraint definitions are rejected until kernel-backed constraint fixtures are available.');
+        }
+        if (artifacts.eventTypeMigrations?.length) {
+            throw new UnsupportedEventSequenceOperation('artifacts.eventTypeMigrations', artifacts.eventTypeMigrations.map(type => type.name).join(', '),
+                'Migrations are not fixture-backed.');
+        }
+        const sequence = new InProcessEventSequence(options, eventTypes);
+        this.eventSequence = sequence;
+        registerScenarioSeed(this, (source, events) => sequence.seed(source, events));
+        this.given = new EventScenarioGivenBuilder(this);
+        this.when = new EventScenarioWhenBuilder(this);
+    }
+
+    /** Alias for the default event-log sequence only. */
+    get eventLog(): IEventLog {
+        if (this.eventSequence.id.value !== EventSequenceId.eventLog.value) {
+            throw new UnsupportedEventSequenceOperation('eventLog', this.eventSequence.id.value, 'Only the default sequence is an event log.');
+        }
+        return this.eventSequence;
+    }
+    async append(source: string, event: object, options?: AppendOptions): Promise<AppendResult> {
+        return this.eventSequence.append(source, event, options);
+    }
+    appendMany(source: string, events: object[], options?: AppendOptions): Promise<AppendResult[]>;
+    appendMany(events: EventForEventSourceId[], options?: AppendOptions): Promise<AppendResult[]>;
+    async appendMany(sourceOrEvents: string | EventForEventSourceId[], eventsOrOptions?: object[] | AppendOptions, options?: AppendOptions): Promise<AppendResult[]> {
+        if (typeof sourceOrEvents === 'string') {
+            return this.eventSequence.appendMany(sourceOrEvents, eventsOrOptions as object[], options);
+        }
+        return this.eventSequence.appendMany(sourceOrEvents, eventsOrOptions as AppendOptions | undefined);
+    }
+    get results(): readonly AppendResult[] { return (this.eventSequence as InProcessEventSequence).results; }
+    get appendedEvents(): readonly AppendedEvent[] { return (this.eventSequence as InProcessEventSequence).appendedEvents; }
+
+    /** Assertion view, not a callable Promise-like then method. */
+    get then(): { readonly results: readonly AppendResult[]; readonly appendedEvents: readonly AppendedEvent[] } {
+        return { results: this.results, appendedEvents: this.appendedEvents };
+    }
+}

package/testing/EventScenarioGiven.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+import { seedScenario } from './EventScenarioSeed.js';
+
+/** Seeds events in order through individual single appends, as in the .NET given builder. */
+export class EventScenarioGiven {
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
+    async events(...events: object[]): Promise<void> {
+        await seedScenario(this._scenario, this._id, events);
+    }
+}

package/testing/EventScenarioGivenBuilder.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventScenario } from './EventScenario.js';
+import { EventScenarioGiven } from './EventScenarioGiven.js';
+
+/** Selects the source for setup events. */
+export class EventScenarioGivenBuilder {
+    constructor(private readonly _scenario: EventScenario) {}
+    forEventSource(id: string): EventScenarioGiven { return new EventScenarioGiven(this._scenario, id); }
+}