@cratis/chronicle 6.41.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.41.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/InProcessEventSequence.ts

@@ -37,6 +37,11 @@ import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOpe
 // JS trim() omits U+0085, which the kernel trims. Reject unproven non-ASCII whitespace and controls.
 const unprovenFilterCharacters = /[\u007f-\u009f]|(?=[^\x00-\x7f])\p{White_Space}/u;
 
+function resolveStoredSubject(subject: string | undefined, eventSourceId: string): string {
+    // Match the kernel's string.IsNullOrWhiteSpace, including U+0085 but not U+FEFF.
+    return subject && !/^\p{White_Space}*$/u.test(subject) ? subject : eventSourceId;
+}
+
 function matchesConstrainedValue(value: unknown, content: unknown): boolean {
     // Use production serialization for concepts, not their wrapper object's runtime type.
     // Keep rejecting other unproven conversions, such as a Date assigned to a string field.
@@ -168,13 +173,13 @@ export class InProcessEventSequence implements IEventSequence {
         try {
             if (!event || typeof event !== 'object') throw this.unsupported('append.event', this.id.value, 'Only registered event instances are supported.');
             if (!/^[A-Za-z0-9_-]+$/.test(eventSourceId)) throw this.unsupported('append.source', eventSourceId, 'Only simple source identifiers are fixture-backed.');
-            const route = singleAppendRoute(options, event.constructor.name, (operation, artifact, reason) => this.unsupported(operation, artifact, reason));
+            const route = singleAppendRoute(options, event.constructor.name, (operation, artifact, reason) => this.unsupported(operation, artifact, reason), true);
             const metadata = this._catalog.get(event.constructor);
             if (!metadata) throw this.unsupported('append.event', event.constructor.name, 'Event is not in the selected, validated catalog.');
             let prepared: ReturnType<typeof prepareSingleAppend>;
             let content: Record<string, unknown>;
             try {
-                prepared = prepareSingleAppend(event, this._correlationId ? { correlationId: this._correlationId() } : undefined);
+                prepared = prepareSingleAppend(event, { subject: options?.subject, correlationId: this._correlationId?.() });
                 content = this.checkedContent(event, prepared.content, 'append.content',
                     'Content differs from the event schema; null, missing and extra values are not proven.');
             } catch (error) {
@@ -207,7 +212,7 @@ export class InProcessEventSequence implements IEventSequence {
                     eventStore: this._store, namespace: this._namespace,
                     sequenceNumber: sequenceNumber.value, eventSourceId,
                     eventSourceType: route.sourceType, eventStreamType: route.streamType, eventStreamId: route.streamId,
-                    subject: eventSourceId, hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
+                    subject: resolveStoredSubject(prepared.subject, eventSourceId), hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
                     eventType: prepared.eventType, occurred, correlationId: prepared.correlationId.toString(),
                     causation: prepared.causationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
                     tags: prepared.tags.map(tag => new Tag(tag))
@@ -254,6 +259,9 @@ export class InProcessEventSequence implements IEventSequence {
                 }
                 const individual = entry as EventForEventSourceId;
                 if (individual.occurred !== undefined) this.checkedDate(individual.occurred, 'appendMany.occurred');
+                if (individual.subject !== undefined && individual.subject !== null && typeof individual.subject !== 'string') {
+                    throw this.unsupported('appendMany.subject', this.id.value, 'Subject must be a string.');
+                }
                 const tags = individual.tags;
                 if (tags && (!Array.isArray(tags) || tags.some(tag => typeof tag !== 'string'))) {
                     throw this.unsupported('appendMany.tags', this.id.value, 'Only plain string tags are fixture-backed.');
@@ -288,8 +296,8 @@ export class InProcessEventSequence implements IEventSequence {
                 this.validateSource(eventSourceId, 'appendMany.source');
                 const wire = eventsToAppend[index];
                 for (const [name, value] of Object.entries({ sourceType: wire.EventSourceType, streamType: wire.EventStreamType,
-                    streamId: wire.EventStreamId, subject: wire.Subject })) {
-                    const identifiers = name === 'subject' ? /^[A-Za-z0-9_-]+$/ : /^[A-Za-z0-9_-]*$/;
+                    streamId: wire.EventStreamId })) {
+                    const identifiers = /^[A-Za-z0-9_-]*$/;
                     if (value !== undefined && (typeof value !== 'string' || !identifiers.test(value))) {
                         throw this.unsupported(`appendMany.${name}`, String(value), 'Only simple metadata identifiers are fixture-backed.');
                     }
@@ -307,7 +315,7 @@ export class InProcessEventSequence implements IEventSequence {
                 const stored: AppendedEvent = { eventType, content, context: {
                     eventStore: this._store, namespace: this._namespace, sequenceNumber: sequenceNumber.value, eventSourceId,
                     eventSourceType: wire.EventSourceType || 'Default', eventStreamType: wire.EventStreamType || 'All',
-                    eventStreamId: wire.EventStreamId || 'Default', subject: wire.Subject, hash, causedBy: identity,
+                    eventStreamId: wire.EventStreamId || 'Default', subject: resolveStoredSubject(wire.Subject, eventSourceId), hash, causedBy: identity,
                     observationState: EventObservationState.Initial, eventType, occurred, correlationId: correlationId.toString(),
                     causation: batchCausationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
                     tags: wire.Tags.map(tag => new Tag(tag))
@@ -408,6 +416,9 @@ export class InProcessEventSequence implements IEventSequence {
             options.concurrencyScope !== undefined || options.concurrencyScopes !== undefined || options.eventSourceId !== undefined) {
             throw this.unsupported('appendMany.options', this.id.value, 'Concurrency and unrecognized metadata are not fixture-backed.');
         }
+        if (options.subject !== undefined && options.subject !== null && typeof options.subject !== 'string') {
+            throw this.unsupported('appendMany.subject', this.id.value, 'Subject must be a string.');
+        }
         if (options.tags && (!Array.isArray(options.tags) || options.tags.some(tag => typeof tag !== 'string'))) {
             throw this.unsupported('appendMany.tags', this.id.value, 'Only plain string tags are fixture-backed.');
         }

package/testing/ReadModelScenario.spec.ts

@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest';
 import { ConceptAs, field, Guid } from '@cratis/fundamentals';
 import type { Constructor } from '@cratis/fundamentals';
 import { pii } from '../compliance/pii.js';
+import { subject } from '../compliance/subject.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import type { EventContext } from '../events/EventContext.js';
 import { fromEvent } from '../projections/modelBound/fromEvent.js';
@@ -219,6 +220,36 @@ describe('ReadModelScenario', () => {
         expect(await scenario.instance).toMatchObject({ subject: 'source-a' });
     });
 
+    it('maps a seeded event subject annotation to the projection Subject context', async () => {
+        class PersonalData {
+            @field(String) personId = 'person-a';
+        }
+        subject()(PersonalData.prototype, 'personId');
+        eventType('scenario-personal-data')(PersonalData);
+        class SubjectState { @field(String) id = ''; @field(String) subject = ''; }
+        fromEvent(PersonalData)(SubjectState);
+        setFromContext(PersonalData, 'subject')(SubjectState.prototype, 'subject');
+        const scenario = new ReadModelScenario(SubjectState, { ...artifacts, eventTypes: [PersonalData] });
+        scenario.given.forEventSource('source-a').events(new PersonalData());
+        expect(await scenario.instance).toMatchObject({ subject: 'person-a' });
+    });
+
+    it.each([undefined, null, '', ' \t\n', '\u0085\u2003'])('defaults an annotated subject %j to the event source', async value => {
+        class PersonalData {
+            // Keep null out of serialized content while exercising subject resolution.
+            get personId(): string | null | undefined { return value; }
+        }
+        field(String)(PersonalData.prototype, 'personId');
+        subject()(PersonalData.prototype, 'personId');
+        eventType('scenario-empty-subject')(PersonalData);
+        class SubjectState { @field(String) id = ''; @field(String) subject = ''; }
+        fromEvent(PersonalData)(SubjectState);
+        setFromContext(PersonalData, 'subject')(SubjectState.prototype, 'subject');
+        const scenario = new ReadModelScenario(SubjectState, { ...artifacts, eventTypes: [PersonalData] });
+        scenario.given.forEventSource('source-a').events(new PersonalData());
+        expect(await scenario.instance).toMatchObject({ subject: 'source-a' });
+    });
+
     it('defaults a projection Hash and CausedBy mapping to kernel sentinels when the seed omits them', async () => {
         class ContextDefaults { @field(String) id = ''; @field(String) hash = ''; @field(String) causedByName = ''; }
         setFromContext(ItemAdded, 'hash')(ContextDefaults.prototype, 'hash');

package/testing/ReadModelScenario.ts

@@ -7,6 +7,7 @@ import type { Constructor } from '@cratis/fundamentals';
 import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
 import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import { getFromEventMetadata } from '../projections/modelBound/fromEvent.js';
 import { getRemovedWithClassMetadata } from '../projections/modelBound/removedWith.js';
 import { getRemovedWithJoinClassMetadata } from '../projections/modelBound/removedWithJoin.js';
@@ -138,11 +139,14 @@ export class ReadModelScenario<TReadModel extends object> {
             if (!metadata) throw new Error(`Event '${event.constructor.name}' has no @eventType metadata.`);
             // The kernel delivers JSON objects, not instances of decorated event classes.
             const content: unknown = JSON.parse(JsonSerializer.serialize(event));
+            const subject = resolveEventSubject(event);
             this._events.push({
                 sourceId: id,
                 content,
                 context: {
                     eventSourceId: id,
+                    // Match the kernel's string.IsNullOrWhiteSpace, including U+0085 but not U+FEFF.
+                    subject: subject && !/^\p{White_Space}*$/u.test(subject) ? subject : id,
                     eventSourceType: 'Default',
                     eventStreamType: 'All',
                     eventStreamId: 'Default',

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

@@ -83,7 +83,7 @@ describe('when a scoped append uses unsupported routes or metadata', () => {
                     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' },
+            for (const options of [{ tags: [] }, { 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');
             }

package/testing/for_ReadModelScenario/when_seeding_with_options/with_route_validation.spec.ts

@@ -25,7 +25,7 @@ describe('when read-model setup receives route options', () => {
     it('should reuse single-append rejection messages without collecting unsupported input', async () => {
         const scenario = create();
         const events = createEvents();
-        for (const value of [{ sourceType: ' ' }, { streamType: null }, { streamId: 1 }, { tags: [] }, { arbitrary: true }, null, []]) {
+        for (const value of [{ sourceType: ' ' }, { streamType: null }, { streamId: 1 }, null, []]) {
             const options = value as AppendOptions;
             const error = await rejection(() => events.append('A', new Claim('Other'), options));
             (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(error.message);
@@ -33,6 +33,16 @@ describe('when read-model setup receives route options', () => {
         ((await scenario.instance) === null).should.be.true;
     });
 
+    it('should list only supported seed options without collecting unsupported input', async () => {
+        const scenario = create();
+        for (const value of [{ tags: [] }, { arbitrary: true }, { subject: 'person-a' }]) {
+            const options = value as AppendOptions;
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(
+                'UnsupportedEventSequenceOperation: append.options (Claim): Only sourceType, streamType, streamId options are supported for single append. Use a kernel-backed test.');
+        }
+        ((await scenario.instance) === null).should.be.true;
+    });
+
     it('should retain the unproven routed read-model boundary instead of simulating projection routing', async () => {
         const scenario = create();
         (() => scenario.given.forEventSource('A', route).events(new Claim('Other'))).should.throw(UnsupportedProjectionOperation, 'routed events');

package/testing/singleAppendRoute.spec.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { singleAppendRoute } from './singleAppendRoute.js';
+
+chai.should();
+
+describe('when single-append routing rejects unsupported options', () => {
+    it('should list only routing options when subject is not allowed', () => {
+        (() => singleAppendRoute({ subject: 'person-a' }, 'SeededEvent'))
+            .should.throw('Only sourceType, streamType, streamId options are supported for single append.');
+    });
+
+    it('should include subject in the allowed options for single append', () => {
+        (() => singleAppendRoute({ tags: [] }, 'AppendedEvent', undefined, true))
+            .should.throw('Only sourceType, streamType, streamId, subject options are supported for single append.');
+    });
+});