@cratis/chronicle 6.49.0 → 6.50.0

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/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';
+    }
+}

package/events/NamedTag.ts

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

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

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { InvalidNamedTag } from '../../InvalidNamedTag.js';
+import { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when constructing a named tag with invalid values', () => {
+    it('should reject an empty name', () => (() => new NamedTag('', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a whitespace name', () => (() => new NamedTag(' \t', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a name of only next-line characters like .NET', () => (() => new NamedTag('\u0085', 'value')).should.throw(InvalidNamedTag));
+    it('should reject a missing name', () => (() => new NamedTag(undefined as unknown as string, 'value')).should.throw(InvalidNamedTag));
+    it('should reject a null value', () => (() => new NamedTag('name', null as unknown as string)).should.throw(InvalidNamedTag));
+    it('should reject a non-string value', () => (() => new NamedTag('name', 42 as unknown as string)).should.throw(InvalidNamedTag));
+});

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

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when constructing a named tag with a name and an empty value', () => {
+    const tag = new NamedTag('import-batch', '');
+    it('should keep the name exactly', () => tag.name.should.equal('import-batch'));
+    it('should keep the empty value', () => tag.value.should.equal(''));
+    it('should be immutable', () => Object.isFrozen(tag).should.be.true);
+});
+
+describe('when comparing named tags', () => {
+    it('should treat the same name and value as equal', () => new NamedTag('a', 'B').equals(new NamedTag('a', 'B')).should.be.true);
+    it('should compare values case-sensitively', () => new NamedTag('a', 'B').equals(new NamedTag('a', 'b')).should.be.false);
+});

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

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

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

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { InvalidNamedTag } from '../../InvalidNamedTag.js';
+import { mergeNamedTags } from '../../mergeNamedTags.js';
+import type { NamedTag } from '../../NamedTag.js';
+
+chai.should();
+
+describe('when merging named tags with invalid entries', () => {
+    it('should reject a null element', () => (() => mergeNamedTags([null as unknown as NamedTag])).should.throw(InvalidNamedTag));
+    it('should reject a plain object with a blank name', () =>
+        (() => mergeNamedTags([{ name: ' ', value: 'x' } as NamedTag])).should.throw(InvalidNamedTag));
+    it('should reject a string instead of a collection', () =>
+        (() => mergeNamedTags('name' as unknown as NamedTag[])).should.throw(InvalidNamedTag));
+});

package/events/for_toClientEventContext/when_converting_named_tags.spec.ts

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

package/events/index.ts

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

package/events/mergeNamedTags.ts

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

package/events/toClientEventContext.ts

@@ -8,6 +8,7 @@ import { EventType } from './EventType.js';
 import { EventTypeGeneration } from './EventTypeGeneration.js';
 import { EventTypeId } from './EventTypeId.js';
 import { Tag } from './Tag.js';
+import { NamedTag } from './NamedTag.js';
 import type { WireEventContext } from './WireEventContext.js';
 
 /** Converts kernel metadata identically for reads, reactors, and reducers. */
@@ -37,7 +38,8 @@ export function toClientEventContext(context: WireEventContext): EventContext {
             occurred: causation.Occurred ? new Date(causation.Occurred.Value) : undefined,
             properties: { ...causation.Properties }
         })),
-        tags: (context.Tags ?? []).map(value => new Tag(value))
+        tags: (context.Tags ?? []).map(value => new Tag(value)),
+        namedTags: (context.NamedTags ?? []).map(tag => new NamedTag(tag.Name, tag.Value))
     };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.49.0",
+    "version": "6.50.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -178,7 +178,7 @@
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.16.0",
-        "@cratis/chronicle.contracts": "19.30.0",
+        "@cratis/chronicle.contracts": "19.31.10",
         "@grpc/grpc-js": "^1.14.5",
         "@opentelemetry/api": "^1.9.1",
         "glob": "^13.0.6",
@@ -188,14 +188,14 @@
         "undici": "^8.11.2"
     },
     "devDependencies": {
-        "@cratis/fundamentals": "7.20.0",
+        "@cratis/fundamentals": "7.22.4",
         "@opentelemetry/context-async-hooks": "2.11.0",
         "@opentelemetry/core": "2.11.0",
         "@opentelemetry/instrumentation-grpc": "0.222.0",
         "@opentelemetry/instrumentation-http": "0.222.0",
         "@opentelemetry/sdk-metrics": "2.11.0",
         "@opentelemetry/sdk-trace-base": "2.11.0",
-        "@types/node": "^26.6.3",
+        "@types/node": "^26.6.4",
         "@typescript/native": "npm:typescript@^7.0.2",
         "esbuild": "^0.28.2",
         "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -203,6 +203,6 @@
         "vitest": "^5.0.3"
     },
     "peerDependencies": {
-        "@cratis/fundamentals": "^7.20.0"
+        "@cratis/fundamentals": "^7.22.4"
     }
 }

package/projections/eventContextPropertyExpression.ts

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

package/testing/InProcessEventSequence.ts

@@ -17,7 +17,7 @@ import { EventTypeId } from '../events/EventTypeId.js';
 import { EventTypeGeneration } from '../events/EventTypeGeneration.js';
 import { Identity } from '../identity/Identity.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
-import { singleAppendRoute } from './singleAppendRoute.js';
+import { hasNamedTags, singleAppendRoute } from './singleAppendRoute.js';
 import type { AppendResult } from '../eventSequences/AppendResult.js';
 import type { AppendedEventWithResult } from '../eventSequences/AppendedEventWithResult.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
@@ -215,7 +215,8 @@ export class InProcessEventSequence implements IEventSequence {
                     subject: resolveStoredSubject(prepared.subject, eventSourceId), hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
                     eventType: prepared.eventType, occurred, correlationId: prepared.correlationId.toString(),
                     causation: prepared.causationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
-                    tags: prepared.tags.map(tag => new Tag(tag))
+                    tags: prepared.tags.map(tag => new Tag(tag)),
+                    namedTags: []
                 }
             };
             const violations = this.validateConstraints([...this._history, ...(this._stagedSeeds ?? [])], [stored]);
@@ -254,10 +255,13 @@ export class InProcessEventSequence implements IEventSequence {
             for (const entry of entries) {
                 if (typeof sourceOrEvents === 'string') break;
                 if (!entry || typeof entry !== 'object' || Reflect.ownKeys(entry).some(key =>
-                    !['eventSourceId', 'event', 'eventSourceType', 'eventStreamType', 'eventStreamId', 'subject', 'occurred', 'tags'].includes(String(key)))) {
+                    !['eventSourceId', 'event', 'eventSourceType', 'eventStreamType', 'eventStreamId', 'subject', 'occurred', 'tags', 'namedTags'].includes(String(key)))) {
                     throw this.unsupported('appendMany.entry', this.id.value, 'Unrecognized per-entry metadata.');
                 }
                 const individual = entry as EventForEventSourceId;
+                if (hasNamedTags(individual.namedTags)) {
+                    throw this.unsupported('appendMany.namedTags', this.id.value, 'Named tags are not fixture-backed.');
+                }
                 if (individual.occurred !== undefined) this.checkedDate(individual.occurred, 'appendMany.occurred');
                 if (individual.subject !== undefined && individual.subject !== null && typeof individual.subject !== 'string') {
                     throw this.unsupported('appendMany.subject', this.id.value, 'Subject must be a string.');
@@ -271,7 +275,8 @@ export class InProcessEventSequence implements IEventSequence {
             try {
                 const batchOptions: AppendOptions | undefined = shared?.correlationId === undefined && this._correlationId
                     ? { correlationId: this._correlationId(), sourceType: shared?.sourceType, streamType: shared?.streamType,
-                        streamId: shared?.streamId, subject: shared?.subject, occurred: shared?.occurred, tags: shared?.tags }
+                        streamId: shared?.streamId, subject: shared?.subject, occurred: shared?.occurred, tags: shared?.tags,
+                        namedTags: shared?.namedTags }
                     : shared;
                 if (batchOptions?.correlationId !== undefined) this.validateGuid(batchOptions.correlationId, 'appendMany.correlationId');
                 prepared = typeof sourceOrEvents === 'string'
@@ -318,7 +323,8 @@ export class InProcessEventSequence implements IEventSequence {
                     eventStreamId: wire.EventStreamId || 'Default', subject: resolveStoredSubject(wire.Subject, eventSourceId), hash, causedBy: identity,
                     observationState: EventObservationState.Initial, eventType, occurred, correlationId: correlationId.toString(),
                     causation: batchCausationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
-                    tags: wire.Tags.map(tag => new Tag(tag))
+                    tags: wire.Tags.map(tag => new Tag(tag)),
+                    namedTags: []
                 } };
                 return { stored, result: this.success(sequenceNumber, event.constructor.name) };
             });
@@ -411,7 +417,10 @@ export class InProcessEventSequence implements IEventSequence {
         if (!options || typeof options !== 'object' || Array.isArray(options)) {
             throw this.unsupported('appendMany.options', this.id.value, 'Append options must be an object.');
         }
-        const allowed = ['correlationId', 'sourceType', 'streamType', 'streamId', 'subject', 'occurred', 'tags'];
+        if (hasNamedTags(options.namedTags)) {
+            throw this.unsupported('appendMany.namedTags', this.id.value, 'Named tags are not fixture-backed.');
+        }
+        const allowed = ['correlationId', 'sourceType', 'streamType', 'streamId', 'subject', 'occurred', 'tags', 'namedTags'];
         if (Reflect.ownKeys(options).some(key => !allowed.includes(String(key))) ||
             options.concurrencyScope !== undefined || options.concurrencyScopes !== undefined || options.eventSourceId !== undefined) {
             throw this.unsupported('appendMany.options', this.id.value, 'Concurrency and unrecognized metadata are not fixture-backed.');
@@ -492,7 +501,8 @@ export class InProcessEventSequence implements IEventSequence {
             context: { ...event.context, eventType, occurred: new Date(event.context.occurred),
                 causedBy: causedBy && new Identity(causedBy.subject, causedBy.name, causedBy.userName, causedBy.onBehalfOf),
                 causation: event.context.causation.map(item => ({ ...item, occurred: item.occurred && new Date(item.occurred), properties: { ...item.properties } })),
-                tags: event.context.tags.map(item => new Tag(item.value)) }
+                tags: event.context.tags.map(item => new Tag(item.value)),
+                namedTags: [...(event.context.namedTags ?? [])] }
         };
     }
 

package/testing/ReactorScenario.ts

@@ -13,11 +13,13 @@ import type { AppendedEvent } from '../events/AppendedEvent.js';
 import type { EventContext } from '../events/EventContext.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
 import { getDeclaredEventStreamTypeFor, getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import { ensureNamedTagBatchIsSupported } from '../eventSequences/ensureNamedTagBatchIsSupported.js';
 import { EventStoreName } from '../EventStoreName.js';
 import { EventStoreNamespaceName } from '../EventStoreNamespaceName.js';
 import type { IEventStore } from '../IEventStore.js';
@@ -297,6 +299,10 @@ export class ReactorScenario {
             throw new UnsupportedReactorOperation('handler.return', this._reactor.name,
                 'Only registered events and production EventForEventSourceId wrappers may be recorded; commands and unknown values are unsupported.');
         }
+        // Production validates named tags before appending, failing the delivery on an invalid tag; so does recording.
+        for (const target of events) mergeNamedTags(target.namedTags);
+        ensureNamedTagBatchIsSupported(events.some(event => mergeNamedTags(event.namedTags).length > 0),
+            events.some(event => event.eventSource !== undefined));
         for (const target of events) {
             this._effects.push(Object.freeze({ kind: 'event', value: target.event, target, triggeringContext: context,
                 handler, deliveryIndex }));

package/testing/for_EventScenario/when_appending_named_tags/with_named_tags.spec.ts

@@ -0,0 +1,48 @@
+// 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 { NamedTag } from '../../../events/NamedTag.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+import { artifacts, Claim, createEvents, rejection } from '../given/routed_scenario.fixture.js';
+
+chai.should();
+const namedTags = [new NamedTag('batch', 'b-1')];
+
+describe('when appending a single event with named tags in an event scenario', () => {
+    let scenario: EventScenario;
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        scenario = createEvents();
+        error = await rejection(() => scenario.append('source', new Claim('one'), { namedTags }));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('append.namedTags'));
+    it('should not append the event', () => scenario.appendedEvents.should.have.lengthOf(0));
+});
+
+describe('when appending a batch with shared named tags in an event scenario', () => {
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        error = await rejection(() => createEvents().appendMany('source', [new Claim('one')], { namedTags }));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('appendMany.namedTags'));
+});
+
+describe('when appending a batch entry with named tags in an event scenario', () => {
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        error = await rejection(() => createEvents().appendMany([{ eventSourceId: 'source', event: new Claim('one'), namedTags }]));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('appendMany.namedTags'));
+});
+
+describe('when appending with an empty named tag list in an event scenario', () => {
+    let scenario: EventScenario;
+    beforeEach(async () => {
+        scenario = new EventScenario({ artifacts });
+        await scenario.append('source', new Claim('one'), { namedTags: [] });
+    });
+    it('should append the event', () => scenario.appendedEvents.should.have.lengthOf(1));
+    it('should expose an empty named tag list on the stored context like a kernel delivery', () =>
+        scenario.appendedEvents[0].context.namedTags!.should.deep.equal([]));
+});