@cratis/chronicle 6.45.0 → 6.47.0

package/events/eventStreamTypeDecorator.ts

@@ -0,0 +1,33 @@
+// 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';
+
+const EVENT_STREAM_TYPE_METADATA_KEY = 'chronicle:eventStreamType';
+
+/**
+ * Restricts a reactor or reducer to events in the given event stream type.
+ * Like .NET `[EventStreamType]`, also sets the stream type of bare events returned by a reactor.
+ * Explicit EventForEventSourceId returns and service append options retain their own metadata.
+ * Does not filter projections.
+ * Supports legacy and standard class decorators; derived observers inherit the value unless overridden.
+ * @param value - The event stream type to observe. 'All' leaves the stream type unrestricted.
+ * @returns A class decorator.
+ */
+export function eventStreamType(value: string): ClassDecorator {
+    return (target: object) => { Reflect.defineMetadata(EVENT_STREAM_TYPE_METADATA_KEY, value, target); };
+}
+
+/**
+ * Resolves an observer's event stream type filter, including inherited metadata.
+ * @param target - The observer constructor.
+ * @returns The configured value, or 'All' (unrestricted).
+ */
+export function getEventStreamTypeFor(target: Function): string {
+    return getDeclaredEventStreamTypeFor(target) ?? 'All';
+}
+
+/** Resolves declared (including inherited) metadata without the observer's 'All' delivery default. */
+export function getDeclaredEventStreamTypeFor(target: Function): string | undefined {
+    return Reflect.getMetadata(EVENT_STREAM_TYPE_METADATA_KEY, target) as string | undefined;
+}

package/events/for_observerFilters/when_registering/filter_registration_behaviors.fixture.ts

@@ -0,0 +1,55 @@
+// 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 { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
+import type { IEventLog } from '../../../eventSequences/IEventLog.js';
+import { Reactors } from '../../../reactors/Reactors.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { Reducers } from '../../../reducers/Reducers.js';
+import { reducer } from '../../../reducers/reducer.js';
+
+chai.should();
+
+export function filterRegistrationBehaviors(cases: readonly { type: Constructor; source: string; stream: string; tags: string[] }[]): void {
+    for (const kind of ['reactor', 'reducer'] as const) {
+        for (const { type, source, stream, tags } of cases) {
+            describe(`when registering ${kind} ${type.name}`, () => {
+                it('should combine source and stream type filters with tag filters without changing observer labels', async () => {
+                    let registration: unknown;
+                    let received!: () => void;
+                    const captured = new Promise<void>(resolve => { received = resolve; });
+                    const observe = async function* (queue: AsyncIterable<unknown>) {
+                        registration = (await queue[Symbol.asyncIterator]().next()).value;
+                        received();
+                        // An empty stream is enough to capture registration, not evidence of kernel filtering.
+                        yield* [];
+                    };
+                    const connection = { reactors: { observe }, reducers: { observe }, readModels: {
+                        registerMany: async () => ({})
+                    } } as unknown as ChronicleConnection;
+                    reactor(type.name)(type);
+                    reducer(type.name)(type);
+                    const artifacts = { reactors: kind === 'reactor' ? [type] : [], reducers: kind === 'reducer' ? [type] : [],
+                        eventTypes: [], readModels: [] } as unknown as IClientArtifactsProvider;
+                    const observer = kind === 'reactor'
+                        ? new Reactors(artifacts, connection, 'store', 'Default', new ConnectionLifecycle(), {} as IEventLog)
+                        : new Reducers(artifacts, connection, 'store', 'Default', new ConnectionLifecycle(), 'sink');
+                    try {
+                        await observer.register();
+                        await captured;
+                        const message = registration as { Content: { Value0: Record<string, { Filters: object; Tags: string[] }> } };
+                        const definition = message.Content.Value0[kind === 'reactor' ? 'Reactor' : 'Reducer'];
+                        definition.Filters.should.deep.equal({ EventSourceType: source, EventStreamType: stream, FilterTags: tags });
+                        definition.Tags.should.deep.equal(tags.length ? ['Analytics'] : []);
+                    } finally {
+                        observer.dispose();
+                    }
+                });
+            });
+        }
+    }
+}

package/events/for_observerFilters/when_registering/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventSourceType, eventStreamType, filterEventsByTag, tag } from '../../../index.js';
+import { filterRegistrationBehaviors } from './filter_registration_behaviors.fixture.js';
+
+class Unfiltered {}
+@eventSourceType('Customers')
+class SourceFiltered {}
+@eventStreamType('Orders')
+class StreamFiltered {}
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class Combined {}
+class Inherited extends Combined {}
+@eventSourceType('')
+@eventStreamType('All')
+class Reset extends Combined {}
+
+filterRegistrationBehaviors([
+    { type: Unfiltered, source: '', stream: 'All', tags: [] },
+    { type: SourceFiltered, source: 'Customers', stream: 'All', tags: [] },
+    { type: StreamFiltered, source: '', stream: 'Orders', tags: [] },
+    { type: Combined, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Inherited, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Reset, source: '', stream: 'All', tags: ['priority', 'vip'] }
+]);

package/events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventSourceType, eventStreamType, filterEventsByTag, tag } from '../../../index.js';
+import { filterRegistrationBehaviors } from './filter_registration_behaviors.fixture.js';
+
+class Unfiltered {}
+@eventSourceType('Customers')
+class SourceFiltered {}
+@eventStreamType('Orders')
+class StreamFiltered {}
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class Combined {}
+class Inherited extends Combined {}
+@eventSourceType('')
+@eventStreamType('All')
+class Reset extends Combined {}
+
+filterRegistrationBehaviors([
+    { type: Unfiltered, source: '', stream: 'All', tags: [] },
+    { type: SourceFiltered, source: 'Customers', stream: 'All', tags: [] },
+    { type: StreamFiltered, source: '', stream: 'Orders', tags: [] },
+    { type: Combined, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Inherited, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Reset, source: '', stream: 'All', tags: ['priority', 'vip'] }
+]);

package/events/index.ts

@@ -18,6 +18,8 @@ export { isRegisteredEvent } from './isRegisteredEvent.js';
 export { Tag } from './Tag.js';
 export { tag, tags, getTagsFor } from './tagDecorator.js';
 export { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator.js';
+export { eventSourceType, getEventSourceTypeFor } from './eventSourceTypeDecorator.js';
+export { eventStreamType, getEventStreamTypeFor } from './eventStreamTypeDecorator.js';
 export { mergeTags } from './mergeTags.js';
 export * from './constraints/index.js';
 export * from './migrations/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.45.0",
+    "version": "6.47.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,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 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",
+        "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",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/projections/declarative/CompositeKeyBuilder.ts

@@ -3,36 +3,53 @@
 
 import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
 import { ICompositeKeyBuilder } from './ICompositeKeyBuilder.js';
+import { ISetBuilder } from './ISetBuilder.js';
+import { ICompositeKeySetBuilder } from './ICompositeKeySetBuilder.js';
+import { SetBuilder } from './SetBuilder.js';
 
 /**
  * Concrete implementation of {@link ICompositeKeyBuilder} that builds a `$composite(...)` key
- * expression from multiple event properties mapped onto named parts of a key type.
+ * expression from event properties, event context, source identifiers and constants.
  * @template TKeyType - The composite key type.
  * @template TEvent - The event type.
  */
 export class CompositeKeyBuilder<TKeyType, TEvent> implements ICompositeKeyBuilder<TKeyType, TEvent> {
-    private readonly _parts: Array<{ property: string; expression: string }> = [];
+    private readonly _parts: Array<{ property: string; expression?: string }> = [];
 
+    /** @inheritdoc */
+    set<TProperty>(targetPropertyAccessor: (key: TKeyType) => TProperty): ICompositeKeySetBuilder<TKeyType, TEvent, TProperty>;
     /** @inheritdoc */
     set(
         targetPropertyAccessor: PropertyAccessor<TKeyType>,
         sourcePropertyAccessor: PropertyAccessor<TEvent>
-    ): ICompositeKeyBuilder<TKeyType, TEvent> {
+    ): ICompositeKeyBuilder<TKeyType, TEvent>;
+    set(
+        targetPropertyAccessor: PropertyAccessor<TKeyType>,
+        sourcePropertyAccessor?: PropertyAccessor<TEvent>
+    ): ICompositeKeyBuilder<TKeyType, TEvent> | ISetBuilder<TEvent, ICompositeKeyBuilder<TKeyType, TEvent>> {
         const targetHandler = new PropertyPathResolverProxyHandler();
         const targetProxy = new Proxy({}, targetHandler);
         targetPropertyAccessor(targetProxy as TKeyType);
 
-        const sourceHandler = new PropertyPathResolverProxyHandler();
-        const sourceProxy = new Proxy({}, sourceHandler);
-        sourcePropertyAccessor(sourceProxy as TEvent);
+        if (this._parts.some(part => part.property === targetHandler.property)) {
+            throw new Error(`Composite key part '${targetHandler.property}' is already configured.`);
+        }
 
-        this._parts.push({ property: targetHandler.property, expression: sourceHandler.property });
-        return this;
+        const part: { property: string; expression?: string } = { property: targetHandler.property };
+        this._parts.push(part);
+        const setBuilder = new SetBuilder<TEvent, ICompositeKeyBuilder<TKeyType, TEvent>>(
+            part.property, (_property, expression) => { part.expression = expression; }, this);
+        return sourcePropertyAccessor ? setBuilder.to(sourcePropertyAccessor) : setBuilder;
     }
 
     /** @inheritdoc */
     build(): string {
-        const parts = this._parts.map(part => `${part.property}=${part.expression}`).join(',');
+        const parts = this._parts.map(part => {
+            if (part.expression === undefined) {
+                throw new Error(`Composite key part '${part.property}' is missing a to expression.`);
+            }
+            return `${part.property}=${part.expression}`;
+        }).join(',');
         return `$composite(${parts})`;
     }
 }

package/projections/declarative/ICompositeKeyBuilder.ts

@@ -2,13 +2,21 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { PropertyAccessor } from '@cratis/fundamentals';
+import { ICompositeKeySetBuilder } from './ICompositeKeySetBuilder.js';
 
 /**
- * Defines a builder for constructing composite keys from multiple event properties.
+ * Defines a builder for constructing composite keys from event properties, context and constants.
  * @template TKeyType - The composite key type.
  * @template TEvent - The event type.
  */
 export interface ICompositeKeyBuilder<TKeyType, TEvent> {
+    /**
+     * Configures a key part from an event property, event context property, event source id or constant.
+     * @param targetPropertyAccessor - Accessor for the property on the key type to populate.
+     * @returns A set-expression builder whose to methods return this composite key builder.
+     */
+    set<TProperty>(targetPropertyAccessor: (key: TKeyType) => TProperty): ICompositeKeySetBuilder<TKeyType, TEvent, TProperty>;
+
     /**
      * Maps a source event property to a target key property.
      * @param targetPropertyAccessor - Accessor for the property on the key type to populate.

package/projections/declarative/ICompositeKeySetBuilder.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ICompositeKeyBuilder } from './ICompositeKeyBuilder.js';
+import { ISetBuilder } from './ISetBuilder.js';
+
+/**
+ * Configures an expression for a composite key part, retaining its target property type.
+ * @template TKeyType - The composite key type.
+ * @template TEvent - The event type.
+ * @template TProperty - The selected key property's type.
+ */
+export interface ICompositeKeySetBuilder<TKeyType, TEvent, TProperty>
+    extends Omit<ISetBuilder<TEvent, ICompositeKeyBuilder<TKeyType, TEvent>>, 'toValue'> {
+    /**
+     * Sets the key part to a constant of the selected property's type.
+     * @param value - The constant value to assign.
+     * @returns The composite key builder for fluent chaining.
+     */
+    toValue(value: TProperty): ICompositeKeyBuilder<TKeyType, TEvent>;
+}

package/projections/declarative/for_CompositeKeyBuilder/when_matching_kernel_fixtures.spec.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { ProjectionBuilderFor, type ICompositeKeyBuilder } from '../index.js';
+import type { ChildrenDefinitionLike } from '../ProjectionBuilderCore.js';
+
+chai.should();
+
+class RecordChanged { orderId!: string; title!: string; }
+class OrderCreated { orderId!: string; title!: string; }
+class ItemChanged { orderId!: string; itemId!: string; name!: string; }
+class OrderPlaced { customerId!: string; }
+class CustomerNamed { customerId!: string; name!: string; }
+class ItemAdded { itemId!: string; title!: string; name!: string; }
+class ItemNamed { itemId!: string; name!: string; }
+for (const event of [RecordChanged, OrderCreated, ItemChanged, OrderPlaced, CustomerNamed, ItemAdded, ItemNamed]) eventType(event.name)(event);
+
+class Key { orderId!: string; customerId!: string; itemId!: string; subject!: string; sourceId!: string; category!: string; }
+class Item { id!: string; name!: string; }
+class CompositeItem { id!: Key; name!: string; }
+class Model { id!: Key; title!: string; items!: Item[]; }
+class ChildJoinModel { id!: Key; title!: string; items!: CompositeItem[]; }
+class JoinModel { id!: string; customerId!: string; customerName!: string; }
+
+type Definition = ReturnType<ProjectionBuilderFor<Model>['build']>;
+
+function contextParts<TEvent>(key: ICompositeKeyBuilder<Key, TEvent>): ICompositeKeyBuilder<Key, TEvent> {
+    return key.set(target => target.subject).toEventContextProperty('subject')
+        .set(target => target.sourceId).toEventSourceId();
+}
+
+function childKey<TEvent extends { itemId: string }>(key: ICompositeKeyBuilder<Key, TEvent>): void {
+    contextParts(key.set(target => target.itemId, event => event.itemId)).set(target => target.category).toValue('items');
+}
+
+function buildRoot(): Definition {
+    return new ProjectionBuilderFor<Model>().noAutoMap()
+        .from(RecordChanged, from => from
+            .usingCompositeKey<Key>(key => contextParts(key.set(target => target.orderId, event => event.orderId))
+                .set(target => target.category).toValue('orders'))
+            .set(model => model.title).to(event => event.title))
+        .build('oracle-composite-expression-parts', 'OracleReadModel');
+}
+
+function buildParent(withConstant: boolean): Definition {
+    const parentKey = <TEvent extends { orderId: string }>(key: ICompositeKeyBuilder<Key, TEvent>): void => {
+        if (!withConstant) key.set(target => target.orderId, event => event.orderId);
+        contextParts(key);
+        if (withConstant) key.set(target => target.category).toValue('orders');
+    };
+    return new ProjectionBuilderFor<Model>().noAutoMap()
+        .from(OrderCreated, from => from.usingCompositeKey<Key>(parentKey).set(model => model.title).to(event => event.title))
+        .children<Item>(model => model.items, children => children.noAutoMap().identifiedBy(item => item.id)
+            .from(ItemChanged, from => from.usingKey(event => event.itemId).usingParentCompositeKey<Key>(parentKey)
+                .set(item => item.id).to(event => event.itemId).set(item => item.name).to(event => event.name)))
+        .build(withConstant ? 'oracle-composite-parent-expression-parts' : 'oracle-composite-parent-without-constant', 'OracleReadModel');
+}
+
+function buildRootJoin(): Definition {
+    return new ProjectionBuilderFor<JoinModel>().noAutoMap()
+        .from(OrderPlaced, from => from.set(model => model.customerId).to(event => event.customerId))
+        .join(CustomerNamed, join => join.on(model => model.customerId)
+            .usingCompositeKey<Key>(key => contextParts(key.set(target => target.customerId, event => event.customerId))
+                .set(target => target.category).toValue('customers'))
+            .set(model => model.customerName).to(event => event.name))
+        .build('oracle-composite-join-expression-parts', 'OracleReadModel');
+}
+
+function buildChildJoin(): Definition {
+    return new ProjectionBuilderFor<ChildJoinModel>().noAutoMap()
+        .from(ItemAdded, from => from.usingCompositeKey<Key>(childKey).set(model => model.title).to(event => event.title))
+        .children<CompositeItem>(model => model.items, children => children.noAutoMap().identifiedBy(item => item.id)
+            .from(ItemAdded, from => from.usingCompositeKey<Key>(childKey).usingParentCompositeKey<Key>(childKey)
+                .set(item => item.name).to(event => event.name))
+            .join(ItemNamed, join => join.on(item => item.id).usingCompositeKey<Key>(childKey)
+                .set(item => item.name).to(event => event.name)))
+        .build('oracle-composite-child-join-expression-parts', 'OracleReadModel');
+}
+
+// Compare every event's Key/ParentKey and mappings, including child joins; do not derive
+// builder configuration from the fixture expressions being asserted.
+function expressions(definition: Pick<ChildrenDefinitionLike, 'From' | 'Join' | 'Children'>): object {
+    return {
+        From: definition.From.map(entry => ({ Event: entry.Key.Id, ...entry.Value })),
+        Join: definition.Join.map(entry => ({ Event: entry.Key.Id, Key: entry.Value.Key, On: entry.Value.On, Properties: entry.Value.Properties })),
+        Children: Object.fromEntries(Object.entries(definition.Children).map(([name, child]) => [name, expressions(child)]))
+    };
+}
+
+for (const [name, build] of [
+    ['composite-key-expression-parts', buildRoot],
+    ['composite-parent-key-expression-parts', () => buildParent(true)],
+    ['composite-parent-key-without-constant', () => buildParent(false)],
+    ['composite-join-key-expression-parts', buildRootJoin],
+    ['composite-child-join-key-expression-parts', buildChildJoin]
+] as const) {
+    describe(`when matching the composite expressions in ${name}`, () => {
+        const fixture = JSON.parse(readFileSync(new URL(`../../../testing/projections/fixtures/${name}.json`, import.meta.url), 'utf8')) as { wireDefinition: Definition };
+        let definition: Definition;
+        beforeEach(() => { definition = build(); });
+        it('should emit the instance, parent and join keys executed by the packaged kernel', () => {
+            expressions(definition).should.deep.equal(expressions(fixture.wireDefinition));
+        });
+    });
+}

package/projections/declarative/for_CompositeKeyBuilder/when_setting_a_duplicate_part.spec.ts

@@ -0,0 +1,43 @@
+// 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 { CompositeKeyBuilder } from '../CompositeKeyBuilder.js';
+
+chai.should();
+
+class Key { orderId!: string; }
+class Changed { orderId!: string; }
+
+for (const first of ['two-argument', 'completed', 'unfinished'] as const) {
+    for (const second of ['two-argument', 'one-argument'] as const) {
+        describe(`when setting a duplicate composite part using ${second} after ${first}`, () => {
+            let builder: CompositeKeyBuilder<Key, Changed>;
+            let duplicate: () => unknown;
+
+            beforeEach(() => {
+                builder = new CompositeKeyBuilder<Key, Changed>();
+                if (first === 'two-argument') builder.set(key => key.orderId, event => event.orderId);
+                if (first === 'completed') builder.set(key => key.orderId).toValue('original');
+                if (first === 'unfinished') builder.set(key => key.orderId);
+                duplicate = () => second === 'two-argument'
+                    ? builder.set(key => key.orderId, event => event.orderId)
+                    : builder.set(key => key.orderId);
+            });
+
+            it('should reject the duplicate as soon as the target is selected', () => {
+                duplicate.should.throw("Composite key part 'orderId' is already configured.");
+            });
+        });
+    }
+}
+
+describe('when continuing after a rejected duplicate composite part', () => {
+    it('should retain the original part without reserving another part', () => {
+        const builder = new CompositeKeyBuilder<Key, Changed>();
+        const original = builder.set(key => key.orderId);
+        (() => builder.set(key => key.orderId)).should.throw();
+        original.toValue('original');
+        builder.build().should.equal('$composite(orderId=$value(original))');
+    });
+});

package/projections/declarative/for_CompositeKeyBuilder/when_setting_expression_parts.spec.ts

@@ -0,0 +1,84 @@
+// 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 { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { CompositeKeyBuilder } from '../CompositeKeyBuilder.js';
+import type { ICompositeKeyBuilder } from '../ICompositeKeyBuilder.js';
+import { ProjectionBuilderFor } from '../ProjectionBuilderFor.js';
+
+chai.should();
+
+class Changed { orderId!: string; lineNumber!: number; }
+eventType('expression-parts-changed')(Changed);
+class Model { id!: string; }
+class Key { orderId!: string; lineNumber!: number; subject!: string; sourceId!: string; category!: string; }
+
+const configure = (key: ICompositeKeyBuilder<Key, Changed>) => key
+    .set(target => target.orderId, event => event.orderId)
+    .set(target => target.lineNumber).to(event => event.lineNumber)
+    .set(target => target.subject).toEventContextProperty('causedBy.subject')
+    .set(target => target.sourceId).toEventSourceId()
+    .set(target => target.category).toValue('orders');
+const expression = '$composite(orderId=orderId,lineNumber=lineNumber,subject=$eventContext(CausedBy.Subject),sourceId=$eventSourceId,category=$value(orders))';
+
+for (const kind of ['root', 'parent', 'join'] as const) {
+    describe(`when setting mixed expression parts on a ${kind} composite key`, () => {
+        let result: string;
+        beforeEach(() => {
+            const builder = new ProjectionBuilderFor<Model>();
+            if (kind === 'root') builder.from(Changed, from => from.usingCompositeKey<Key>(configure));
+            if (kind === 'parent') builder.from(Changed, from => from.usingParentCompositeKey<Key>(configure));
+            if (kind === 'join') builder.join(Changed, join => join.on(model => model.id).usingCompositeKey<Key>(configure));
+            const definition = builder.build('expressionParts', 'Model');
+            result = kind === 'join' ? definition.Join[0].Value.Key
+                : kind === 'parent' ? definition.From[0].Value.ParentKey : definition.From[0].Value.Key;
+        });
+        it('should emit the .NET set expressions in declaration order', () => result.should.equal(expression));
+    });
+}
+
+for (const [value, expected] of [
+    [42, '$value(42)'], [false, '$value(false)'], ['fixed', '$value(fixed)'],
+    [null, '$null'], [{ value: 'concept' }, '$value(concept)']
+] as const) {
+    describe(`when setting a composite constant part to ${JSON.stringify(value)}`, () => {
+        let result: string;
+        beforeEach(() => {
+            const builder = new CompositeKeyBuilder<{ category: typeof value }, Changed>();
+            builder.set(target => target.category).toValue(value);
+            result = builder.build();
+        });
+        it('should use the shared constant expression syntax', () => result.should.equal(`$composite(category=${expected})`));
+    });
+}
+
+describe('when completing composite parts out of declaration order', () => {
+    it('should retain declaration order', () => {
+        const builder = new CompositeKeyBuilder<Key, Changed>();
+        const first = builder.set(target => target.orderId);
+        builder.set(target => target.category).toValue('orders');
+        first.to(event => event.orderId);
+        builder.build().should.equal('$composite(orderId=orderId,category=$value(orders))');
+    });
+});
+
+describe('when a composite part has no source expression', () => {
+    it('should reject building an incomplete key', () => {
+        const builder = new CompositeKeyBuilder<Key, Changed>();
+        builder.set(target => target.category);
+        (() => builder.build()).should.throw("Composite key part 'category' is missing a to expression.");
+    });
+});
+
+describe('when configuring an invalid context or constant part', () => {
+    it('should reject a context path the kernel cannot resolve', () => {
+        const builder = new CompositeKeyBuilder<Key, Changed>();
+        (() => builder.set(target => target.subject).toEventContextProperty('unknown')).should.throw();
+    });
+    it('should reject a constant the kernel cannot parse', () => {
+        const builder = new CompositeKeyBuilder<Key, Changed>();
+        (() => builder.set(target => target.category).toValue('a,b')).should.throw('unsupported by the kernel');
+    });
+});

package/projections/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.standard.spec.ts

@@ -0,0 +1,43 @@
+// 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 { CompositeKeyBuilder, type ICompositeKeyBuilder } from '../index.js';
+
+chai.should();
+
+class Key {
+    number!: number;
+    text!: string;
+    nullable!: string | null;
+    sourceNumber!: number;
+}
+class Changed { number!: number; }
+
+// Checked by test:standard-types. Do not execute invalid configurations at runtime.
+function rejectMismatchedConstants(builder: ICompositeKeyBuilder<Key, Changed>): void {
+    // @ts-expect-error A number key part cannot receive a string constant.
+    builder.set(key => key.number).toValue('orders');
+    // @ts-expect-error A string key part cannot receive a number constant.
+    builder.set(key => key.text).toValue(42);
+    // @ts-expect-error Null requires a nullable key part.
+    builder.set(key => key.text).toValue(null);
+}
+
+function rejectOnConcreteBuilder(builder: CompositeKeyBuilder<Key, Changed>): void {
+    // @ts-expect-error The concrete overload must not fall back to an untyped accessor.
+    builder.set(key => key.number).toValue('orders');
+}
+void rejectMismatchedConstants;
+void rejectOnConcreteBuilder;
+
+describe('when typing constant composite parts', () => {
+    it('should accept selected property types and preserve fluent chaining', () => {
+        const builder: ICompositeKeyBuilder<Key, Changed> = new CompositeKeyBuilder<Key, Changed>();
+        builder.set(key => key.number).toValue(42)
+            .set(key => key.text).toValue('orders')
+            .set(key => key.nullable).toValue(null)
+            .set(key => key.sourceNumber, event => event.number);
+        builder.build().should.equal('$composite(number=$value(42),text=$value(orders),nullable=$null,sourceNumber=number)');
+    });
+});

package/projections/declarative/index.ts

@@ -26,6 +26,7 @@ export type { IJoinBuilder } from './IJoinBuilder.js';
 export type { IFromEveryBuilder } from './IFromEveryBuilder.js';
 export type { IReadModelPropertiesBuilder } from './IReadModelPropertiesBuilder.js';
 export type { ICompositeKeyBuilder } from './ICompositeKeyBuilder.js';
+export type { ICompositeKeySetBuilder } from './ICompositeKeySetBuilder.js';
 export type { ISetBuilder } from './ISetBuilder.js';
 export type { IAllSetBuilder } from './IAllSetBuilder.js';
 export type { IAddBuilder } from './IAddBuilder.js';