@cratis/chronicle 6.48.0 → 6.50.0

package/eventSources/for_EventSources/when_discovering_and_registering.spec.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConcurrencyDimensions, eventSource, eventStream, EventSources } from '../index.js';
+import { DuplicateEventSourceName } from '../DuplicateEventSourceName.js';
+import { DuplicateEventStreamName } from '../DuplicateEventStreamName.js';
+import { UnknownEventSource } from '../UnknownEventSource.js';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+
+const should = chai.should();
+
+@eventSource({ description: 'An account', concurrency: ConcurrencyDimensions.eventSourceId })
+@eventStream('Transactions', { description: 'Money moves', concurrency: ConcurrencyDimensions.eventSourceId | ConcurrencyDimensions.eventStreamType })
+@eventStream('Statements')
+class AccountEventSource {}
+
+@eventSource({ name: 'Same' }) class First {}
+@eventSource({ name: 'Same' }) class Second {}
+@eventSource({ name: 'Dup' })
+@eventStream('S') @eventStream('S')
+class DuplicateStreams {}
+
+function artifacts(...types: Constructor[]): IClientArtifactsProvider {
+    return { eventSources: types } as unknown as IClientArtifactsProvider;
+}
+
+function create(...types: Constructor[]) {
+    const registerEventSources = vi.fn().mockResolvedValue({ IsSuccess: true, ValidationResults: [], ExceptionMessages: [] });
+    const connection = { eventSources: { registerEventSources } } as unknown as ChronicleConnection;
+    return { sources: new EventSources('store', connection, artifacts(...types)), registerEventSources };
+}
+
+describe('when discovering a decorated event source', () => {
+    let sources: EventSources;
+    beforeEach(async () => {
+        ({ sources } = create(AccountEventSource));
+        await sources.discover();
+    });
+    it('should default the name by trimming the EventSource suffix', () => sources.all[0].name.should.equal('Account'));
+    it('should keep description and concurrency', () => {
+        sources.all[0].description.should.equal('An account');
+        sources.all[0].concurrency.should.equal(ConcurrencyDimensions.eventSourceId);
+    });
+    it('should keep streams in declaration order with their own dimensions', () => {
+        sources.all[0].streams.map(_ => _.name).should.deep.equal(['Transactions', 'Statements']);
+        sources.all[0].streams[0].concurrency.should.equal(5);
+        sources.all[0].streams[1].concurrency.should.equal(0);
+    });
+    it('should resolve by class and by name', () => {
+        sources.getFor(AccountEventSource).should.equal(sources.getFor('Account'));
+    });
+    it('should reject an unknown source', () => {
+        (() => sources.getFor('Nope')).should.throw(UnknownEventSource);
+    });
+});
+
+describe('when discovering duplicate names', () => {
+    it('should reject duplicate source names', async () => {
+        const { sources } = create(First, Second);
+        let error: unknown;
+        await sources.discover().catch(e => error = e);
+        (error as Error).should.be.instanceOf(DuplicateEventSourceName);
+    });
+    it('should reject duplicate stream names', async () => {
+        const { sources } = create(DuplicateStreams);
+        let error: unknown;
+        await sources.discover().catch(e => error = e);
+        (error as Error).should.be.instanceOf(DuplicateEventStreamName);
+    });
+});
+
+describe('when registering', () => {
+    it('should send the definitions with client ownership and wire dimension flags', async () => {
+        const { sources, registerEventSources } = create(AccountEventSource);
+        await sources.discover();
+        await sources.register();
+        const request = registerEventSources.mock.calls[0][0];
+        request.EventStore.should.equal('store');
+        request.Sources.should.have.length(1);
+        request.Sources[0].Name.should.equal('Account');
+        request.Sources[0].Owner.should.equal(1);
+        request.Sources[0].Concurrency.should.equal(1);
+        request.Sources[0].Streams[0].should.deep.equal({ Name: 'Transactions', Description: 'Money moves', Concurrency: 5 });
+    });
+    it('should not call the kernel when there are no definitions', async () => {
+        const { sources, registerEventSources } = create();
+        await sources.discover();
+        await sources.register();
+        should.equal(registerEventSources.mock.calls.length, 0);
+    });
+});

package/eventSources/index.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.
+
+export { ConcurrencyDimensions } from './ConcurrencyDimensions.js';
+export type { ConcurrencyDimensionFlags } from './ConcurrencyDimensions.js';
+export type { EventSourceDefinition } from './EventSourceDefinition.js';
+export type { EventStreamDefinition } from './EventStreamDefinition.js';
+export { eventSource, eventStream, getEventSourceMetadata, getEventStreamsFor } from './eventSource.js';
+export type { EventSourceOptions, EventStreamOptions, EventSourceMetadata, EventStreamMetadata } from './eventSource.js';
+export type { IEventSources } from './IEventSources.js';
+export { EventSources } from './EventSources.js';
+export { ResolvedEventRouting } from './ResolvedEventRouting.js';
+export type { ExplicitRouting } from './ResolvedEventRouting.js';
+export { UnknownEventSource } from './UnknownEventSource.js';
+export { DuplicateEventSourceName } from './DuplicateEventSourceName.js';
+export { DuplicateEventStreamName } from './DuplicateEventStreamName.js';
+export { EventStreamDoesNotBelongToEventSource } from './EventStreamDoesNotBelongToEventSource.js';
+export { EventRoutingContradictsEventSource } from './EventRoutingContradictsEventSource.js';
+export { EventStreamRequiresEventSource } from './EventStreamRequiresEventSource.js';

package/events/EventContext.ts

@@ -4,6 +4,7 @@
 import { EventType } from './EventType.js';
 import { CausationEntry } from './CausationEntry.js';
 import { Tag } from './Tag.js';
+import type { NamedTag } from './NamedTag.js';
 import type { Identity } from '../identity/Identity.js';
 
 /**
@@ -31,6 +32,12 @@ export interface EventContext {
     /** The stream identifier returned by the kernel. */
     readonly eventStreamId?: string;
 
+    /**
+     * The registered event source definition the event was appended through.
+     * Undefined for events appended without a definition, including events stored before event sources existed.
+     */
+    readonly eventSource?: string;
+
     /** The compliance subject returned by the kernel. */
     readonly subject?: string;
 
@@ -57,4 +64,11 @@ export interface EventContext {
 
     /** The tags the event carries. */
     readonly tags: ReadonlyArray<Tag>;
+
+    /**
+     * The structured named tags the event carries, in the order the kernel stored them.
+     * Always present on events read from or delivered by the kernel (empty when the event has none);
+     * optional so that contexts constructed by hand remain valid.
+     */
+    readonly namedTags?: ReadonlyArray<NamedTag>;
 }

package/events/InvalidNamedTag.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.
+
+/**
+ * The error that is thrown when a named tag has a blank name or a non-string value, or a named tag
+ * collection contains an entry that is not a named tag. Mirrors the .NET client's `InvalidNamedTag`.
+ */
+export class InvalidNamedTag extends Error {
+    constructor() {
+        super('Named tags require a nonblank name and a non-null value; named tag collections cannot contain null elements.');
+        this.name = 'InvalidNamedTag';
+    }
+}

package/events/NamedTag.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InvalidNamedTag } from './InvalidNamedTag.js';
+
+// Matches .NET string.IsNullOrWhiteSpace, which also treats U+0085 and other Unicode white space as blank.
+const blank = /^\p{White_Space}*$/u;
+
+/**
+ * Associates a name with an exact, opaque event tag value. Names and values are compared exactly
+ * (ordinal and case-sensitive); one name may carry several values on the same event.
+ * Mirrors the .NET client's `NamedTag`.
+ */
+export class NamedTag {
+    /** The name of the tag. Never blank. */
+    readonly name: string;
+
+    /** The exact, opaque value of the tag. May be empty. */
+    readonly value: string;
+
+    /**
+     * Initializes a new instance of {@link NamedTag}.
+     * @param name - The name. Must be a nonblank string.
+     * @param value - The opaque value. Must be a string; the empty string is allowed.
+     * @throws {@link InvalidNamedTag} when the name is blank or not a string, or the value is not a string.
+     */
+    constructor(name: string, value: string) {
+        if (typeof name !== 'string' || blank.test(name) || typeof value !== 'string') {
+            throw new InvalidNamedTag();
+        }
+        this.name = name;
+        this.value = value;
+        Object.freeze(this);
+    }
+
+    /**
+     * Determines whether this tag has the same name and value as another, compared exactly.
+     * @param other - The tag to compare with.
+     * @returns True when both name and value are equal.
+     */
+    equals(other: NamedTag): boolean {
+        return other instanceof NamedTag && other.name === this.name && other.value === this.value;
+    }
+}

package/events/WireEventContext.ts

@@ -7,6 +7,8 @@ import type { AppendedEventResponse } from '@cratis/chronicle.contracts';
 export type WireEventContext = Omit<NonNullable<AppendedEventResponse['Context']>, 'ObservationState'> & {
     /** Numeric wire value shared by the generated observation-state enums. */
     ObservationState: number;
+    /** The registered event source name; empty or absent when the event was not appended through a definition. */
+    EventSource?: string;
     /** Store metadata is carried by observer deliveries, but not every read response. */
     EventStore?: string;
     /** Namespace metadata is carried by observer deliveries, but not every read response. */

package/events/for_EventContext/with_event_source.spec.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it, chai } from 'vitest';
+import { toClientEventContext } from '../toClientEventContext.js';
+import type { WireEventContext } from '../WireEventContext.js';
+
+const should = chai.should();
+const wire = (extra: Partial<WireEventContext>): WireEventContext => ({
+    EventSourceId: 's', SequenceNumber: 1n, ObservationState: 0, Tags: [], Causation: [],
+    EventType: { Id: 't', Generation: 1, Tombstone: false }, Occurred: { Value: '2025-01-01T00:00:00.000Z' }, ...extra
+} as unknown as WireEventContext);
+
+describe('when converting a kernel event context', () => {
+    it('should carry the registered event source', () => {
+        toClientEventContext(wire({ EventSource: 'Account' })).eventSource!.should.equal('Account');
+    });
+    it('should leave the source unset when the event was not appended through a definition', () => {
+        should.equal(toClientEventContext(wire({ EventSource: '' })).eventSource, undefined);
+        should.equal(toClientEventContext(wire({})).eventSource, undefined);
+    });
+});

package/events/for_NamedTag/when_constructing/with_invalid_values.spec.ts

@@ -0,0 +1,17 @@
+// 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 { InvalidNamedTag } from '../../InvalidNamedTag.js';
+import { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when constructing a named tag with invalid values', () => {
+    it('should reject an empty name', () => (() => new NamedTag('', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a whitespace name', () => (() => new NamedTag(' \t', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a name of only next-line characters like .NET', () => (() => new NamedTag('\u0085', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a missing name', () => (() => new NamedTag(undefined as unknown as string, 'value')).should.throw(InvalidNamedTag));
+    it('should reject a null value', () => (() => new NamedTag('name', null as unknown as string)).should.throw(InvalidNamedTag));
+    it('should reject a non-string value', () => (() => new NamedTag('name', 42 as unknown as string)).should.throw(InvalidNamedTag));
+});

package/events/for_NamedTag/when_constructing/with_valid_values.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 { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when constructing a named tag with a name and an empty value', () => {
+    const tag = new NamedTag('import-batch', '');
+    it('should keep the name exactly', () => tag.name.should.equal('import-batch'));
+    it('should keep the empty value', () => tag.value.should.equal(''));
+    it('should be immutable', () => Object.isFrozen(tag).should.be.true);
+});
+
+describe('when comparing named tags', () => {
+    it('should treat the same name and value as equal', () => new NamedTag('a', 'B').equals(new NamedTag('a', 'B')).should.be.true);
+    it('should compare values case-sensitively', () => new NamedTag('a', 'B').equals(new NamedTag('a', 'b')).should.be.false);
+});

package/events/for_mergeNamedTags/when_merging/with_event_and_call_tags.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { mergeNamedTags } from '../../mergeNamedTags.js';
+import { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when merging event and call named tags', () => {
+    let result: NamedTag[];
+    beforeEach(() => {
+        result = mergeNamedTags(
+            [new NamedTag('side', 'debit'), new NamedTag('transfer', 't-1')],
+            [new NamedTag('transfer', 't-1'), new NamedTag('transfer', 'T-1'), new NamedTag('side', 'credit')]);
+    });
+    it('should keep the first occurrence of each exact pair in order, including several values per name', () =>
+        result.map(tag => [tag.name, tag.value]).should.deep.equal([
+            ['side', 'debit'], ['transfer', 't-1'], ['transfer', 'T-1'], ['side', 'credit']
+        ]));
+});
+
+describe('when merging plain named tag objects', () => {
+    let result: NamedTag[];
+    beforeEach(() => { result = mergeNamedTags([{ name: 'channel', value: 'web' } as NamedTag]); });
+    it('should return validated named tag instances', () => result[0].should.be.instanceOf(NamedTag));
+});
+
+describe('when merging no named tags', () => {
+    it('should return an empty list', () => mergeNamedTags(undefined, null, []).should.deep.equal([]));
+});

package/events/for_mergeNamedTags/when_merging/with_invalid_entries.spec.ts

@@ -0,0 +1,17 @@
+// 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 { InvalidNamedTag } from '../../InvalidNamedTag.js';
+import { mergeNamedTags } from '../../mergeNamedTags.js';
+import type { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when merging named tags with invalid entries', () => {
+    it('should reject a null element', () => (() => mergeNamedTags([null as unknown as NamedTag])).should.throw(InvalidNamedTag));
+    it('should reject a plain object with a blank name', () =>
+        (() => mergeNamedTags([{ name: ' ', value: 'x' } as NamedTag])).should.throw(InvalidNamedTag));
+    it('should reject a string instead of a collection', () =>
+        (() => mergeNamedTags('name' as unknown as NamedTag[])).should.throw(InvalidNamedTag));
+});

package/events/for_toClientEventContext/when_converting_named_tags.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import type { EventContext } from '../EventContext.js';
+import { NamedTag } from '../NamedTag.js';
+import { toClientEventContext } from '../toClientEventContext.js';
+import type { WireEventContext } from '../WireEventContext.js';
+
+chai.should();
+
+function wireContext(namedTags?: { Name: string; Value: string }[]): WireEventContext {
+    return {
+        EventSourceId: 'source', SequenceNumber: 1n, EventSourceType: 'Default', EventStreamType: 'All', EventStreamId: 'Default',
+        EventType: { Id: 'type', Generation: 1, Tombstone: false }, Occurred: { Value: '2025-01-01T00:00:00.000Z' },
+        CorrelationId: undefined, Causation: [], CausedBy: undefined, Tags: [], Hash: '', ObservationState: 1, Subject: 'source',
+        NamedTags: namedTags
+    } as unknown as WireEventContext;
+}
+
+describe('when converting a delivered context with named tags', () => {
+    let context: EventContext;
+    beforeEach(() => { context = toClientEventContext(wireContext([{ Name: 'batch', Value: 'b-1' }, { Name: 'batch', Value: '' }])); });
+    it('should expose every named tag in delivered order', () =>
+        context.namedTags!.map(tag => [tag.name, tag.value]).should.deep.equal([['batch', 'b-1'], ['batch', '']]));
+    it('should expose named tag instances', () => context.namedTags![0].should.be.instanceOf(NamedTag));
+});
+
+describe('when converting a delivered context without named tags', () => {
+    it('should expose an empty list', () => toClientEventContext(wireContext()).namedTags!.should.deep.equal([]));
+});

package/events/index.ts

@@ -21,5 +21,8 @@ export { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorato
 export { eventSourceType, getEventSourceTypeFor } from './eventSourceTypeDecorator.js';
 export { eventStreamType, getEventStreamTypeFor } from './eventStreamTypeDecorator.js';
 export { mergeTags } from './mergeTags.js';
+export { NamedTag } from './NamedTag.js';
+export { InvalidNamedTag } from './InvalidNamedTag.js';
+export { mergeNamedTags } from './mergeNamedTags.js';
 export * from './constraints/index.js';
 export * from './migrations/index.js';

package/events/mergeNamedTags.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { InvalidNamedTag } from './InvalidNamedTag.js';
+import { NamedTag } from './NamedTag.js';
+
+/**
+ * Validates and merges structured named tags - for example the tags carried by an individual event and
+ * the tags supplied for a whole append call - into one distinct list. The first occurrence of each exact
+ * (ordinal, case-sensitive) name and value pair is kept, in order. Mirrors the .NET client's
+ * `NamedTagConverters.Merge`.
+ * @param sources - The named tag sources to merge, in precedence order. An undefined or null source contributes nothing.
+ * @returns The distinct, validated named tags.
+ * @throws {@link InvalidNamedTag} when a source is not iterable, contains an entry that is not an object,
+ * or contains a tag with a blank name or a non-string value.
+ */
+export function mergeNamedTags(...sources: ReadonlyArray<Iterable<NamedTag> | undefined | null>): NamedTag[] {
+    const seen = new Set<string>();
+    const merged: NamedTag[] = [];
+    for (const source of sources) {
+        if (source === undefined || source === null) continue;
+        if (typeof source !== 'object' || typeof (source as Iterable<NamedTag>)[Symbol.iterator] !== 'function') {
+            throw new InvalidNamedTag();
+        }
+        for (const entry of source as Iterable<unknown>) {
+            if (entry === null || typeof entry !== 'object') throw new InvalidNamedTag();
+            // Reconstruct so plain { name, value } objects are validated exactly like NamedTag instances.
+            const tag = entry instanceof NamedTag ? entry
+                : new NamedTag(Reflect.get(entry, 'name') as string, Reflect.get(entry, 'value') as string);
+            const key = JSON.stringify([tag.name, tag.value]);
+            if (seen.has(key)) continue;
+            seen.add(key);
+            merged.push(tag);
+        }
+    }
+    return merged;
+}

package/events/toClientEventContext.ts

@@ -8,6 +8,7 @@ import { EventType } from './EventType.js';
 import { EventTypeGeneration } from './EventTypeGeneration.js';
 import { EventTypeId } from './EventTypeId.js';
 import { Tag } from './Tag.js';
+import { NamedTag } from './NamedTag.js';
 import type { WireEventContext } from './WireEventContext.js';
 
 /** Converts kernel metadata identically for reads, reactors, and reducers. */
@@ -20,6 +21,7 @@ export function toClientEventContext(context: WireEventContext): EventContext {
         eventSourceType: context.EventSourceType,
         eventStreamType: context.EventStreamType,
         eventStreamId: context.EventStreamId,
+        eventSource: context.EventSource ? context.EventSource : undefined,
         subject: context.Subject,
         hash: context.Hash,
         observationState: context.ObservationState,
@@ -36,7 +38,8 @@ export function toClientEventContext(context: WireEventContext): EventContext {
             occurred: causation.Occurred ? new Date(causation.Occurred.Value) : undefined,
             properties: { ...causation.Properties }
         })),
-        tags: (context.Tags ?? []).map(value => new Tag(value))
+        tags: (context.Tags ?? []).map(value => new Tag(value)),
+        namedTags: (context.NamedTags ?? []).map(tag => new NamedTag(tag.Name, tag.Value))
     };
 }
 

package/for_EventStore/when_implementing_a_legacy_event_store.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 type { IEventStore } from '../IEventStore.js';
+
+const should = chai.should();
+
+/** An implementation written before event sources existed: it has no `eventSources` member. */
+type LegacyEventStore = Omit<IEventStore, 'eventSources'>;
+
+describe('when implementing an event store written before event sources', () => {
+    it('should still satisfy the IEventStore contract', () => {
+        // Compile-time regression: assigning would fail type-checking if `eventSources` became required.
+        const legacy = {} as LegacyEventStore;
+        const store: IEventStore = legacy;
+        should.not.exist(store.eventSources);
+    });
+});

package/index.ts

@@ -3,6 +3,7 @@
 
 import * as events from './events/index.js';
 import * as eventSequences from './eventSequences/index.js';
+import * as eventSources from './eventSources/index.js';
 import * as reactors from './reactors/index.js';
 import * as reducers from './reducers/index.js';
 import * as seeding from './seeding/index.js';
@@ -48,6 +49,7 @@ export { DiagChronicleLogger } from './logging/DiagChronicleLogger.js';
 
 export * from './events/index.js';
 export * from './eventSequences/index.js';
+export * from './eventSources/index.js';
 export * from './reactors/index.js';
 export * from './reducers/index.js';
 export * from './seeding/index.js';
@@ -74,6 +76,7 @@ export * from './confidentiality/index.js';
 export {
     events,
     eventSequences,
+    eventSources,
     reactors,
     reducers,
     seeding,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.48.0",
+    "version": "6.50.0",
     "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,12 +173,12 @@
         "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/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.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 projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.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/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.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 projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts for_EventStore/when_implementing_a_legacy_event_store.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.16.0",
-        "@cratis/chronicle.contracts": "19.26.2",
+        "@cratis/chronicle.contracts": "19.31.10",
         "@grpc/grpc-js": "^1.14.5",
         "@opentelemetry/api": "^1.9.1",
         "glob": "^13.0.6",
@@ -188,14 +188,14 @@
         "undici": "^8.11.2"
     },
     "devDependencies": {
-        "@cratis/fundamentals": "7.20.0",
+        "@cratis/fundamentals": "7.22.4",
         "@opentelemetry/context-async-hooks": "2.11.0",
         "@opentelemetry/core": "2.11.0",
         "@opentelemetry/instrumentation-grpc": "0.222.0",
         "@opentelemetry/instrumentation-http": "0.222.0",
         "@opentelemetry/sdk-metrics": "2.11.0",
         "@opentelemetry/sdk-trace-base": "2.11.0",
-        "@types/node": "^26.6.3",
+        "@types/node": "^26.6.4",
         "@typescript/native": "npm:typescript@^7.0.2",
         "esbuild": "^0.28.2",
         "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -203,6 +203,6 @@
         "vitest": "^5.0.3"
     },
     "peerDependencies": {
-        "@cratis/fundamentals": "^7.20.0"
+        "@cratis/fundamentals": "^7.22.4"
     }
 }

package/projections/eventContextPropertyExpression.ts

@@ -23,7 +23,9 @@ const contextProperties = {
     correlationId: true,
     causation: true,
     tags: true
-} satisfies Record<keyof EventContext, true>;
+    // eventSource and namedTags are deliberately not projectable: their kernel resolution is not part of the
+    // supported expression set.
+} satisfies Record<Exclude<keyof EventContext, 'eventSource' | 'namedTags'>, true>;
 
 // Mirror the kernel's DerivedPropertyFunctions registry: Week() applies to dates only.
 const derivedFunctions: Record<string, string> = { week: 'Week' };

package/testing/EventScenario.event-sources.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 'reflect-metadata';
+import { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+class ScenarioSourceEvent { @field(String) name: string; constructor(name: string) { this.name = name; } }
+eventType('ScenarioSourceEvent')(ScenarioSourceEvent);
+
+const rejects = async (action: () => Promise<unknown>) => {
+    let caught: unknown;
+    try { await action(); } catch (error) { caught = error; }
+    (caught instanceof UnsupportedEventSequenceOperation).should.be.true;
+};
+const create = () => new EventScenario({ artifacts: { eventTypes: [ScenarioSourceEvent] } });
+
+describe('when appending with registered event sources in an in-process scenario', () => {
+    it('should reject the eventSource option on append instead of dropping it', async () => {
+        await rejects(() => create().append('A', new ScenarioSourceEvent('x'), { eventSource: 'Account' }));
+    });
+    it('should reject the eventSource option on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x') }], { eventSource: 'Account' }));
+    });
+    it('should reject a per-event eventSource on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventSource: 'Account' }]));
+    });
+    it('should reject a per-event eventStream on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventStream: 'Transactions' }]));
+    });
+});