@cratis/chronicle 6.48.0 → 6.50.0

package/dist/types/DecoratorType.js

@@ -25,5 +25,7 @@ export var DecoratorType;
     DecoratorType["EventTypeMigration"] = "eventTypeMigration";
     /** Global read model variant handler artifacts discovered through the globalFor decorator. */
     DecoratorType["GlobalForHandler"] = "globalForHandler";
+    /** Event source definition artifacts discovered through the eventSource decorator. */
+    DecoratorType["EventSource"] = "eventSource";
 })(DecoratorType || (DecoratorType = {}));
 //# sourceMappingURL=DecoratorType.js.map

package/dist/types/DecoratorType.js.map

@@ -1 +1 @@
-{"version":3,"file":"DecoratorType.js","sourceRoot":"","sources":["../../types/DecoratorType.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;GAEG;AACH,MAAM,CAAN,IAAY,aA8BX;AA9BD,WAAY,aAAa;IACrB,uEAAuE;IACvE,wCAAuB,CAAA;IAEvB,uEAAuE;IACvE,wCAAuB,CAAA;IAEvB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,gEAAgE;IAChE,kCAAiB,CAAA;IAEjB,wEAAwE;IACxE,0CAAyB,CAAA;IAEzB,oFAAoF;IACpF,0CAAyB,CAAA;IAEzB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,0FAA0F;IAC1F,0DAAyC,CAAA;IAEzC,8FAA8F;IAC9F,sDAAqC,CAAA;AACzC,CAAC,EA9BW,aAAa,KAAb,aAAa,QA8BxB"}
+{"version":3,"file":"DecoratorType.js","sourceRoot":"","sources":["../../types/DecoratorType.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG;;GAEG;AACH,MAAM,CAAN,IAAY,aAiCX;AAjCD,WAAY,aAAa;IACrB,uEAAuE;IACvE,wCAAuB,CAAA;IAEvB,uEAAuE;IACvE,wCAAuB,CAAA;IAEvB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,gEAAgE;IAChE,kCAAiB,CAAA;IAEjB,wEAAwE;IACxE,0CAAyB,CAAA;IAEzB,oFAAoF;IACpF,0CAAyB,CAAA;IAEzB,kEAAkE;IAClE,oCAAmB,CAAA;IAEnB,0FAA0F;IAC1F,0DAAyC,CAAA;IAEzC,8FAA8F;IAC9F,sDAAqC,CAAA;IAErC,sFAAsF;IACtF,4CAA2B,CAAA;AAC/B,CAAC,EAjCW,aAAa,KAAb,aAAa,QAiCxB"}

package/eventSequences/AppendOptions.ts

@@ -3,6 +3,8 @@
 
 import { Guid } from '@cratis/fundamentals';
 import type { Tag } from '../events/Tag.js';
+import type { NamedTag } from '../events/NamedTag.js';
+import type { Constructor } from '@cratis/fundamentals';
 import type { ConcurrencyScope } from './ConcurrencyScope.js';
 
 /**
@@ -41,10 +43,33 @@ export interface AppendOptions {
      */
     tags?: ReadonlyArray<string | Tag>;
 
+    /**
+     * Optional structured named tags shared by every event being appended. For the
+     * `appendMany(events: EventForEventSourceId[], options?)` overload they are merged after each entry's own
+     * {@link EventForEventSourceId.namedTags}; the first occurrence of each exact name and value pair is kept.
+     * When any event ends up with named tags, the append uses the kernel's dedicated named-tag call, so a kernel
+     * without named-tag support rejects it instead of silently dropping the tags.
+     * @throws {@link InvalidNamedTag} (from the append) when an entry has a blank name or a non-string value.
+     */
+    namedTags?: ReadonlyArray<NamedTag>;
+
     /**
      * Optional labeled concurrency scopes, keyed by event source id. Labels need not be append targets.
      * Any target without an explicit scope falls back to {@link concurrencyScope}.
      * The kernel requires at least one event in a batch, so scope-only batches are not supported.
      */
     concurrencyScopes?: Record<string, ConcurrencyScope>;
+
+    /**
+     * Routes the append through a registered event source definition: the class decorated with `@eventSource`, or its name.
+     * Sets the event source type and the wire `EventSource` key. Explicit `sourceType`/`streamType` values must not contradict it.
+     * When no `concurrencyScope` is supplied and the definition declares concurrency dimensions, the scope is derived from them.
+     */
+    eventSource?: Constructor | string;
+
+    /**
+     * The name of a stream declared by {@link eventSource}. Becomes the event stream type. Requires `eventSource`.
+     * Use `streamId` for the identifier within the stream.
+     */
+    eventStream?: string;
 }

package/eventSequences/EventForEventSourceId.ts

@@ -1,7 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { Constructor } from '@cratis/fundamentals';
 import type { Tag } from '../events/Tag.js';
+import type { NamedTag } from '../events/NamedTag.js';
 
 /**
  * Represents an event paired with the event source identifier it belongs to.
@@ -34,4 +36,22 @@ export interface EventForEventSourceId {
      * append time.
      */
     readonly tags?: ReadonlyArray<string | Tag>;
+
+    /**
+     * Optional structured named tags for this event. They are merged, in order, with the shared
+     * `AppendOptions.namedTags`; the first occurrence of each exact name and value pair is kept.
+     */
+    readonly namedTags?: ReadonlyArray<NamedTag>;
+
+    /**
+     * Optional registered event source definition (class decorated with `@eventSource`, or its name) for this event.
+     * Overrides `AppendOptions.eventSource`, so one batch can mix several event sources.
+     */
+    readonly eventSource?: Constructor | string;
+
+    /**
+     * Optional stream name declared by the event's event source. Overrides `AppendOptions.eventStream`.
+     * When this event names a different `eventSource` than the options, the options' stream is not inherited.
+     */
+    readonly eventStream?: string;
 }

package/eventSequences/EventLog.ts

@@ -7,6 +7,7 @@ import { EventSequenceId } from './EventSequenceId.js';
 import { IEventLog } from './IEventLog.js';
 import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager.js';
 import type { ConstraintViolation } from './ConstraintViolation.js';
+import type { IEventSources } from '../eventSources/IEventSources.js';
 import type { ChronicleTelemetryOptions } from '../telemetry/ChronicleTelemetryOptions.js';
 
 /**
@@ -20,8 +21,9 @@ export class EventLog extends EventSequence implements IEventLog {
         connection: ChronicleConnection,
         unitOfWorkManager: IUnitOfWorkManager,
         resolveConstraintMessage?: (violation: ConstraintViolation) => ConstraintViolation,
-        telemetry?: ChronicleTelemetryOptions
+        telemetry?: ChronicleTelemetryOptions,
+        eventSources?: IEventSources
     ) {
-        super(EventSequenceId.eventLog, eventStoreName, namespace, connection, unitOfWorkManager, resolveConstraintMessage, telemetry);
+        super(EventSequenceId.eventLog, eventStoreName, namespace, connection, unitOfWorkManager, resolveConstraintMessage, telemetry, eventSources);
     }
 }

package/eventSequences/EventSequence.ts

@@ -14,6 +14,7 @@ import { prepareBatchAppend } from './prepareBatchAppend.js';
 import { createAppendNotification, mapAppendNotificationCausation } from './createAppendNotification.js';
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import type { AppendedEvent } from '../events/AppendedEvent.js';
+import type { NamedTag } from '../events/NamedTag.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
 import { DecoratorType } from '../types/DecoratorType.js';
 import { TypeDiscoverer } from '../types/TypeDiscoverer.js';
@@ -47,7 +48,10 @@ import { causationManager, CausationType } from '../auditing/index.js';
 import { toContractsGuid } from '../connection/Guid.js';
 import { ensureCommandResponse, ensureCommandSuccess, ensureQuerySuccess } from '../connection/callResults.js';
 import type { ConcurrencyScope } from './ConcurrencyScope.js';
+import type { IEventSources } from '../eventSources/IEventSources.js';
+import { deriveConcurrencyScope, planDerivedGuards, resolveBatchRouting, resolveSingleRouting } from './resolveEventSourceRouting.js';
 import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager.js';
+import { ensureNamedTagBatchIsSupported } from './ensureNamedTagBatchIsSupported.js';
 
 /**
  * Implements {@link IEventSequence} by communicating with the Chronicle Kernel
@@ -64,14 +68,16 @@ export class EventSequence implements IEventSequence {
         private readonly _connection: ChronicleConnection,
         private readonly _unitOfWorkManager: IUnitOfWorkManager,
         private readonly _resolveConstraintMessage?: (violation: ConstraintViolation) => ConstraintViolation,
-        private readonly _telemetry?: ChronicleTelemetryOptions
+        private readonly _telemetry?: ChronicleTelemetryOptions,
+        private readonly _eventSources?: IEventSources
     ) {
         this.transactional = new TransactionalEventSequence(this, this._unitOfWorkManager);
     }
 
     /** @inheritdoc */
     async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
-        const { eventType, correlationId, content, tags, causationChain, identity, subject } = prepareSingleAppend(event, options);
+        const routing = resolveSingleRouting(this._eventSources, options);
+        const { eventType, correlationId, content, tags, namedTags, causationChain, identity, subject } = prepareSingleAppend(event, options);
 
         const sequenceMetricAttributes = {
             [names.attributes.eventStore]: this._eventStoreName,
@@ -88,14 +94,17 @@ export class EventSequence implements IEventSequence {
             if (options?.sourceType) span.setAttribute(names.attributes.eventSourceType, options.sourceType);
             const startTime = performance.now();
             try {
-                const response = await this._connection.eventSequences.append({
+                const concurrencyScope = options?.concurrencyScope ?? (routing
+                    ? await deriveConcurrencyScope(routing, eventSourceId, options?.streamId, this.tailReader)
+                    : undefined);
+                const request = {
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     CorrelationId: toContractsGuid(correlationId),
-                    EventSourceType: options?.sourceType,
+                    EventSourceType: routing?.sourceType ?? options?.sourceType,
                     EventSourceId: eventSourceId,
-                    EventStreamType: options?.streamType,
+                    EventStreamType: routing?.streamType ?? options?.streamType,
                     EventStreamId: options?.streamId,
                     EventType: {
                         Id: eventType.id.value,
@@ -109,11 +118,16 @@ export class EventSequence implements IEventSequence {
                         Properties: { ...c.properties }
                     })),
                     CausedBy: toContractsCausedBy(identity),
-                    ConcurrencyScope: this.toContractConcurrencyScope(options?.concurrencyScope),
+                    ConcurrencyScope: this.toContractConcurrencyScope(concurrencyScope),
+                    EventSource: routing?.eventSource,
                     Tags: tags,
                     Occurred: options?.occurred === undefined ? undefined : { Value: options.occurred.toISOString() },
                     Subject: subject ?? eventSourceId
-                });
+                };
+                // Named tags travel on the dedicated call so a kernel without support rejects them instead of dropping them.
+                const response = namedTags.length === 0
+                    ? await this._connection.eventSequences.append(request)
+                    : await this._connection.eventSequences.appendWithNamedTags({ ...request, NamedTags: toContractsNamedTags(namedTags) });
 
                 const appendResponse = ensureCommandResponse('append event', response);
                 const durationInSeconds = (performance.now() - startTime) / 1000;
@@ -137,7 +151,7 @@ export class EventSequence implements IEventSequence {
 
                 if (this.appendOperations.hasSubscribers) {
                     this.appendOperations.publish([createAppendNotification(eventSourceId, event, result,
-                        correlationId.toString(), mapAppendNotificationCausation(causationChain), tags)]);
+                        correlationId.toString(), mapAppendNotificationCausation(causationChain), tags, undefined, namedTags)]);
                 }
 
                 return result;
@@ -159,9 +173,14 @@ export class EventSequence implements IEventSequence {
         eventsOrOptions?: object[] | AppendOptions,
         options?: AppendOptions
     ): Promise<AppendResult[]> {
-        const { eventsForEventSourceIds, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend } =
+        const { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend, namedTags } =
             prepareBatchAppend(eventSourceIdOrEvents, eventsOrOptions, options);
 
+        const wireEvents: Array<(typeof eventsToAppend)[number] & { EventSource?: string }> = eventsToAppend;
+        const routings = eventsForEventSourceIds.map(event => resolveBatchRouting(this._eventSources, event, appendOptions));
+        ensureNamedTagBatchIsSupported(namedTags.some(tagsForEvent => tagsForEvent.length > 0), routings.some(routing => routing !== undefined));
+        const explicitIds = new Set([...concurrencyScopes].filter(([, scope]) => scope !== undefined).map(([id]) => id));
+        const derivedGuards = planDerivedGuards(routings, eventsForEventSourceIds, appendOptions?.streamId, explicitIds);
         const distinctEventSourceIds = [...new Set(eventsForEventSourceIds.map(_ => _.eventSourceId))];
 
         const batchMetricAttributes = {
@@ -178,12 +197,24 @@ export class EventSequence implements IEventSequence {
             setTelemetryAttribute(span, 'eventCount', eventsForEventSourceIds.length);
             const startTime = performance.now();
             try {
-                const response = await this._connection.eventSequences.appendManyForEventSources({
+                routings.forEach((routing, index) => {
+                    if (!routing) return;
+                    wireEvents[index] = {
+                        ...wireEvents[index],
+                        EventSourceType: routing.sourceType,
+                        EventStreamType: routing.streamType ?? wireEvents[index].EventStreamType,
+                        EventSource: routing.eventSource
+                    };
+                });
+                for (const [id, { routing, streamId }] of derivedGuards) {
+                    concurrencyScopes.set(id, await deriveConcurrencyScope(routing, id, streamId, this.tailReader));
+                }
+                const request = {
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
                     CorrelationId: toContractsGuid(correlationId),
-                    Events: eventsToAppend,
+                    Events: wireEvents,
                     Causation: batchCausationChain.map(c => ({
                         Occurred: { Value: c.occurred.toISOString() },
                         Type: c.type.name,
@@ -194,7 +225,13 @@ export class EventSequence implements IEventSequence {
                         EventSourceId: eventSourceId,
                         Scope: this.toContractConcurrencyScope(scope)
                     }))
-                });
+                };
+                const response = namedTags.every(tagsForEvent => tagsForEvent.length === 0)
+                    ? await this._connection.eventSequences.appendManyForEventSources(request)
+                    : await this._connection.eventSequences.appendManyForEventSourcesWithNamedTags({
+                        ...request,
+                        Events: wireEvents.map((wireEvent, index) => ({ ...wireEvent, NamedTags: toContractsNamedTags(namedTags[index]) }))
+                    });
 
                 const appendManyResponse = ensureCommandResponse('append many events', response);
                 const durationInSeconds = (performance.now() - startTime) / 1000;
@@ -242,7 +279,7 @@ export class EventSequence implements IEventSequence {
                     this.appendOperations.publish(result.map((appendResult: AppendResult, index: number) => {
                         const { eventSourceId, event } = eventsForEventSourceIds[index];
                         return createAppendNotification(eventSourceId, event, appendResult, correlationId.toString(),
-                            causationEntries, eventsToAppend[index].Tags, occurredAt);
+                            causationEntries, eventsToAppend[index].Tags, occurredAt, namedTags[index]);
                     }));
                 }
 
@@ -598,6 +635,9 @@ export class EventSequence implements IEventSequence {
         }
     }
 
+    private readonly tailReader = (source?: string, sourceType?: string, streamType?: string, streamId?: string) =>
+        this.getTailSequenceNumber(source, sourceType, streamType, streamId);
+
     private toContractConcurrencyScope(scope?: ConcurrencyScope) {
         return {
             SequenceNumber: scope?.sequenceNumber === EventSequenceNumber.beforeFirst.value
@@ -617,6 +657,15 @@ export class EventSequence implements IEventSequence {
     }
 }
 
+/**
+ * Converts structured named tags into the sequence contract shape.
+ * @param namedTags - The validated named tags.
+ * @returns The wire named tags.
+ */
+function toContractsNamedTags(namedTags: readonly NamedTag[]): { Name: string; Value: string }[] {
+    return namedTags.map(tag => ({ Name: tag.name, Value: tag.value }));
+}
+
 /**
  * Converts an {@link Identity} into the CausedBy shape used by Chronicle contracts.
  * @param identity - The identity to convert.

package/eventSequences/ITransactionalEventSequence.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { TransactionalAppendOptions } from '../transactions/TransactionalAppendOptions.js';
 import { IUnitOfWork } from '../transactions/IUnitOfWork.js';
 
 /**
@@ -14,13 +15,15 @@ export interface ITransactionalEventSequence {
      * Adds a single event to the current unit of work.
      * @param eventSourceId - The identifier of the event source.
      * @param event - The event to append.
+     * @param options - Optional registered event source / stream routing and named tags.
      */
-    append(eventSourceId: string, event: object): Promise<void>;
+    append(eventSourceId: string, event: object, options?: TransactionalAppendOptions): Promise<void>;
 
     /**
      * Adds multiple events to the current unit of work.
      * @param eventSourceId - The identifier of the event source.
      * @param events - The events to append.
+     * @param options - Optional registered event source / stream routing and named tags applied to every event.
      */
-    appendMany(eventSourceId: string, events: object[]): Promise<void>;
+    appendMany(eventSourceId: string, events: object[], options?: TransactionalAppendOptions): Promise<void>;
 }

package/eventSequences/NamedTagsWithRegisteredEventSourceNotSupported.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Named-tag batches cannot preserve registered event source routing on the current kernel. */
+export class NamedTagsWithRegisteredEventSourceNotSupported extends Error {
+    constructor() {
+        super('Batches and unit-of-work commits cannot combine non-empty named tags with registered event sources: ' +
+            'the kernel named-tag batch operation drops registered event source routing. ' +
+            'Use single append calls instead. See https://github.com/Cratis/Chronicle/issues/4603.');
+        this.name = 'NamedTagsWithRegisteredEventSourceNotSupported';
+    }
+}

package/eventSequences/TransactionalEventSequence.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { TransactionalAppendOptions } from '../transactions/TransactionalAppendOptions.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { IUnitOfWork } from '../transactions/IUnitOfWork.js';
 import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager.js';
 import { IEventSequence } from './IEventSequence.js';
@@ -21,14 +23,16 @@ export class TransactionalEventSequence implements ITransactionalEventSequence {
     }
 
     /** @inheritdoc */
-    async append(eventSourceId: string, event: object): Promise<void> {
-        this.unitOfWork.addEvent(this._eventSequence.id, eventSourceId, event);
+    async append(eventSourceId: string, event: object, options?: TransactionalAppendOptions): Promise<void> {
+        this.unitOfWork.addEvent(this._eventSequence.id, eventSourceId, event, options);
     }
 
     /** @inheritdoc */
-    async appendMany(eventSourceId: string, events: object[]): Promise<void> {
+    async appendMany(eventSourceId: string, events: object[], options?: TransactionalAppendOptions): Promise<void> {
+        // Validate once up front so an invalid tag adds none of the events.
+        const shared = options?.namedTags === undefined ? options : { ...options, namedTags: mergeNamedTags(options.namedTags) };
         for (const event of events) {
-            this.unitOfWork.addEvent(this._eventSequence.id, eventSourceId, event);
+            this.unitOfWork.addEvent(this._eventSequence.id, eventSourceId, event, shared);
         }
     }
 }

package/eventSequences/createAppendNotification.ts

@@ -3,6 +3,7 @@
 
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { Tag } from '../events/Tag.js';
+import type { NamedTag } from '../events/NamedTag.js';
 import type { CausationEntry } from '../events/CausationEntry.js';
 import type { AppendResult } from './AppendResult.js';
 import type { AppendedEventWithResult } from './AppendedEventWithResult.js';
@@ -17,7 +18,7 @@ export function mapAppendNotificationCausation(chain: readonly Causation[]): Cau
 /** Maps a successful append into the client-side appendOperations notification shape. */
 export function createAppendNotification(
     eventSourceId: string, event: object, result: AppendResult, correlationId: string,
-    causation: CausationEntry[], tags: readonly string[], occurredAt = new Date()
+    causation: CausationEntry[], tags: readonly string[], occurredAt = new Date(), namedTags: readonly NamedTag[] = []
 ): AppendedEventWithResult {
     const eventType = getEventTypeFor(event.constructor);
     return {
@@ -25,7 +26,8 @@ export function createAppendNotification(
             context: {
                 sequenceNumber: result.sequenceNumber.value, eventSourceId, eventType, occurred: occurredAt, correlationId,
                 causation,
-                tags: tags.map(value => new Tag(value))
+                tags: tags.map(value => new Tag(value)),
+                namedTags: [...namedTags]
             },
             eventType,
             content: event as Record<string, unknown>

package/eventSequences/ensureNamedTagBatchIsSupported.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NamedTagsWithRegisteredEventSourceNotSupported } from './NamedTagsWithRegisteredEventSourceNotSupported.js';
+
+/** Rejects the combination before any RPC, even when tags and registered routing belong to different entries. */
+export function ensureNamedTagBatchIsSupported(hasNamedTags: boolean, hasRegisteredEventSource: boolean): void {
+    if (hasNamedTags && hasRegisteredEventSource) {
+        throw new NamedTagsWithRegisteredEventSourceNotSupported();
+    }
+}

package/eventSequences/for_EventSequence/against_a_kernel/when_appending_named_tags.integration.spec.ts

@@ -0,0 +1,107 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ObserverRunningState } from '@cratis/chronicle.contracts';
+import { ChronicleClient, ChronicleOptions, NamedTag, eventType, reactor, type AppendedEvent, type EventContext,
+    type IClientArtifactsProvider, type IEventStore } from '../../../index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+
+chai.should();
+function should(value: unknown): ReturnType<typeof chai.expect> {
+    return (value as { should: ReturnType<typeof chai.expect> }).should;
+}
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class NamedTagsItemImported {
+    @field(String) sku = '';
+}
+
+const delivered = new Map<string, EventContext>();
+@reactor()
+class NamedTagsImportTracker {
+    namedTagsItemImported(event: NamedTagsItemImported, context: EventContext) {
+        delivered.set(event.sku, context);
+    }
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [NamedTagsItemImported], reactors: [NamedTagsImportTracker], reducers: [], readModels: [], seeders: [],
+    constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+
+async function eventually(accept: () => boolean | Promise<boolean>, timeoutMs = 30_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (!await accept()) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+}
+
+const pairs = (context: { namedTags?: ReadonlyArray<NamedTag> }) => (context.namedTags ?? []).map(tag => `${tag.name}=${tag.value}`);
+const item = (sku: string) => Object.assign(new NamedTagsItemImported(), { sku });
+
+describe.skipIf(!connectionString && !process.env.CI)('when appending named tags against a kernel', () => {
+    const storeName = `NamedTags${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const source = randomUUID();
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let stored: Map<string, AppendedEvent>;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [], clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(storeName);
+        const connection = (store as unknown as { _connection: ChronicleConnection })._connection;
+        await eventually(async () => {
+            const observer = await connection.observers.getObserverInformation({ EventStore: storeName, Namespace: 'Default',
+                ObserverId: NamedTagsImportTracker.name, EventSequenceId: 'event-log' });
+            return observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active;
+        });
+
+        const single = await store.eventLog.append(source, item('single'), {
+            tags: ['import'],
+            namedTags: [new NamedTag('import-batch', 'b-1'), new NamedTag('import-batch', 'B-1'), new NamedTag('empty', ''),
+                new NamedTag('import-batch', 'b-1')]
+        });
+        should(single.isSuccess).be.true;
+        const batch = await store.eventLog.appendMany([
+            { eventSourceId: source, event: item('debit'), namedTags: [new NamedTag('side', 'debit')] },
+            { eventSourceId: source, event: item('credit'), namedTags: [new NamedTag('side', 'credit'), new NamedTag('transfer', 't-1')] }
+        ], { namedTags: [new NamedTag('transfer', 't-1')] });
+        should(batch.every(result => result.isSuccess)).be.true;
+        const untagged = await store.eventLog.append(source, item('untagged'));
+        should(untagged.isSuccess).be.true;
+
+        const unitOfWork = store.unitOfWorkManager.begin();
+        await store.eventLog.transactional.append(source, item('transactional'), { namedTags: [new NamedTag('unit', 'u-1')] });
+        await unitOfWork.commit();
+        should(unitOfWork.isSuccess).be.true;
+
+        const events = await store.eventLog.getForEventSourceIdAndEventTypes(source, [NamedTagsItemImported]);
+        stored = new Map(events.map(event => [(event.content as { sku: string }).sku, event]));
+        await eventually(() => delivered.has('transactional'));
+    });
+    afterAll(() => client?.dispose());
+
+    it('should round-trip distinct single-append named tags in order through a read', () =>
+        should(pairs(stored.get('single')!.context)).deep.equal(['import-batch=b-1', 'import-batch=B-1', 'empty=']));
+    it('should keep plain tags beside named tags', () =>
+        should(stored.get('single')!.context.tags.map(tag => tag.value)).deep.equal(['import']));
+    it('should store each batch event with its own tags followed by the shared tags', () => {
+        should(pairs(stored.get('debit')!.context)).deep.equal(['side=debit', 'transfer=t-1']);
+        should(pairs(stored.get('credit')!.context)).deep.equal(['side=credit', 'transfer=t-1']);
+    });
+    it('should store an untagged event with no named tags', () => should(pairs(stored.get('untagged')!.context)).deep.equal([]));
+    it('should store named tags added through a unit of work', () =>
+        should(pairs(stored.get('transactional')!.context)).deep.equal(['unit=u-1']));
+    it('should deliver the named tags to reactors in the event context', () => {
+        should(pairs(delivered.get('single')!)).deep.equal(['import-batch=b-1', 'import-batch=B-1', 'empty=']);
+        should(pairs(delivered.get('credit')!)).deep.equal(['side=credit', 'transfer=t-1']);
+        should(pairs(delivered.get('untagged')!)).deep.equal([]);
+    });
+});

package/eventSequences/for_EventSequence/when_appending_named_tags/given.fixture.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 { vi } from 'vitest';
+import { EventSequence, EventSequenceId } from '../../index.js';
+import { eventType } from '../../../events/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import type { IUnitOfWorkManager } from '../../../transactions/index.js';
+import { ConcurrencyDimensions, type IEventSources } from '../../../eventSources/index.js';
+
+export class Account {}
+
+/** A registered source, optionally requiring a derived tail read. */
+export function registered_sources(concurrency = ConcurrencyDimensions.none): IEventSources {
+    return {
+        getFor: () => ({ type: Account, name: 'Account', description: '', concurrency, streams: [] })
+    } as unknown as IEventSources;
+}
+
+export class NamedTagRecorded { constructor(readonly value = 'payload') {} }
+eventType('NamedTagRecorded')(NamedTagRecorded);
+
+/** An event sequence whose four append calls are recorded. */
+export function a_sequence(eventSources?: IEventSources) {
+    const single = { Response: { SequenceNumber: 0n, ConstraintViolations: [], Errors: [] } };
+    const batch = async (request: { Events: unknown[] }) =>
+        ({ Response: { SequenceNumbers: request.Events.map((_, index) => BigInt(index)), ConstraintViolations: [], Errors: [] } });
+    const append = vi.fn().mockResolvedValue(single);
+    const appendWithNamedTags = vi.fn().mockResolvedValue(single);
+    const appendManyForEventSources = vi.fn().mockImplementation(batch);
+    const appendManyForEventSourcesWithNamedTags = vi.fn().mockImplementation(batch);
+    const tailSequenceNumber = vi.fn().mockResolvedValue({ Data: { SequenceNumber: 0n } });
+    const connection = { eventSequences: { append, appendWithNamedTags, appendManyForEventSources, appendManyForEventSourcesWithNamedTags, tailSequenceNumber } } as unknown as ChronicleConnection;
+    return {
+        sequence: new EventSequence(EventSequenceId.eventLog, 'store', 'tenant', connection, {} as IUnitOfWorkManager, undefined, undefined, eventSources),
+        append, appendWithNamedTags, appendManyForEventSources, appendManyForEventSourcesWithNamedTags, tailSequenceNumber
+    };
+}

package/eventSequences/for_EventSequence/when_appending_named_tags/with_a_batch.spec.ts

@@ -0,0 +1,49 @@
+// 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 { AppendManyForEventSourcesWithNamedTagsRequest } from '@cratis/chronicle.contracts';
+import { NamedTag } from '../../../events/index.js';
+import { a_sequence, NamedTagRecorded } from './given.fixture.js';
+
+chai.should();
+
+describe('when appending a batch with per-event and shared named tags', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let request: AppendManyForEventSourcesWithNamedTagsRequest;
+    beforeEach(async () => {
+        calls = a_sequence();
+        await calls.sequence.appendMany([
+            { eventSourceId: 'from', event: new NamedTagRecorded(), namedTags: [new NamedTag('side', 'debit'), new NamedTag('transfer', 't-1')] },
+            { eventSourceId: 'to', event: new NamedTagRecorded(), namedTags: [new NamedTag('side', 'credit')] },
+            { eventSourceId: 'audit', event: new NamedTagRecorded() }
+        ], { namedTags: [new NamedTag('transfer', 't-1')] });
+        request = calls.appendManyForEventSourcesWithNamedTags.mock.calls[0][0];
+    });
+    it('should use the dedicated named-tag batch call', () => calls.appendManyForEventSources.mock.calls.should.have.lengthOf(0));
+    it('should send each event its own tags before the shared tags without duplicates', () =>
+        request.Events.map(event => event.NamedTags.map(tag => `${tag.Name}=${tag.Value}`)).should.deep.equal([
+            ['side=debit', 'transfer=t-1'], ['side=credit', 'transfer=t-1'], ['transfer=t-1']
+        ]));
+});
+
+describe('when appending many events for one source with shared named tags', () => {
+    let request: AppendManyForEventSourcesWithNamedTagsRequest;
+    beforeEach(async () => {
+        const calls = a_sequence();
+        await calls.sequence.appendMany('source', [new NamedTagRecorded(), new NamedTagRecorded()], { namedTags: [new NamedTag('import', 'i-1')] });
+        request = calls.appendManyForEventSourcesWithNamedTags.mock.calls[0][0];
+    });
+    it('should give every event the shared named tags', () =>
+        request.Events.map(event => event.NamedTags).should.deep.equal([[{ Name: 'import', Value: 'i-1' }], [{ Name: 'import', Value: 'i-1' }]]));
+});
+
+describe('when appending a batch without named tags', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence();
+        await calls.sequence.appendMany([{ eventSourceId: 'one', event: new NamedTagRecorded(), namedTags: [] }]);
+    });
+    it('should keep using the plain batch call', () => calls.appendManyForEventSources.mock.calls.should.have.lengthOf(1));
+    it('should not use the named-tag batch call', () => calls.appendManyForEventSourcesWithNamedTags.mock.calls.should.have.lengthOf(0));
+});

package/eventSequences/for_EventSequence/when_appending_named_tags/with_a_single_event.spec.ts

@@ -0,0 +1,47 @@
+// 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 { AppendWithNamedTagsRequest } from '@cratis/chronicle.contracts';
+import { NamedTag } from '../../../events/index.js';
+import type { AppendedEventWithResult } from '../../AppendedEventWithResult.js';
+import { a_sequence, NamedTagRecorded } from './given.fixture.js';
+
+chai.should();
+
+describe('when appending a single event with named tags', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let request: AppendWithNamedTagsRequest;
+    let notification: AppendedEventWithResult;
+    beforeEach(async () => {
+        calls = a_sequence();
+        const iterator = calls.sequence.appendOperations[Symbol.asyncIterator]();
+        const next = iterator.next();
+        await calls.sequence.append('source', new NamedTagRecorded(), {
+            tags: ['checkout'],
+            namedTags: [new NamedTag('session', 's-1'), new NamedTag('session', 's-1'), new NamedTag('channel', 'web')]
+        });
+        notification = (await next).value[0];
+        await iterator.return?.();
+        request = calls.appendWithNamedTags.mock.calls[0][0];
+    });
+    it('should use the dedicated named-tag call instead of the plain append', () => calls.append.mock.calls.should.have.lengthOf(0));
+    it('should send the distinct named tags in order', () =>
+        request.NamedTags.should.deep.equal([{ Name: 'session', Value: 's-1' }, { Name: 'channel', Value: 'web' }]));
+    it('should keep the plain tags beside the named tags', () => request.Tags.should.deep.equal(['checkout']));
+    it('should encode through the published contract', () =>
+        AppendWithNamedTagsRequest.decode(AppendWithNamedTagsRequest.encode(AppendWithNamedTagsRequest.fromPartial(request)).finish())
+            .NamedTags.should.have.lengthOf(2));
+    it('should carry the named tags on the append notification context', () =>
+        notification.event.context.namedTags!.map(tag => tag.name).should.deep.equal(['session', 'channel']));
+});
+
+describe('when appending a single event with an empty named tag list', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence();
+        await calls.sequence.append('source', new NamedTagRecorded(), { namedTags: [] });
+    });
+    it('should use the plain append call', () => calls.append.mock.calls.should.have.lengthOf(1));
+    it('should not use the named-tag call', () => calls.appendWithNamedTags.mock.calls.should.have.lengthOf(0));
+});