@cratis/chronicle 6.40.0 → 6.41.1

package/eventSequences/for_EventSequence/when_appending/subject_behaviors.fixture.ts

@@ -0,0 +1,239 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { resolveEventSubject } from '../../../compliance/resolveEventSubject.js';
+import { Guid, 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 '../../EventSequence.js';
+import { EventSequenceId } from '../../EventSequenceId.js';
+import { EventScenario } from '../../../testing/EventScenario.js';
+import { UnitOfWork } from '../../../transactions/UnitOfWork.js';
+import type { IUnitOfWorkManager } from '../../../transactions/IUnitOfWorkManager.js';
+import type { IEventStore } from '../../../IEventStore.js';
+
+const should = chai.should();
+function check(value: unknown): Assertion { return (value as { should: Assertion }).should; }
+
+export function subjectBehaviors(fixtures: {
+    types: Constructor[];
+    annotated: (value: string) => object;
+    inherited: (value: string) => object;
+    concept: (value: string) => object;
+    unannotated: () => object;
+}): void {
+    function connected() {
+        const append = vi.fn().mockResolvedValue({ Response: { SequenceNumber: 0n } });
+        const appendManyForEventSources = vi.fn().mockImplementation(async (request: { Events: object[] }) => ({
+            Response: { SequenceNumbers: request.Events.map((_, index) => BigInt(index)) }
+        }));
+        const manager = {} as IUnitOfWorkManager;
+        const sequence = new EventSequence(EventSequenceId.eventLog, 'store', 'Default',
+            { eventSequences: { append, appendManyForEventSources } } as unknown as ChronicleConnection, manager);
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {},
+            { getEventSequence: () => sequence } as unknown as IEventStore);
+        Object.assign(manager, { current: unitOfWork });
+        return { sequence, unitOfWork, append, appendManyForEventSources };
+    }
+    function scenario() {
+        return new EventScenario({ artifacts: { eventTypes: fixtures.types, constraints: [] }, constraints: 'disabled' });
+    }
+
+    const cases = [
+        { name: 'an annotated subject', event: () => fixtures.annotated('person'), expected: 'person', stored: 'person' },
+        { name: 'an inherited annotated subject', event: () => fixtures.inherited('person'), expected: 'person', stored: 'person' },
+        { name: 'a concept subject', event: () => fixtures.concept('person'), expected: 'person', stored: 'person' },
+        { name: 'an empty annotated string', event: () => fixtures.annotated(''), expected: '', stored: 'source' },
+        { name: 'a whitespace annotated string', event: () => fixtures.annotated('  '), expected: '  ', stored: 'source' },
+        { name: 'an empty concept subject', event: () => fixtures.concept(''), expected: 'source', stored: 'source' },
+        { name: 'no annotation despite an id property', event: fixtures.unannotated, expected: 'source', stored: 'source' }
+    ];
+    for (const testCase of cases) {
+        describe(`when appending with ${testCase.name}`, () => {
+            let wireSubjects: string[];
+            let scenarioSubjects: (string | undefined)[];
+            beforeEach(async () => {
+                const client = connected();
+                const memory = scenario();
+                await client.sequence.append('source', testCase.event());
+                await memory.append('source', testCase.event());
+                await client.sequence.appendMany('source', [testCase.event()]);
+                await memory.appendMany('source', [testCase.event()]);
+                await client.sequence.appendMany([{ eventSourceId: 'source', event: testCase.event() }]);
+                await memory.appendMany([{ eventSourceId: 'source', event: testCase.event() }]);
+                wireSubjects = [client.append.mock.calls[0][0].Subject,
+                    ...client.appendManyForEventSources.mock.calls.map(call => call[0].Events[0].Subject)];
+                scenarioSubjects = memory.appendedEvents.map(event => event.context.subject);
+            });
+            it('should select the wire subject using .NET value semantics in every append overload', () => {
+                check(wireSubjects).deep.equal([testCase.expected, testCase.expected, testCase.expected]);
+            });
+            it('should record the kernel subject in every scenario append overload', () => {
+                check(scenarioSubjects).deep.equal([testCase.stored, testCase.stored, testCase.stored]);
+            });
+        });
+    }
+    for (const testCase of [
+        { value: undefined, expected: 'source' },
+        { value: 0, expected: '0' },
+        { value: false, expected: 'false' },
+        { value: Guid.as('00000000-0000-0000-0000-000000000001'), expected: '00000000-0000-0000-0000-000000000001' },
+        { value: { toString: () => '' }, expected: 'source' },
+        { value: { toString: () => null }, expected: 'source' }
+    ]) {
+        describe(`when an annotated property contains ${String(testCase.value)}`, () => {
+            let subjects: string[];
+            beforeEach(async () => {
+                const client = connected();
+                const event = fixtures.annotated('person');
+                Reflect.set(event, 'personId', testCase.value);
+                await client.sequence.append('source', event);
+                await client.sequence.appendMany('source', [event]);
+                await client.sequence.appendMany([{ eventSourceId: 'source', event }]);
+                subjects = [client.append.mock.calls[0][0].Subject,
+                    ...client.appendManyForEventSources.mock.calls.map(call => call[0].Events[0].Subject)];
+            });
+            it('should preserve .NET conversion and null fallback in every append overload', () => {
+                check(subjects).deep.equal([testCase.expected, testCase.expected, testCase.expected]);
+            });
+        });
+    }
+    describe('when resolving a null annotated property before serialization', () => {
+        let selected: string | undefined;
+        beforeEach(() => {
+            const event = fixtures.annotated('person');
+            Reflect.set(event, 'personId', null);
+            selected = resolveEventSubject(event);
+        });
+        it('should leave the subject unresolved for source fallback', () => should.equal(selected, undefined));
+    });
+    for (const { subject, stored } of [
+        { subject: 'explicit', stored: 'explicit' },
+        { subject: '', stored: 'source' },
+        { subject: '  ', stored: 'source' },
+        { subject: '\t\r\n', stored: 'source' },
+        { subject: '\u0085\u00a0', stored: 'source' },
+        { subject: '\ufeff', stored: '\ufeff' },
+        { subject: ' person ', stored: ' person ' }
+    ]) {
+        describe(`when overriding the annotation with ${JSON.stringify(subject)}`, () => {
+            let wireSubject: string;
+            let scenarioSubject: string | undefined;
+            beforeEach(async () => {
+                const client = connected();
+                const memory = scenario();
+                await client.sequence.append('source', fixtures.annotated('person'), { subject });
+                await memory.append('source', fixtures.annotated('person'), { subject });
+                wireSubject = client.append.mock.calls[0][0].Subject;
+                scenarioSubject = memory.appendedEvents[0].context.subject;
+            });
+            it('should prefer the explicit subject', () => should.equal(wireSubject, subject));
+            it('should record the kernel subject in the scenario', () => should.equal(scenarioSubject, stored));
+        });
+    }
+    for (const overload of ['single source', 'multiple sources'] as const) {
+        for (const subject of [undefined, 'shared', '', '  ']) {
+            describe(`when appending a ${overload} batch with shared subject ${JSON.stringify(subject)}`, () => {
+                let wireSubjects: string[];
+                let scenarioSubjects: (string | undefined)[];
+                beforeEach(async () => {
+                    const client = connected();
+                    const memory = scenario();
+                    const events = [fixtures.annotated('person'), fixtures.concept('other'), fixtures.unannotated()];
+                    if (overload === 'single source') {
+                        await client.sequence.appendMany('source', events, { subject });
+                        await memory.appendMany('source', events, { subject });
+                    } else {
+                        const entries = events.map((event, index) => ({ eventSourceId: 'source', event, subject: index === 0 ? 'entry' : undefined }));
+                        await client.sequence.appendMany(entries, { subject });
+                        await memory.appendMany(entries, { subject });
+                    }
+                    wireSubjects = client.appendManyForEventSources.mock.calls[0][0].Events.map((entry: { Subject: string }) => entry.Subject);
+                    scenarioSubjects = memory.appendedEvents.map(event => event.context.subject);
+                });
+                it('should prefer entry then shared then annotation then source', () => {
+                    check(wireSubjects).deep.equal([overload === 'multiple sources' ? 'entry' : subject ?? 'person', subject ?? 'other', subject ?? 'source']);
+                });
+                it('should record the kernel subjects in the scenario', () => {
+                    const stored = subject === '' || subject === '  ' ? 'source' : subject;
+                    check(scenarioSubjects).deep.equal([overload === 'multiple sources' ? 'entry' : stored ?? 'person',
+                        stored ?? 'other', stored ?? 'source']);
+                });
+            });
+        }
+    }
+    for (const subject of ['', '  ', '\t\r\n', '\u0085\u00a0']) {
+        describe(`when an entry has an explicit blank subject ${JSON.stringify(subject)}`, () => {
+            let wireSubjects: string[];
+            let scenarioSubjects: (string | undefined)[];
+            beforeEach(async () => {
+                const client = connected();
+                const memory = scenario();
+                const entries = [{ eventSourceId: 'source', event: fixtures.annotated('person'), subject }];
+                await client.sequence.appendMany(entries, { subject: 'shared' });
+                await memory.appendMany(entries, { subject: 'shared' });
+                wireSubjects = client.appendManyForEventSources.mock.calls[0][0].Events.map((entry: { Subject: string }) => entry.Subject);
+                scenarioSubjects = memory.appendedEvents.map(event => event.context.subject);
+            });
+            it('should not replace the blank entry subject on the wire', () => check(wireSubjects).deep.equal([subject]));
+            it('should record the event source subject in the scenario', () => check(scenarioSubjects).deep.equal(['source']));
+        });
+    }
+    for (const testCase of cases) {
+        describe(`when using routed scenario builders with ${testCase.name}`, () => {
+            let memory: EventScenario;
+            const route = { sourceType: 'people', streamType: 'personal', streamId: 'details' };
+            beforeEach(async () => {
+                memory = scenario();
+                await memory.given.forEventSource('source', route).events(testCase.event());
+                await memory.when.forEventSource('source', route).event(testCase.event());
+                await memory.when.forEventSource('source', route).events(testCase.event());
+            });
+            it('should record the kernel subject for seeds, single appends and batch appends', () => {
+                check(memory.appendedEvents.map(event => event.context.subject)).deep.equal(Array(3).fill(testCase.stored));
+            });
+            it('should retain the selected route on every append path', () => {
+                check(memory.appendedEvents.map(event => ({ sourceType: event.context.eventSourceType,
+                    streamType: event.context.eventStreamType, streamId: event.context.eventStreamId }))).deep.equal(Array(3).fill(route));
+            });
+        });
+    }
+    for (const subject of ['explicit', '', '  ']) {
+        describe(`when routed scenario builders override an annotation with ${JSON.stringify(subject)}`, () => {
+            let subjects: (string | undefined)[];
+            beforeEach(async () => {
+                const memory = scenario();
+                const options = { sourceType: 'people', streamType: 'personal', streamId: 'details', subject };
+                await memory.given.forEventSource('source', options).events(fixtures.annotated('person'));
+                await memory.when.forEventSource('source', options).event(fixtures.annotated('person'));
+                await memory.when.forEventSource('source', options).events(fixtures.annotated('person'));
+                subjects = memory.appendedEvents.map(event => event.context.subject);
+            });
+            it('should prefer the call subject and apply the kernel fallback on every path', () => {
+                check(subjects).deep.equal(Array(3).fill(subject.trim() ? subject : 'source'));
+            });
+        });
+    }
+    describe('when committing transactional single and batch appends', () => {
+        let subjects: string[];
+        beforeEach(async () => {
+            const client = connected();
+            await client.sequence.transactional.append('source', fixtures.annotated('person'));
+            await client.sequence.transactional.appendMany('source', [fixtures.concept('other'), fixtures.unannotated()]);
+            await client.unitOfWork.commit();
+            subjects = client.appendManyForEventSources.mock.calls[0][0].Events.map((entry: { Subject: string }) => entry.Subject);
+        });
+        it('should resolve each buffered event\'s annotation when the unit of work commits', () => check(subjects).deep.equal(['person', 'other', 'source']));
+    });
+    for (const testCase of cases) {
+        describe(`when seeding a scenario with ${testCase.name}`, () => {
+            let subject: string | undefined;
+            beforeEach(async () => {
+                const memory = scenario();
+                await memory.given.forEventSource('source').events(testCase.event());
+                subject = memory.appendedEvents[0].context.subject;
+            });
+            it('should record the kernel subject through the append boundary', () => should.equal(subject, testCase.stored));
+        });
+    }
+}

package/eventSequences/for_EventSequence/when_appending/with_subject_annotations.spec.ts

@@ -0,0 +1,34 @@
+// 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 { subject } from '../../../compliance/subject.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { subjectBehaviors } from './subject_behaviors.fixture.js';
+
+class PersonId extends ConceptAs<string> { static readonly valueType = String; }
+class PersonalData { constructor(readonly personId: string) {} }
+class DerivedPersonalData extends PersonalData {}
+class ConceptPersonalData { constructor(readonly personId: PersonId) {} }
+class UnannotatedData { id = 'not-the-subject'; }
+
+subject()(PersonalData.prototype, 'personId');
+field(String)(PersonalData.prototype, 'personId');
+eventType('subject-legacy-string')(PersonalData);
+eventType('subject-legacy-derived')(DerivedPersonalData);
+subject()(ConceptPersonalData.prototype, 'personId');
+field(PersonId)(ConceptPersonalData.prototype, 'personId');
+eventType('subject-legacy-concept')(ConceptPersonalData);
+field(String)(UnannotatedData.prototype, 'id');
+eventType('subject-legacy-unannotated')(UnannotatedData);
+
+describe('when appending subject annotations with legacy decorators', () => {
+    subjectBehaviors({
+        types: [PersonalData, DerivedPersonalData, ConceptPersonalData, UnannotatedData],
+        annotated: value => new PersonalData(value),
+        inherited: value => new DerivedPersonalData(value),
+        concept: value => new ConceptPersonalData(new PersonId(value)),
+        unannotated: () => new UnannotatedData()
+    });
+});

package/eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts

@@ -0,0 +1,38 @@
+// 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 { subject } from '../../../compliance/subject.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { subjectBehaviors } from './subject_behaviors.fixture.js';
+
+class PersonId extends ConceptAs<string> { static readonly valueType = String; }
+
+@eventType('subject-standard-string')
+class PersonalData {
+    @subject() @field(String) personId: string;
+    constructor(personId: string) { this.personId = personId; }
+}
+
+@eventType('subject-standard-derived')
+class DerivedPersonalData extends PersonalData {}
+
+@eventType('subject-standard-concept')
+class ConceptPersonalData {
+    @subject() @field(PersonId) personId: PersonId;
+    constructor(personId: string) { this.personId = new PersonId(personId); }
+}
+
+@eventType('subject-standard-unannotated')
+class UnannotatedData { @field(String) id = 'not-the-subject'; }
+
+describe('when appending subject annotations with standard decorators', () => {
+    subjectBehaviors({
+        types: [PersonalData, DerivedPersonalData, ConceptPersonalData, UnannotatedData],
+        annotated: value => new PersonalData(value),
+        inherited: value => new DerivedPersonalData(value),
+        concept: value => new ConceptPersonalData(value),
+        unannotated: () => new UnannotatedData()
+    });
+});

package/eventSequences/prepareBatchAppend.ts

@@ -8,6 +8,7 @@ import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { mergeTags } from '../events/mergeTags.js';
 import { identityProvider } from '../identity/index.js';
+import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import type { AppendOptions } from './AppendOptions.js';
 import type { EventForEventSourceId } from './EventForEventSourceId.js';
 import type { ConcurrencyScope } from './ConcurrencyScope.js';
@@ -56,7 +57,7 @@ export function prepareBatchAppend(
             EventType: { Id: eventType.id.value, Generation: eventType.generation.value, Tombstone: eventType.tombstone },
             Content: JsonSerializer.serialize(event), Tags: tags,
             Occurred: occurrenceTime === undefined ? undefined : { Value: occurrenceTime.toISOString() },
-            Subject: subject ?? appendOptions?.subject ?? eventSourceId
+            Subject: subject ?? appendOptions?.subject ?? resolveEventSubject(event) ?? eventSourceId
         };
     });
     return { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend };

package/eventSequences/prepareSingleAppend.ts

@@ -8,6 +8,7 @@ import { mergeTags } from '../events/mergeTags.js';
 import { identityProvider } from '../identity/index.js';
 import { causationManager, CausationType } from '../auditing/index.js';
 import { correlationIdManager } from '../correlation/index.js';
+import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import type { AppendOptions } from './AppendOptions.js';
 
 /** The production client and in-process scenario share the single-append serialization boundary. */
@@ -16,10 +17,11 @@ export function prepareSingleAppend(event: object, options?: AppendOptions) {
     const correlationId = options?.correlationId === undefined
         ? Guid.as(correlationIdManager.current.value)
         : Guid.as(options.correlationId);
+    const subject = options?.subject ?? resolveEventSubject(event);
     const content = JsonSerializer.serialize(event);
     const tags = mergeTags(getTagsFor(event.constructor as Function), options?.tags);
     const causationChain = causationManager.run(CausationType.appendEvent, { eventType: eventType.id.value },
         () => causationManager.getCurrentChain());
     const identity = identityProvider.getCurrent();
-    return { eventType, correlationId, content, tags, causationChain, identity };
+    return { eventType, correlationId, content, tags, causationChain, identity, subject };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.40.0",
+    "version": "6.41.1",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -173,7 +173,7 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:integration": "vitest run --config vitest.integration.config.ts",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/testing/EventScenario.batches.spec.ts

@@ -265,7 +265,7 @@ describe('when appending batches against committed kernel fixtures', () => {
             error => { (error instanceof UnsupportedEventSequenceOperation).should.be.true; }
         );
         await first;
-        for (const options of [{ subject: 'bad subject' }, { tags: ['invalid|tag'] },
+        for (const options of [{ subject: 42 as unknown as string }, { tags: ['invalid|tag'] },
             { concurrencyScope: {} as never }]) {
             await scenario.appendMany('B', [new OracleEventRecorded('second', false)], options).then(
                 () => { throw new Error('Unproven metadata accepted'); },
@@ -450,7 +450,7 @@ describe('when appending batches against committed kernel fixtures', () => {
             ['appendMany.correlationId', () => scenario.appendMany('B', [event()], { correlationId: 'bad-guid' })],
             ['appendMany.entry', () => scenario.appendMany([entry({ unknown: 'value' })])],
             ['appendMany.sourceType', () => scenario.appendMany([entry({ eventSourceType: 'bad source' })])],
-            ['appendMany.subject', () => scenario.appendMany([entry({ subject: '' })], { subject: 'shared' })],
+            ['appendMany.subject', () => scenario.appendMany([entry({ subject: 42 })], { subject: 'shared' })],
             ['appendMany.streamType', () => scenario.appendMany([entry({ eventStreamType: 'bad stream' })])],
             ['appendMany.streamId', () => scenario.appendMany([entry({ eventStreamId: 'bad stream' })])],
             ['appendMany.event', () => scenario.appendMany('B', [new UnregisteredRecorded()])],

package/testing/EventScenario.fixtures.spec.ts

@@ -219,11 +219,11 @@ describe('when appending against committed kernel event fixtures', () => {
     it('should reject prototype getters and non-enumerable append metadata without mutation', async () => {
         const scenario = makeScenario();
         class OptionsWithGetters {
-            get subject() { return 'different-subject'; }
+            get occurred() { return new Date(); }
             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 });
+        const hidden = Object.defineProperty({}, 'occurred', { value: new Date(), 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);

package/testing/EventScenario.rejections.spec.ts

@@ -233,9 +233,9 @@ describe('when the fixture-bounded event sequence encounters unproven operations
         await rejects(() => subject.append('A', new Recorded(), { correlationId: '00000000-0000-0000-0000-000000000001' }), 'append.options');
         clean(subject);
     });
-    it('should reject plain subject options', async () => {
+    it('should reject non-string subject options', async () => {
         const subject = scenario();
-        await rejects(() => subject.append('A', new Recorded(), { subject: 'other' }), 'append.options');
+        await rejects(() => subject.append('A', new Recorded(), { subject: 42 as unknown as string }), 'append.subject');
         clean(subject);
     });
     it('should reject empty source/type-read event types', async () => {

package/testing/EventScenario.ts

@@ -149,7 +149,7 @@ export class EventScenario {
         }
         const sequence = new InProcessEventSequence(options, eventTypes, constraints);
         this.eventSequence = sequence;
-        registerScenarioSeed(this, (source, events) => sequence.seed(source, events));
+        registerScenarioSeed(this, (source, events, options) => sequence.seed(source, events, options));
         this.given = new EventScenarioGivenBuilder(this);
         this.when = new EventScenarioWhenBuilder(this);
     }

package/testing/EventScenarioGiven.ts

@@ -1,13 +1,14 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 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) {}
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string, private readonly _options?: AppendOptions) {}
     async events(...events: object[]): Promise<void> {
-        await seedScenario(this._scenario, this._id, events);
+        await seedScenario(this._scenario, this._id, events, this._options);
     }
 }

package/testing/EventScenarioGivenBuilder.ts

@@ -1,11 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 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); }
+    forEventSource(id: string, options?: AppendOptions): EventScenarioGiven { return new EventScenarioGiven(this._scenario, id, options); }
 }

package/testing/EventScenarioSeed.ts

@@ -1,17 +1,18 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 
-const seeders = new WeakMap<EventScenario, (source: string, events: object[]) => Promise<void>>();
+const seeders = new WeakMap<EventScenario, (source: string, events: object[], options?: AppendOptions) => Promise<void>>();
 
 /** Internal builder wiring; not exported by the testing package. */
-export function registerScenarioSeed(scenario: EventScenario, seed: (source: string, events: object[]) => Promise<void>): void {
+export function registerScenarioSeed(scenario: EventScenario, seed: (source: string, events: object[], options?: AppendOptions) => Promise<void>): void {
     seeders.set(scenario, seed);
 }
 
-export function seedScenario(scenario: EventScenario, source: string, events: object[]): Promise<void> {
+export function seedScenario(scenario: EventScenario, source: string, events: object[], options?: AppendOptions): Promise<void> {
     const seed = seeders.get(scenario);
     if (!seed) throw new Error('EventScenario setup requires a constructed scenario.');
-    return seed(source, events);
+    return seed(source, events, options);
 }

package/testing/EventScenarioWhen.ts

@@ -1,14 +1,15 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { AppendResult } from '../eventSequences/AppendResult.js';
 import type { EventScenario } from './EventScenario.js';
 
 /** A single act-phase append; the plural form is reserved for atomic batches. */
 export class EventScenarioWhen {
-    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
-    async event(event: object): Promise<AppendResult> { return this._scenario.append(this._id, event); }
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string, private readonly _options?: AppendOptions) {}
+    async event(event: object): Promise<AppendResult> { return this._scenario.append(this._id, event, this._options); }
     async events(...events: object[]): Promise<readonly AppendResult[]> {
-        return this._scenario.appendMany(this._id, events);
+        return this._scenario.appendMany(this._id, events, this._options);
     }
 }

package/testing/EventScenarioWhenBuilder.ts

@@ -1,11 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 import { EventScenarioWhen } from './EventScenarioWhen.js';
 
 /** Selects the source for an act-phase append. */
 export class EventScenarioWhenBuilder {
     constructor(private readonly _scenario: EventScenario) {}
-    forEventSource(id: string): EventScenarioWhen { return new EventScenarioWhen(this._scenario, id); }
+    forEventSource(id: string, options?: AppendOptions): EventScenarioWhen { return new EventScenarioWhen(this._scenario, id, options); }
 }