@cratis/chronicle 6.49.0 → 6.51.0

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 append metadata (routing, subject, occurrence time, tags, named tags, concurrency scope) kept with the event until commit.
      */
-    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 append metadata (routing, subject, occurrence time, tags, named tags, concurrency scope) 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' }]));
+});

package/eventSequences/for_TransactionalEventSequence/when_appending_many_with_named_tags.spec.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { InvalidNamedTag, NamedTag } from '../../events/index.js';
+import type { IUnitOfWorkManager } from '../../transactions/index.js';
+import { EventSequenceId } from '../EventSequenceId.js';
+import type { IEventSequence } from '../IEventSequence.js';
+import { TransactionalEventSequence } from '../TransactionalEventSequence.js';
+
+chai.should();
+
+function a_transactional_sequence() {
+    const addEvent = vi.fn();
+    const manager = { current: { addEvent } } as unknown as IUnitOfWorkManager;
+    return { sequence: new TransactionalEventSequence({ id: EventSequenceId.eventLog } as IEventSequence, manager), addEvent };
+}
+
+describe('when appending many events transactionally with shared named tags', () => {
+    let addEvent: ReturnType<typeof vi.fn>;
+    beforeEach(async () => {
+        const given = a_transactional_sequence();
+        addEvent = given.addEvent;
+        await given.sequence.appendMany('source', [{ one: 1 }, { two: 2 }], { eventSource: 'Account', namedTags: [new NamedTag('import', 'i-1')] });
+    });
+    it('should add every event with the shared named tags and routing', () =>
+        addEvent.mock.calls.map(call => [call[3].eventSource, call[3].namedTags.map((tag: NamedTag) => tag.value)])
+            .should.deep.equal([['Account', ['i-1']], ['Account', ['i-1']]]));
+});
+
+describe('when appending many events transactionally with an invalid named tag', () => {
+    let addEvent: ReturnType<typeof vi.fn>;
+    let error: unknown;
+    beforeEach(async () => {
+        const given = a_transactional_sequence();
+        addEvent = given.addEvent;
+        error = await given.sequence.appendMany('source', [{ one: 1 }], { namedTags: [{ name: '', value: '' } as NamedTag] }).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not add any event', () => addEvent.mock.calls.should.have.lengthOf(0));
+});

package/eventSequences/for_TransactionalEventSequence/when_appending_many_with_options.spec.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi, type Mock } from 'vitest';
+import { EventSequenceId } from '../EventSequenceId.js';
+import type { IEventSequence } from '../IEventSequence.js';
+import type { IUnitOfWorkManager } from '../../transactions/IUnitOfWorkManager.js';
+import type { TransactionalAppendOptions } from '../../transactions/TransactionalAppendOptions.js';
+import { TransactionalEventSequence } from '../TransactionalEventSequence.js';
+
+chai.should();
+
+describe('when appending many with options to a transactional event sequence', () => {
+    const outbox = new EventSequenceId('outbox');
+    const options: TransactionalAppendOptions = { subject: 'subject-1', occurred: new Date(0), tags: ['t'], concurrencyScope: { sequenceNumber: 2n } };
+    let addEvent: Mock;
+
+    beforeEach(async () => {
+        addEvent = vi.fn();
+        const manager = { current: { addEvent } } as unknown as IUnitOfWorkManager;
+        const sequence = new TransactionalEventSequence({ id: outbox } as unknown as IEventSequence, manager);
+        await sequence.appendMany('a-1', [{ order: 0 }, { order: 1 }], options);
+    });
+
+    it('should enroll every event with the options in order', () => addEvent.mock.calls.should.deep.equal([
+        [outbox, 'a-1', { order: 0 }, options],
+        [outbox, 'a-1', { order: 1 }, options]
+    ]));
+});

package/eventSequences/index.ts

@@ -10,6 +10,7 @@ export type { AppendResult } from './AppendResult.js';
 export type { AppendedEventWithResult } from './AppendedEventWithResult.js';
 export type { AppendOptions } from './AppendOptions.js';
 export { CompleteStreamError } from './CompleteStreamError.js';
+export { NamedTagsWithRegisteredEventSourceNotSupported } from './NamedTagsWithRegisteredEventSourceNotSupported.js';
 export type { CompleteStreamResult } from './CompleteStreamResult.js';
 export type { ConcurrencyScope } from './ConcurrencyScope.js';
 export type { EventForEventSourceId } from './EventForEventSourceId.js';

package/eventSequences/prepareBatchAppend.ts

@@ -7,6 +7,7 @@ import { correlationIdManager } from '../correlation/index.js';
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { mergeTags } from '../events/mergeTags.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { identityProvider } from '../identity/index.js';
 import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import type { AppendOptions } from './AppendOptions.js';
@@ -45,6 +46,8 @@ export function prepareBatchAppend(
     for (const { eventSourceId } of eventsForEventSourceIds) {
         if (!concurrencyScopes.has(eventSourceId)) concurrencyScopes.set(eventSourceId, appendOptions?.concurrencyScope);
     }
+    // Validate every event's named tags before anything is sent; the order of entries is preserved.
+    const namedTags = eventsForEventSourceIds.map(({ namedTags: instanceNamedTags }) => mergeNamedTags(instanceNamedTags, appendOptions?.namedTags));
     const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event, eventStreamType, eventStreamId, eventSourceType, subject, occurred, tags: instanceTags }) => {
         const eventType = getEventTypeFor(event.constructor as Function);
         const tags = mergeTags(getTagsFor(event.constructor as Function), instanceTags, appendOptions?.tags);
@@ -60,5 +63,5 @@ export function prepareBatchAppend(
             Subject: subject ?? appendOptions?.subject ?? resolveEventSubject(event) ?? eventSourceId
         };
     });
-    return { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend };
+    return { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend, namedTags };
 }

package/eventSequences/prepareSingleAppend.ts

@@ -5,6 +5,7 @@ import { Guid, JsonSerializer } from '@cratis/fundamentals';
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { mergeTags } from '../events/mergeTags.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { identityProvider } from '../identity/index.js';
 import { causationManager, CausationType } from '../auditing/index.js';
 import { correlationIdManager } from '../correlation/index.js';
@@ -20,8 +21,9 @@ export function prepareSingleAppend(event: object, options?: AppendOptions) {
     const subject = options?.subject ?? resolveEventSubject(event);
     const content = JsonSerializer.serialize(event);
     const tags = mergeTags(getTagsFor(event.constructor as Function), options?.tags);
+    const namedTags = mergeNamedTags(options?.namedTags);
     const causationChain = causationManager.run(CausationType.appendEvent, { eventType: eventType.id.value },
         () => causationManager.getCurrentChain());
     const identity = identityProvider.getCurrent();
-    return { eventType, correlationId, content, tags, causationChain, identity, subject };
+    return { eventType, correlationId, content, tags, namedTags, causationChain, identity, subject };
 }

package/events/EventContext.ts

@@ -4,6 +4,7 @@
 import { EventType } from './EventType.js';
 import { CausationEntry } from './CausationEntry.js';
 import { Tag } from './Tag.js';
+import type { NamedTag } from './NamedTag.js';
 import type { Identity } from '../identity/Identity.js';
 
 /**
@@ -63,4 +64,11 @@ export interface EventContext {
 
     /** The tags the event carries. */
     readonly tags: ReadonlyArray<Tag>;
+
+    /**
+     * The structured named tags the event carries, in the order the kernel stored them.
+     * Always present on events read from or delivered by the kernel (empty when the event has none);
+     * optional so that contexts constructed by hand remain valid.
+     */
+    readonly namedTags?: ReadonlyArray<NamedTag>;
 }

package/events/InvalidNamedTag.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The error that is thrown when a named tag has a blank name or a non-string value, or a named tag
+ * collection contains an entry that is not a named tag. Mirrors the .NET client's `InvalidNamedTag`.
+ */
+export class InvalidNamedTag extends Error {
+    constructor() {
+        super('Named tags require a nonblank name and a non-null value; named tag collections cannot contain null elements.');
+        this.name = 'InvalidNamedTag';
+    }
+}