@cratis/chronicle 6.3.2 → 6.5.0

package/dist/types/propertyDecoratorMetadata.js

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import 'reflect-metadata';
+import { getStandardMetadata } from './standardDecoratorMetadata.js';
+/** Dispatches class and field decorations while retaining the legacy invocation shape. */
+export function decorateClassOrProperty(legacy) {
+    const propertyDecorator = decorateProperty(legacy);
+    return (target, propertyOrContext) => {
+        if (typeof propertyOrContext === 'object' && propertyOrContext !== null) {
+            if (propertyOrContext.kind === 'class') {
+                if (typeof target !== 'function')
+                    throw new TypeError('Chronicle class decorators require a class constructor.');
+                legacy(target);
+            }
+            else {
+                propertyDecorator(target, propertyOrContext);
+            }
+            return;
+        }
+        if (!target)
+            throw new TypeError('Invalid legacy decorator invocation.');
+        legacy(target, propertyOrContext);
+    };
+}
+/** Stores standard property annotations on the class metadata object, without constructing an instance. */
+export function decorateProperty(legacy) {
+    return (target, keyOrContext) => {
+        if (typeof keyOrContext === 'object' && keyOrContext !== null) {
+            const context = keyOrContext;
+            if (target !== undefined || context.kind !== 'field' || context.static || context.private || typeof context.name !== 'string' || !context.metadata) {
+                throw new TypeError('Chronicle property decorators require a public instance field with standard decorator metadata.');
+            }
+            // Legacy decorators use target.constructor to track fields and store type-level annotations.
+            // The context.metadata object is owned by this class; never mutate its parent's metadata.
+            Object.defineProperty(context.metadata, 'constructor', { value: context.metadata, configurable: true });
+            legacy(context.metadata, context.name);
+            return;
+        }
+        if (!target || (typeof keyOrContext !== 'string' && typeof keyOrContext !== 'symbol')) {
+            throw new TypeError('Invalid legacy property decorator invocation.');
+        }
+        legacy(target, keyOrContext);
+    };
+}
+/** Reads an annotation declared by either decorator transform on a class field. */
+export function getPropertyMetadata(key, target, property) {
+    const ownLegacy = Reflect.getOwnMetadata(key, target, property);
+    if (ownLegacy !== undefined)
+        return ownLegacy;
+    const type = target.constructor;
+    const metadata = type && getStandardMetadata(type);
+    const ownStandard = metadata && Reflect.getOwnMetadata(key, metadata, property);
+    if (ownStandard !== undefined)
+        return ownStandard;
+    return Reflect.getMetadata(key, target, property)
+        ?? (metadata ? Reflect.getMetadata(key, metadata, property) : undefined);
+}
+/** Checks whether either decorator transform declared an annotation on a class field. */
+export function hasPropertyMetadata(key, target, property) {
+    const type = target.constructor;
+    const metadata = type && getStandardMetadata(type);
+    return Reflect.hasMetadata(key, target, property) || !!metadata && Reflect.hasMetadata(key, metadata, property);
+}
+/** Reads a type-level annotation emitted by a standard field decorator (or its legacy equivalent). */
+export function getTypeOrFieldMetadata(key, type) {
+    const ownLegacy = Reflect.getOwnMetadata(key, type);
+    if (ownLegacy !== undefined)
+        return ownLegacy;
+    const metadata = getStandardMetadata(type);
+    const ownStandard = metadata && Reflect.getOwnMetadata(key, metadata);
+    if (ownStandard !== undefined)
+        return ownStandard;
+    return Reflect.getMetadata(key, type)
+        ?? (metadata ? Reflect.getMetadata(key, metadata) : undefined);
+}
+//# sourceMappingURL=propertyDecoratorMetadata.js.map

package/dist/types/propertyDecoratorMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propertyDecoratorMetadata.js","sourceRoot":"","sources":["../../types/propertyDecoratorMetadata.ts"],"names":[],"mappings":"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"}

package/dist/types/standardDecoratorMetadata.d.ts

@@ -0,0 +1,9 @@
+/** A class decorator accepted by both the legacy and standard TypeScript transforms. */
+export type ChronicleClassDecorator = ClassDecorator & ((value: Function, context: ClassDecoratorContext) => void);
+/** Gets the metadata object attached when a standard-decorated class finishes evaluation. */
+export declare function getStandardMetadata(type: Function): object | undefined;
+/** Whether a class completed its own standard decorator evaluation. */
+export declare function hasOwnStandardMetadata(type: Function): boolean;
+/** Prevents a class decorator from inspecting fields before their metadata is attached. */
+export declare function requireCompletedStandardMetadata(type: Function): void;
+//# sourceMappingURL=standardDecoratorMetadata.d.ts.map

package/dist/types/standardDecoratorMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standardDecoratorMetadata.d.ts","sourceRoot":"","sources":["../../types/standardDecoratorMetadata.ts"],"names":[],"mappings":"AAOA,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG,cAAc,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC,CAAC;AAEnH,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAEtE;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE9D;AAED,2FAA2F;AAC3F,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAIrE"}

package/dist/types/standardDecoratorMetadata.js

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+// Node versions without native decorator metadata need this before evaluating a decorated class.
+const symbolWithMetadata = Symbol;
+symbolWithMetadata.metadata ??= Symbol.for('Symbol.metadata');
+/** Gets the metadata object attached when a standard-decorated class finishes evaluation. */
+export function getStandardMetadata(type) {
+    return Reflect.get(type, symbolWithMetadata.metadata);
+}
+/** Whether a class completed its own standard decorator evaluation. */
+export function hasOwnStandardMetadata(type) {
+    return Object.prototype.hasOwnProperty.call(type, symbolWithMetadata.metadata);
+}
+/** Prevents a class decorator from inspecting fields before their metadata is attached. */
+export function requireCompletedStandardMetadata(type) {
+    if (!hasOwnStandardMetadata(type)) {
+        throw new TypeError(`Standard decorator metadata for ${type.name} is not complete; inspect its schema after class evaluation.`);
+    }
+}
+//# sourceMappingURL=standardDecoratorMetadata.js.map

package/dist/types/standardDecoratorMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standardDecoratorMetadata.js","sourceRoot":"","sources":["../../types/standardDecoratorMetadata.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,iGAAiG;AACjG,MAAM,kBAAkB,GAAG,MAAyC,CAAC;AACrE,kBAAkB,CAAC,QAAQ,KAAK,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAK9D,6FAA6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAC9C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAuB,CAAC;AAChF,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,IAAc;IACjD,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AACnF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,gCAAgC,CAAC,IAAc;IAC3D,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,mCAAmC,IAAI,CAAC,IAAI,8DAA8D,CAAC,CAAC;IACpI,CAAC;AACL,CAAC"}

package/eventSequences/AppendOptions.ts

@@ -42,10 +42,9 @@ export interface AppendOptions {
     tags?: ReadonlyArray<string | Tag>;
 
     /**
-     * Optional per-event-source-id concurrency scopes, keyed by event source id.
-     * Only meaningful for the `appendMany(events: EventForEventSourceId[], options?)` overload, which
-     * can target multiple distinct event sources in a single batch. When an event source id has no
-     * entry here, it falls back to {@link concurrencyScope}.
+     * Optional labeled concurrency scopes, keyed by event source id. Labels need not be append targets.
+     * Any target without an explicit scope falls back to {@link concurrencyScope}.
+     * The kernel requires at least one event in a batch, so scope-only batches are not supported.
      */
     concurrencyScopes?: Record<string, ConcurrencyScope>;
 }

package/eventSequences/EventSequence.spec.ts

@@ -3,6 +3,7 @@
 
 import { describe, expect, it, vi } from 'vitest';
 import type { ChronicleConnection } from '../connection/index.js';
+import { causationManager, CausationType } from '../auditing/index.js';
 import type { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import { CompleteStreamError } from './CompleteStreamError.js';
@@ -354,6 +355,64 @@ describe('EventSequence', () => {
         });
     });
 
+    describe('when appending several batches in one command scope', () => {
+        it('should not carry the previous append link into the next append', async () => {
+            const { eventSequence, appendManyForEventSources } = createEventSequence();
+            await causationManager.run(new CausationType('Command'), {}, async () => {
+                const commandChain = causationManager.getCurrentChain().map(c => ({
+                    Occurred: { Value: c.occurred.toISOString() }, Type: c.type.name, Properties: { ...c.properties }
+                }));
+                await eventSequence.appendMany([{ eventSourceId: 'target', event: new SomethingHappened() }]);
+                await eventSequence.appendMany([{ eventSourceId: 'target', event: new SomethingHappened() }]);
+
+                // The test runner may have an ambient causation link; neither batch may add one to the next.
+                const [first, second] = appendManyForEventSources.mock.calls;
+                const expectedChain = [...commandChain, expect.objectContaining({
+                    Type: CausationType.appendManyEvents.name, Properties: { count: '1' }
+                })];
+                expect(first[0].Causation).toEqual(expectedChain);
+                expect(second[0].Causation).toEqual(expectedChain);
+            });
+        });
+    });
+
+    describe('when a batch has an independent concurrency label', () => {
+        it('should send both the event target and the independent scope', async () => {
+            const { eventSequence, appendManyForEventSources } = createEventSequence();
+            await eventSequence.appendMany([{ eventSourceId: 'target', event: new SomethingHappened() }], {
+                concurrencyScope: { sequenceNumber: 7n },
+                concurrencyScopes: { independent: { sequenceNumber: 3n, eventSourceId: true } }
+            });
+
+            const scopes = appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+            expect(scopes).toEqual(expect.arrayContaining([
+                expect.objectContaining({ EventSourceId: 'independent', Scope: expect.objectContaining({ SequenceNumber: 3n, EventSourceId: true }) }),
+                expect.objectContaining({ EventSourceId: 'target', Scope: expect.objectContaining({ SequenceNumber: 7n }) })
+            ]));
+        });
+    });
+
+    describe('when a batch expects no matching event', () => {
+        it('should send the dedicated flag and unavailable sequence number', async () => {
+            const { eventSequence, appendManyForEventSources } = createEventSequence();
+            await eventSequence.appendMany([{ eventSourceId: 'target', event: new SomethingHappened() }], {
+                concurrencyScopes: { independent: { sequenceNumber: EventSequenceNumber.beforeFirst.value, eventSourceId: true } }
+            });
+            const scope = appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes[0].Scope;
+            expect(scope.ExpectsNoMatchingEvent).toBe(true);
+            expect(scope.SequenceNumber).toBe(EventSequenceNumber.unset.value);
+        });
+    });
+
+    describe('when a batch contains only concurrency scopes', () => {
+        it('should reject locally because the kernel requires an event', async () => {
+            const { eventSequence, appendManyForEventSources } = createEventSequence();
+            await expect(eventSequence.appendMany([], { concurrencyScopes: { independent: { sequenceNumber: 1n } } }))
+                .rejects.toThrow('Chronicle requires at least one event');
+            expect(appendManyForEventSources).not.toHaveBeenCalled();
+        });
+    });
+
     describe('when an EventForEventSourceId specifies its own stream targeting', () => {
         const { eventSequence, appendManyForEventSources } = createEventSequence();
 

package/eventSequences/EventSequence.ts

@@ -71,8 +71,8 @@ export class EventSequence implements IEventSequence {
         // Merge static tags declared on the event type with tags supplied at append time.
         const tags = mergeTags(getTagsFor(event.constructor as Function), options?.tags);
 
-        causationManager.add(CausationType.appendEvent, { eventType: eventType.id.value });
-        const causationChain = causationManager.getCurrentChain();
+        const causationChain = causationManager.run(CausationType.appendEvent, { eventType: eventType.id.value },
+            () => causationManager.getCurrentChain());
         const identity = identityProvider.getCurrent();
 
         const metricAttributes = {
@@ -212,23 +212,26 @@ export class EventSequence implements IEventSequence {
         const appendOptions = typeof eventSourceIdOrEvents === 'string'
             ? options
             : eventsOrOptions as AppendOptions | undefined;
+        if (eventsForEventSourceIds.length === 0 && Object.keys(appendOptions?.concurrencyScopes ?? {}).length > 0) {
+            throw new Error('Chronicle requires at least one event to validate concurrency scopes.');
+        }
 
         const correlationId = appendOptions?.correlationId === undefined
             ? Guid.as(correlationIdManager.current.value)
             : Guid.as(appendOptions.correlationId);
 
-        causationManager.add(CausationType.appendManyEvents, { count: String(eventsForEventSourceIds.length) });
-        const batchCausationChain = causationManager.getCurrentChain();
+        const batchCausationChain = causationManager.run(CausationType.appendManyEvents, { count: String(eventsForEventSourceIds.length) },
+            () => causationManager.getCurrentChain());
         const identity = identityProvider.getCurrent();
 
-        // Each distinct event source id in the batch gets its own concurrency scope: an explicit
-        // entry in options.concurrencyScopes wins, falling back to the shared options.concurrencyScope
-        // when no per-source entry is given — mirroring C#'s AppendMany(IEnumerable<EventForEventSourceId>, ...)
-        // overload, which takes an IDictionary<EventSourceId, ConcurrencyScope> rather than one shared scope.
-        const concurrencyScopesByEventSourceId = appendOptions?.concurrencyScopes;
-        const defaultConcurrencyScope = appendOptions?.concurrencyScope;
-        const resolveConcurrencyScope = (eventSourceId: string) =>
-            this.toContractConcurrencyScope(concurrencyScopesByEventSourceId?.[eventSourceId] ?? defaultConcurrencyScope);
+        // Explicit labels may narrow a different event source than any target in this batch.
+        // Preserve them and supply the shared fallback only for targets without an explicit scope.
+        const concurrencyScopes = new Map<string, ConcurrencyScope | undefined>(Object.entries(appendOptions?.concurrencyScopes ?? {}));
+        for (const { eventSourceId } of eventsForEventSourceIds) {
+            if (!concurrencyScopes.has(eventSourceId)) {
+                concurrencyScopes.set(eventSourceId, appendOptions?.concurrencyScope);
+            }
+        }
 
         const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event, eventStreamType, eventStreamId, eventSourceType, subject, occurred, tags: instanceTags }) => {
             const eventType = getEventTypeFor(event.constructor as Function);
@@ -286,9 +289,9 @@ export class EventSequence implements IEventSequence {
                         Properties: { ...c.properties }
                     })),
                     CausedBy: toContractsCausedBy(identity),
-                    ConcurrencyScopes: distinctEventSourceIds.map(eventSourceId => ({
+                    ConcurrencyScopes: [...concurrencyScopes].map(([eventSourceId, scope]) => ({
                         EventSourceId: eventSourceId,
-                        Scope: resolveConcurrencyScope(eventSourceId)
+                        Scope: this.toContractConcurrencyScope(scope)
                     }))
                 });
 
@@ -752,7 +755,10 @@ export class EventSequence implements IEventSequence {
 
     private toContractConcurrencyScope(scope?: ConcurrencyScope) {
         return {
-            SequenceNumber: scope?.sequenceNumber ?? EventSequenceNumber.unset.value,
+            SequenceNumber: scope?.sequenceNumber === EventSequenceNumber.beforeFirst.value
+                ? EventSequenceNumber.unset.value
+                : scope?.sequenceNumber ?? EventSequenceNumber.unset.value,
+            ExpectsNoMatchingEvent: scope?.sequenceNumber === EventSequenceNumber.beforeFirst.value,
             EventSourceId: scope?.eventSourceId ?? false,
             EventStreamType: scope?.eventStreamType ?? '',
             EventStreamId: scope?.eventStreamId ?? '',

package/eventSequences/EventSequenceNumber.ts

@@ -8,9 +8,12 @@ export class EventSequenceNumber {
     /** Represents the first possible sequence number. */
     static readonly first = new EventSequenceNumber(0n);
 
-    /** Represents an unset sequence number. */
+    /** Represents an unset/unavailable sequence number; no expected revision was supplied. */
     static readonly unset = new EventSequenceNumber(18446744073709551615n);
 
+    /** Expects no event matching the scope. Encoded as ExpectsNoMatchingEvent, not as a wire sequence number. */
+    static readonly beforeFirst = new EventSequenceNumber(18446744073709551613n);
+
     constructor(readonly value: bigint) {}
 
     /**

package/eventSequences/for_EventSequence/when_appending/with_metadata.spec.ts

@@ -67,8 +67,9 @@ describe('when appending with explicit legacy routing and metadata', () => {
         request.Occurred!.Value.should.equal(occurred.toISOString());
     });
     it('should not derive concurrency scope from the route', () => {
+        // The .NET converter sends the contract's explicit false when no before-first check was requested.
         request.ConcurrencyScope!.should.deep.equal({
-            SequenceNumber: EventSequenceNumber.unset.value, EventSourceId: false,
+            SequenceNumber: EventSequenceNumber.unset.value, ExpectsNoMatchingEvent: false, EventSourceId: false,
             EventStreamType: '', EventStreamId: '', EventSourceType: '', EventTypes: []
         });
     });

package/events/classDecorators.standard.spec.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { constraint, getConstraintMetadata } from './constraints/constraint.js';
+import { eventType, getEventTypeMetadata } from './eventTypeDecorator.js';
+import { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator.js';
+import { eventTypeMigration, getEventTypeMigrationMetadata } from './migrations/eventTypeMigration.js';
+import { tag, tags, getTagsFor } from './tagDecorator.js';
+import { entersOn, getEntersOnMetadata } from '../projections/modelBound/entersOn.js';
+import { eventLog, eventSequence, getEventSequenceMetadata } from '../projections/modelBound/eventSequence.js';
+import { fromEvent, getFromEventMetadata } from '../projections/modelBound/fromEvent.js';
+import { getGlobalForMetadata, globalFor } from '../projections/modelBound/globalFor.js';
+import { isNotRewindable, notRewindable } from '../projections/modelBound/notRewindable.js';
+import { isPassive, passive } from '../projections/modelBound/passive.js';
+import { getVariantOfMetadata, variantOf } from '../projections/modelBound/variantOf.js';
+import { getSeederMetadata, seeder } from '../seeding/seeder.js';
+import { getWebhookMetadata, webhook } from '../webhooks/webhook.js';
+
+@eventType('migration-fixture', 1)
+class Previous {}
+
+@eventType('migration-fixture', 2)
+class Upgraded {}
+
+@eventTypeMigration(Upgraded, Previous)
+class Migration {}
+
+@constraint('standard-constraint')
+class Constraint {}
+
+@tag('first')
+@tags('second')
+@filterEventsByTag('required')
+class Tagged {}
+
+@fromEvent(Upgraded)
+@entersOn(Upgraded)
+@eventSequence('sequence')
+@passive
+@notRewindable
+class ModelBound {}
+
+@eventLog
+class EventLogModel {}
+
+@globalFor(Upgraded)
+class GlobalHandler {}
+
+@variantOf(Upgraded, 'kind')
+class Variant {}
+
+@seeder()
+class Seeder {}
+
+@webhook('standard-webhook', 'https://example.com/hooks')
+class Webhook {}
+
+describe('standard class decorators', () => {
+    it('retains class registrations and metadata without legacy decorator syntax', () => {
+        expect(getEventTypeMetadata(Previous)?.schema.properties).toEqual({});
+        expect(getEventTypeMigrationMetadata(Migration)?.eventType.generation.value).toBe(2);
+        expect(getConstraintMetadata(Constraint)?.id.value).toBe('standard-constraint');
+        expect(getTagsFor(Tagged).map(item => item.value)).toEqual(['second', 'first']);
+        expect(getFilterTagsFor(Tagged).map(item => item.value)).toEqual(['required']);
+        expect(getFromEventMetadata(ModelBound)).toHaveLength(1);
+        expect(getEntersOnMetadata(ModelBound)).toHaveLength(1);
+        expect(getEventSequenceMetadata(ModelBound)).toBe('sequence');
+        expect(isPassive(ModelBound)).toBe(true);
+        expect(isNotRewindable(ModelBound)).toBe(true);
+        expect(getEventSequenceMetadata(EventLogModel)).toBeDefined();
+        expect(getGlobalForMetadata(GlobalHandler)?.identity).toBe(Upgraded);
+        expect(getVariantOfMetadata(Variant)?.identity).toBe(Upgraded);
+        expect(getSeederMetadata(Seeder)?.isSeeder).toBe(true);
+        expect(getWebhookMetadata(Webhook)?.targetUrl.value).toBe('https://example.com/hooks');
+    });
+});

package/events/eventTypeDecorator.ts

@@ -8,6 +8,8 @@ import { EventTypeId } from './EventTypeId.js';
 import { EventTypeGeneration } from './EventTypeGeneration.js';
 import { DecoratorType, TypeDiscoverer, TypeIntrospector } from '../types/index.js';
 import { JsonSchema, JsonSchemaGenerator } from '../schemas/index.js';
+import { ChronicleClassDecorator } from '../types/standardDecoratorMetadata.js';
+import { createDeferredSchema } from '../schemas/createDeferredSchema.js';
 
 /** Metadata key used to store event type information on a class. */
 const EVENT_TYPE_METADATA_KEY = 'chronicle:eventType';
@@ -51,18 +53,18 @@ export interface EventTypeMetadata {
  * }
  * ```
  */
-export function eventType(): ClassDecorator;
-export function eventType(id: string): ClassDecorator;
-export function eventType(id: string, generation: number): ClassDecorator;
-export function eventType(id: string, generation: number, tombstone: boolean): ClassDecorator;
-export function eventType(generation: number): ClassDecorator;
-export function eventType(generation: number, tombstone: boolean): ClassDecorator;
-export function eventType(tombstone: boolean): ClassDecorator;
+export function eventType(): ChronicleClassDecorator;
+export function eventType(id: string): ChronicleClassDecorator;
+export function eventType(id: string, generation: number): ChronicleClassDecorator;
+export function eventType(id: string, generation: number, tombstone: boolean): ChronicleClassDecorator;
+export function eventType(generation: number): ChronicleClassDecorator;
+export function eventType(generation: number, tombstone: boolean): ChronicleClassDecorator;
+export function eventType(tombstone: boolean): ChronicleClassDecorator;
 export function eventType(
     idOrGenerationOrTombstone?: string | number | boolean,
     generationOrTombstone?: number | boolean,
     tombstone: boolean = false
-): ClassDecorator {
+): ChronicleClassDecorator {
     let id = '';
     let generation = EventTypeGeneration.firstValue;
     let isTombstone = false;
@@ -86,14 +88,23 @@ export function eventType(
         isTombstone = idOrGenerationOrTombstone;
     }
 
-    return (target: object) => {
-        const constructor = target as Function;
+    return (target: object, context?: ClassDecoratorContext) => {
+        let constructor = target as Function;
         const eventTypeId = new EventTypeId(id || constructor.name);
         const eventTypeInstance = new EventType(eventTypeId, new EventTypeGeneration(generation), isTombstone);
-        const members = TypeIntrospector.getMembers(constructor);
-        const metadata: EventTypeMetadata = {
+        const members = context?.kind === 'class' ? undefined : TypeIntrospector.getMembers(constructor);
+        const resolve = createDeferredSchema(() => constructor);
+        const metadata: EventTypeMetadata = context?.kind === 'class' ? {
             eventType: eventTypeInstance,
-            members,
+            get members() {
+                return resolve().members;
+            },
+            get schema() {
+                return resolve().schema;
+            }
+        } : {
+            eventType: eventTypeInstance,
+            members: members!,
             schema: JsonSchemaGenerator.generate(constructor, members)
         };
         Reflect.defineMetadata(EVENT_TYPE_METADATA_KEY, metadata, target);
@@ -102,6 +113,13 @@ export function eventType(
             constructor as Constructor,
             eventTypeId.value
         );
+        context?.addInitializer(function () {
+            if (this !== constructor) {
+                constructor = this;
+                Reflect.defineMetadata(EVENT_TYPE_METADATA_KEY, metadata, constructor);
+                TypeDiscoverer.default.register(DecoratorType.EventType, constructor as Constructor, eventTypeId.value);
+            }
+        });
     };
 }
 

package/events/index.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import '../types/standardDecoratorMetadata.js';
+
 export { EventType } from './EventType.js';
 export { EventTypeId } from './EventTypeId.js';
 export { EventTypeGeneration } from './EventTypeGeneration.js';
@@ -11,6 +13,7 @@ export type { CausationEntry } from './CausationEntry.js';
 export type { AppendedEvent } from './AppendedEvent.js';
 export type { IEventTypes } from './IEventTypes.js';
 export { EventTypes } from './EventTypes.js';
+export { isRegisteredEvent } from './isRegisteredEvent.js';
 export { Tag } from './Tag.js';
 export { tag, tags, getTagsFor } from './tagDecorator.js';
 export { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator.js';

package/events/isRegisteredEvent.spec.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import type { IEventStore } from '../IEventStore.js';
+import { eventType } from './eventTypeDecorator.js';
+import { isRegisteredEvent } from './isRegisteredEvent.js';
+
+class CurrentEvent {}
+class UnregisteredEvent {}
+eventType('c00f9f33-0ccb-4319-9def-b19ef26f0351')(CurrentEvent);
+eventType('c00f9f33-0ccb-4319-9def-b19ef26f0352')(UnregisteredEvent);
+
+const store = { eventTypes: { all: [CurrentEvent] } } as IEventStore;
+
+describe('when classifying a command return value against a store', () => {
+    it('should accept an instance of the registered event', () => {
+        expect(isRegisteredEvent(store, new CurrentEvent())).toBe(true);
+    });
+
+    it('should reject decorated but unregistered types and ordinary payloads', () => {
+        expect(isRegisteredEvent(store, new UnregisteredEvent())).toBe(false);
+        expect(isRegisteredEvent(store, { event: new CurrentEvent() })).toBe(false);
+        expect(isRegisteredEvent(store, null)).toBe(false);
+    });
+});

package/events/isRegisteredEvent.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.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { IEventStore } from '../IEventStore.js';
+import { hasEventType } from './eventTypeDecorator.js';
+
+/** Checks whether a value is an instance of a current event type registered in this store. */
+export function isRegisteredEvent(store: Pick<IEventStore, 'eventTypes'>, value: unknown): value is object {
+    return typeof value === 'object' && value !== null &&
+        hasEventType(value.constructor) && store.eventTypes.all.includes(value.constructor as Constructor);
+}

package/identity/IdentityProvider.ts

@@ -16,6 +16,11 @@ export class IdentityProvider implements IIdentityProvider {
         return this._storage.getStore() ?? Identity.system;
     }
 
+    /** Runs an async or synchronous operation as the given identity, restoring the caller's identity afterward. */
+    run<T>(identity: Identity, callback: () => T): T {
+        return this._storage.run(identity, callback);
+    }
+
     /** @inheritdoc */
     setCurrentIdentity(identity: Identity): void {
         this._storage.enterWith(identity);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.3.2",
+    "version": "6.5.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",
@@ -162,6 +162,7 @@
         "build": "tsc -b",
         "clean": "rm -rf dist",
         "test": "vitest run",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {
@@ -178,6 +179,7 @@
         "@cratis/fundamentals": "7.19.2",
         "@types/node": "^26.5.1",
         "@typescript/native": "npm:typescript@^7.0.2",
+        "esbuild": "^0.28.2",
         "typescript": "npm:@typescript/typescript6@^6.0.2",
         "vite": "^8.3.0",
         "vitest": "^5.0.1"

package/projections/modelBound/addFrom.ts

@@ -3,6 +3,7 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
+import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the addFrom property decorator. */
 export interface AddFromMetadata {
@@ -20,14 +21,14 @@ const METADATA_KEY = 'chronicle:projection:addFrom';
  * @param eventPropertyName - Optional event property name. Defaults to the property name.
  * @returns A property decorator.
  */
-export function addFrom(eventType: Function, eventPropertyName?: string): PropertyDecorator {
-    return (target: object, propertyKey: string | symbol) => {
+export function addFrom(eventType: Function, eventPropertyName?: string): ChroniclePropertyDecorator {
+    return decorateProperty((target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: AddFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
         const metadata: AddFromMetadata = { eventType, eventPropertyName };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
-    };
+    });
 }
 
 /**
@@ -37,5 +38,5 @@ export function addFrom(eventType: Function, eventPropertyName?: string): Proper
  * @returns An array of addFrom metadata entries.
  */
 export function getAddFromMetadata(target: object, propertyKey: string): AddFromMetadata[] {
-    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+    return getPropertyMetadata<AddFromMetadata[]>(METADATA_KEY, target, propertyKey) ?? [];
 }

package/projections/modelBound/childrenFrom.ts

@@ -3,6 +3,7 @@
 
 import 'reflect-metadata';
 import { TypeIntrospector } from '../../types/index.js';
+import { ChroniclePropertyDecorator, decorateProperty, getPropertyMetadata } from '../../types/propertyDecoratorMetadata.js';
 
 /** Metadata stored by the childrenFrom property decorator. */
 export interface ChildrenFromMetadata {
@@ -31,14 +32,14 @@ export function childrenFrom(
     key?: string,
     identifiedBy?: string,
     parentKey?: string
-): PropertyDecorator {
-    return (target: object, propertyKey: string | symbol) => {
+): ChroniclePropertyDecorator {
+    return decorateProperty((target: object, propertyKey: string | symbol) => {
         const propKey = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, propKey);
         const existing: ChildrenFromMetadata[] = Reflect.getMetadata(METADATA_KEY, target, propKey) ?? [];
         const metadata: ChildrenFromMetadata = { eventType, key, identifiedBy, parentKey };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, propKey);
-    };
+    });
 }
 
 /**
@@ -48,5 +49,5 @@ export function childrenFrom(
  * @returns An array of childrenFrom metadata entries.
  */
 export function getChildrenFromMetadata(target: object, propertyKey: string): ChildrenFromMetadata[] {
-    return Reflect.getMetadata(METADATA_KEY, target, propertyKey) ?? [];
+    return getPropertyMetadata<ChildrenFromMetadata[]>(METADATA_KEY, target, propertyKey) ?? [];
 }