@cratis/chronicle 6.49.0 → 6.50.0

package/eventSequences/EventForEventSourceId.ts

@@ -3,6 +3,7 @@
 
 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.
@@ -36,6 +37,12 @@ export interface EventForEventSourceId {
      */
     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.

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';
@@ -50,6 +51,7 @@ 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
@@ -75,7 +77,7 @@ export class EventSequence implements IEventSequence {
     /** @inheritdoc */
     async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
         const routing = resolveSingleRouting(this._eventSources, options);
-        const { eventType, correlationId, content, tags, causationChain, identity, subject } = prepareSingleAppend(event, options);
+        const { eventType, correlationId, content, tags, namedTags, causationChain, identity, subject } = prepareSingleAppend(event, options);
 
         const sequenceMetricAttributes = {
             [names.attributes.eventStore]: this._eventStoreName,
@@ -95,7 +97,7 @@ export class EventSequence implements IEventSequence {
                 const concurrencyScope = options?.concurrencyScope ?? (routing
                     ? await deriveConcurrencyScope(routing, eventSourceId, options?.streamId, this.tailReader)
                     : undefined);
-                const response = await this._connection.eventSequences.append({
+                const request = {
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
@@ -121,7 +123,11 @@ export class EventSequence implements IEventSequence {
                     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;
@@ -145,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;
@@ -167,11 +173,12 @@ export class EventSequence implements IEventSequence {
         eventsOrOptions?: object[] | AppendOptions,
         options?: AppendOptions
     ): Promise<AppendResult[]> {
-        const { eventsForEventSourceIds, appendOptions, 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))];
@@ -202,7 +209,7 @@ export class EventSequence implements IEventSequence {
                 for (const [id, { routing, streamId }] of derivedGuards) {
                     concurrencyScopes.set(id, await deriveConcurrencyScope(routing, id, streamId, this.tailReader));
                 }
-                const response = await this._connection.eventSequences.appendManyForEventSources({
+                const request = {
                     EventStore: this._eventStoreName,
                     Namespace: this._namespace,
                     EventSequenceId: this.id.value,
@@ -218,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;
@@ -266,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]);
                     }));
                 }
 
@@ -644,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,7 +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 { TransactionalEventRouting } from '../transactions/TransactionalEventRouting.js';
+import type { TransactionalAppendOptions } from '../transactions/TransactionalAppendOptions.js';
 import { IUnitOfWork } from '../transactions/IUnitOfWork.js';
 
 /**
@@ -15,15 +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 routing - Optional registered event source / stream routing.
+     * @param options - Optional registered event source / stream routing and named tags.
      */
-    append(eventSourceId: string, event: object, routing?: TransactionalEventRouting): 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 routing - Optional registered event source / stream routing applied to every event.
+     * @param options - Optional registered event source / stream routing and named tags applied to every event.
      */
-    appendMany(eventSourceId: string, events: object[], routing?: TransactionalEventRouting): 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,7 +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 { TransactionalEventRouting } from '../transactions/TransactionalEventRouting.js';
+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';
@@ -22,14 +23,16 @@ export class TransactionalEventSequence implements ITransactionalEventSequence {
     }
 
     /** @inheritdoc */
-    async append(eventSourceId: string, event: object, routing?: TransactionalEventRouting): Promise<void> {
-        this.unitOfWork.addEvent(this._eventSequence.id, eventSourceId, event, routing);
+    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[], routing?: TransactionalEventRouting): 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, routing);
+            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));
+});

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

@@ -0,0 +1,36 @@
+// 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 { InvalidNamedTag, type NamedTag } from '../../../events/index.js';
+import { a_sequence, NamedTagRecorded } from './given.fixture.js';
+
+chai.should();
+const blank = { name: '', value: 'x' } as NamedTag;
+
+describe('when appending a single event with an invalid named tag', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_sequence();
+        error = await calls.sequence.append('source', new NamedTagRecorded(), { namedTags: [blank] }).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not call the kernel', () =>
+        (calls.append.mock.calls.length + calls.appendWithNamedTags.mock.calls.length).should.equal(0));
+});
+
+describe('when appending a batch where one entry has an invalid named tag', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_sequence();
+        error = await calls.sequence.appendMany([
+            { eventSourceId: 'one', event: new NamedTagRecorded() },
+            { eventSourceId: 'two', event: new NamedTagRecorded(), namedTags: [null as unknown as NamedTag] }
+        ]).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not append any of the events', () =>
+        (calls.appendManyForEventSources.mock.calls.length + calls.appendManyForEventSourcesWithNamedTags.mock.calls.length).should.equal(0));
+});

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

@@ -0,0 +1,74 @@
+// 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 { ConcurrencyDimensions } from '../../../eventSources/index.js';
+import { NamedTag } from '../../../events/index.js';
+import { NamedTagsWithRegisteredEventSourceNotSupported, type AppendOptions, type EventForEventSourceId } from '../../index.js';
+import { Account, a_sequence, NamedTagRecorded, registered_sources } from './given.fixture.js';
+
+chai.should();
+const namedTags = [new NamedTag('batch', 'b-1')];
+const entry = (options: Partial<EventForEventSourceId> = {}): EventForEventSourceId =>
+    ({ eventSourceId: 'source', event: new NamedTagRecorded(), ...options });
+
+const batches: Array<{ description: string; events: EventForEventSourceId[]; options?: AppendOptions }> = [
+    { description: 'tags and a registered source on the same entry', events: [entry({ eventSource: Account, namedTags })] },
+    { description: 'a tagged entry before an untagged registered entry', events: [entry({ namedTags }), entry({ eventSource: 'Account' })] },
+    { description: 'an untagged registered entry before a tagged entry', events: [entry({ eventSource: 'Account' }), entry({ namedTags })] },
+    { description: 'shared tags and a registered entry', events: [entry({ eventSource: 'Account' })], options: { namedTags } },
+    { description: 'per-entry tags and a shared registered source', events: [entry({ namedTags })], options: { eventSource: Account } }
+];
+
+for (const batch of batches) {
+    describe(`when appending a batch with ${batch.description}`, () => {
+        let calls: ReturnType<typeof a_sequence>;
+        let error: unknown;
+        beforeEach(async () => {
+            calls = a_sequence(registered_sources(ConcurrencyDimensions.eventSourceId));
+            error = await calls.sequence.appendMany(batch.events, batch.options).catch(caught => caught);
+        });
+        it('should reject with the typed unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should explain the kernel limitation', () => (error as Error).message.should.contain('drops registered event source routing'));
+        it('should link to the kernel issue', () => (error as Error).message.should.contain('https://github.com/Cratis/Chronicle/issues/4603'));
+        it('should not send a plain batch', () => calls.appendManyForEventSources.mock.calls.should.have.lengthOf(0));
+        it('should not send a named-tag batch', () => calls.appendManyForEventSourcesWithNamedTags.mock.calls.should.have.lengthOf(0));
+        it('should not read a tail to derive a guard', () => calls.tailSequenceNumber.mock.calls.should.have.lengthOf(0));
+        it('should not fall back to single appends', () =>
+            [...calls.append.mock.calls, ...calls.appendWithNamedTags.mock.calls].should.have.lengthOf(0));
+    });
+}
+
+describe('when appending a same-source batch with shared named tags and registered routing', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const calls = a_sequence(registered_sources());
+        error = await calls.sequence.appendMany('source', [new NamedTagRecorded()], { eventSource: Account, namedTags }).catch(caught => caught);
+    });
+    it('should reject with the typed unsupported combination error', () =>
+        (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+});
+
+describe('when appending a registered-source batch with empty named tags', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence(registered_sources());
+        await calls.sequence.appendMany([entry({ eventSource: Account, namedTags: [] })], { namedTags: [] });
+    });
+    it('should retain registered routing on the plain batch call', () =>
+        calls.appendManyForEventSources.mock.calls[0][0].Events[0].EventSource.should.equal('Account'));
+    it('should not send a named-tag batch', () => calls.appendManyForEventSourcesWithNamedTags.mock.calls.should.have.lengthOf(0));
+});
+
+describe('when appending a single event with named tags and a registered source', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence(registered_sources());
+        await calls.sequence.append('source', new NamedTagRecorded(), { eventSource: Account, namedTags });
+    });
+    it('should retain registered routing on the dedicated single append call', () =>
+        calls.appendWithNamedTags.mock.calls[0][0].EventSource.should.equal('Account'));
+    it('should retain the named tags on the single append', () =>
+        calls.appendWithNamedTags.mock.calls[0][0].NamedTags.should.deep.equal([{ Name: 'batch', Value: 'b-1' }]));
+});