@cratis/chronicle 0.0.1 → 0.1.0

package/Projections/Projections.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { diag } from '@opentelemetry/api';
 import {
     AutoMap,
     ProjectionOwner
@@ -8,9 +9,11 @@ import {
 import { Constructor } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts';
 import { ChronicleConnection } from '../connection';
+import { toContractsGuid } from '../connection/Guid';
 import { EventSequenceId } from '../EventSequences/EventSequenceId';
 import { getEventTypeFor } from '../Events/eventTypeDecorator';
 import { getReadModelMetadata } from '../ReadModels';
+import { WellKnownSinks } from '../sinks';
 import { TypeIntrospector } from '../types';
 import { IProjections } from './IProjections';
 import { getProjectionMetadata } from './declarative/projection';
@@ -51,6 +54,8 @@ export class Projections implements IProjections {
     private readonly _declarative = new Map<string, Constructor>();
     private readonly _modelBound = new Map<string, Constructor>();
 
+    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/Projections' });
+
     /**
      * Creates a new {@link Projections} instance.
      * @param _clientArtifacts - Provider for discovered client artifact types.
@@ -66,27 +71,36 @@ export class Projections implements IProjections {
         this._declarative.clear();
         this._modelBound.clear();
 
-        for (const type of this._clientArtifacts.projections) {
+        const declarativeTypes = this._clientArtifacts.projections;
+        const readModelTypes = this._clientArtifacts.readModels;
+        this._logger.debug('Discovering projections', { declarativeCount: declarativeTypes.length, readModelCount: readModelTypes.length });
+
+        for (const type of declarativeTypes) {
             const metadata = getProjectionMetadata(type);
             if (metadata) {
+                this._logger.debug('Discovered declarative projection', { projectionId: metadata.id.value, type: type.name });
                 this._declarative.set(metadata.id.value, type);
             }
         }
 
-        for (const type of this._clientArtifacts.readModels) {
+        for (const type of readModelTypes) {
             if (!hasFromEventMetadata(type)) {
                 continue;
             }
 
             const metadata = this.resolveModelBoundMetadata(type);
             if (!metadata) {
+                this._logger.debug('Read model has @fromEvent but no model-bound metadata resolved', { type: type.name });
                 continue;
             }
 
+            this._logger.debug('Discovered model-bound projection', { projectionId: metadata.id.value, type: type.name });
             if (!this._modelBound.has(metadata.id.value)) {
                 this._modelBound.set(metadata.id.value, type);
             }
         }
+
+        this._logger.debug('Projection discovery complete', { declarativeCount: this._declarative.size, modelBoundCount: this._modelBound.size });
     }
 
     /** @inheritdoc */
@@ -95,12 +109,15 @@ export class Projections implements IProjections {
             await this.discover();
         }
 
+        this._logger.info('Registering projections', { declarativeCount: this._declarative.size, modelBoundCount: this._modelBound.size });
+
         const projections = [
             ...Array.from(this._declarative.values()).map(type => this.buildDeclarativeDefinition(type)),
             ...Array.from(this._modelBound.values()).map(type => this.buildModelBoundDefinition(type))
         ];
 
         if (projections.length === 0) {
+            this._logger.info('No projections to register');
             return;
         }
 
@@ -115,15 +132,37 @@ export class Projections implements IProjections {
         }
 
         for (const projection of projections) {
+            const identifier = String((projection as { Identifier?: unknown }).Identifier ?? '<unknown>');
+            await this.registerWithRetry(projection, identifier);
+        }
+    }
+
+    private async registerWithRetry(projection: unknown, identifier: string, maxAttempts = 5): Promise<void> {
+        let delay = 2000;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             try {
+                this._logger.info('Registering projection', { identifier, readModel: (projection as any).ReadModel, attempt });
                 await this._connection.projections.register({
                     EventStore: this._eventStore,
                     Owner: ProjectionOwner.PROJECTION_OWNER_Client,
-                    Projections: [projection]
+                    Projections: [projection as any]
                 });
+                this._logger.info('Projection registered successfully', { identifier });
+                return;
             } catch (error) {
-                const identifier = String((projection as { Identifier?: unknown }).Identifier ?? '<unknown>');
-                throw new Error(`Failed to register projection '${identifier}': ${String(error)}`);
+                const msg = String(error);
+                const isTransient = msg.includes('UNKNOWN') || msg.includes('UNAVAILABLE') || msg.includes('INTERNAL');
+                if (!isTransient || attempt === maxAttempts) {
+                    throw new Error(`Failed to register projection '${identifier}' after ${attempt} attempt(s): ${msg}`);
+                }
+                this._logger.warn('Projection registration failed with transient error, retrying', {
+                    identifier,
+                    attempt,
+                    nextAttemptInMs: delay,
+                    error: msg
+                });
+                await new Promise(resolve => setTimeout(resolve, delay));
+                delay = Math.min(delay * 2, 15000);
             }
         }
     }
@@ -145,8 +184,8 @@ export class Projections implements IProjections {
                 ContainerName: readModelIdentifier,
                 DisplayName: readModelIdentifier,
                 Sink: {
-                    ConfigurationId: this.toContractsGuid('00000000-0000-0000-0000-000000000000'),
-                    TypeId: this.toContractsGuid('22202c41-2be1-4547-9c00-f0b1f797fd75')
+                    ConfigurationId: toContractsGuid(WellKnownSinks.Null),
+                    TypeId: toContractsGuid(WellKnownSinks.MongoDB)
                 },
                 Schema: this.getReadModelSchema(readModelIdentifier),
                 Indexes: [],
@@ -188,12 +227,19 @@ export class Projections implements IProjections {
 
         const explicitReadModelIdentifier = definition.ReadModel as string;
         if (explicitReadModelIdentifier === type.name) {
-            const inferredReadModelIdentifier = this.inferReadModelIdentifier(builder.getMappedReadModelProperties());
-            if (inferredReadModelIdentifier) {
-                definition.ReadModel = inferredReadModelIdentifier;
+            // Use explicit readModelType from decorator if provided
+            if (metadata.readModelType) {
+                const rm = getReadModelMetadata(metadata.readModelType);
+                definition.ReadModel = rm?.id.value ?? (metadata.readModelType as Function).name;
+            } else {
+                const inferredReadModelIdentifier = this.inferReadModelIdentifier(builder.getMappedReadModelProperties());
+                if (inferredReadModelIdentifier) {
+                    definition.ReadModel = inferredReadModelIdentifier;
+                }
             }
         }
 
+        definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
         return definition;
     }
 
@@ -324,7 +370,7 @@ export class Projections implements IProjections {
             }
         }
 
-        return {
+        const definition: Record<string, unknown> = {
             EventSequenceId: metadata.eventSequenceId ?? EventSequenceId.eventLog.value,
             Identifier: metadata.id.value,
             ReadModel: metadata.readModelIdentifier,
@@ -340,14 +386,15 @@ export class Projections implements IProjections {
                 IncludeChildren: false,
                 AutoMap: AutoMap.Inherit
             },
-            FromEventProperty: undefined,
             RemovedWith: Array.from(removedWithByEventType.values()),
             RemovedWithJoin: Array.from(removedWithJoinByEventType.values()),
-            LastUpdated: { Value: new Date().toISOString() },
+            LastUpdated: { Value: '' },
             Tags: [],
-            AutoMap: AutoMap.Disabled,
+            AutoMap: AutoMap.Enabled,
             Nested: {}
         };
+        definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
+        return definition;
     }
 
     private resolveModelBoundMetadata(type: Constructor): ResolvedModelBoundMetadata | undefined {
@@ -453,11 +500,19 @@ export class Projections implements IProjections {
         return `${eventType.Id}:${eventType.Generation}:${eventType.Tombstone ? '1' : '0'}`;
     }
 
-    private toContractsGuid(value: string): { lo: number; hi: number } {
-        const hex = value.replace(/-/g, '');
-        return {
-            hi: Number(BigInt(`0x${hex.substring(0, 16)}`)),
-            lo: Number(BigInt(`0x${hex.substring(16, 32)}`))
-        };
+    /**
+     * Computes a stable, deterministic ISO timestamp from the projection definition content,
+     * excluding the LastUpdated field itself. This ensures the server does not interpret
+     * a repeated registration of an unchanged definition as a definition change, which
+     * would otherwise trigger an unnecessary auto-replay.
+     */
+    private computeStableLastUpdated(definition: Record<string, unknown>): string {
+        const { LastUpdated: _omit, ...rest } = definition;
+        const content = JSON.stringify(rest, Object.keys(rest).sort());
+        let hash = 5381;
+        for (let i = 0; i < content.length; i++) {
+            hash = ((hash << 5) + hash + content.charCodeAt(i)) >>> 0;
+        }
+        return new Date(hash * 1000).toISOString();
     }
 }

package/Projections/declarative/ProjectionBuilderFor.ts

@@ -215,7 +215,7 @@ export class ProjectionBuilderFor<TReadModel> implements IProjectionBuilderFor<T
      * @returns The projection definition object ready to send to the kernel.
      */
     build(identifier: string, readModelName: string): Record<string, unknown> {
-        return {
+        const definition: Record<string, unknown> = {
             EventSequenceId: this._eventSequenceId,
             Identifier: identifier,
             ReadModel: this._containerName ?? readModelName,
@@ -230,11 +230,13 @@ export class ProjectionBuilderFor<TReadModel> implements IProjectionBuilderFor<T
             FromEventProperty: undefined,
             RemovedWith: this._removedWith,
             RemovedWithJoin: this._removedWithJoin,
-            LastUpdated: { Value: new Date().toISOString() },
+            LastUpdated: { Value: '' },
             Tags: [],
             AutoMap: this._autoMap,
             Nested: {}
         };
+        definition.LastUpdated = { Value: this.computeStableLastUpdated(definition) };
+        return definition;
     }
 
     /**
@@ -274,4 +276,19 @@ export class ProjectionBuilderFor<TReadModel> implements IProjectionBuilderFor<T
             Tombstone: false
         };
     }
+
+    /**
+     * Computes a stable, deterministic ISO timestamp from the projection definition content,
+     * excluding the LastUpdated field itself. This ensures the server does not interpret
+     * a repeated registration of an unchanged definition as a definition change.
+     */
+    private computeStableLastUpdated(definition: Record<string, unknown>): string {
+        const { LastUpdated: _omit, ...rest } = definition;
+        const content = JSON.stringify(rest, Object.keys(rest).sort());
+        let hash = 5381;
+        for (let i = 0; i < content.length; i++) {
+            hash = ((hash << 5) + hash + content.charCodeAt(i)) >>> 0;
+        }
+        return new Date(hash * 1000).toISOString();
+    }
 }

package/Projections/declarative/projection.ts

@@ -18,19 +18,23 @@ export interface ProjectionMetadata {
 
     /** The optional explicit event sequence identifier. */
     readonly eventSequenceId: string | undefined;
+
+    /** The optional explicit read model constructor. */
+    readonly readModelType: Constructor | undefined;
 }
 
 /**
  * TypeScript decorator that marks a class as a declarative projection.
  * @param id - The unique identifier for the projection. Defaults to the class name if omitted.
+ * @param readModelType - Optional explicit read model constructor (needed when TypeScript generic inference is insufficient).
  * @param eventSequenceId - Optional explicit event sequence identifier.
  * @returns A class decorator.
  */
-export function projection(id: string = '', eventSequenceId?: string): ClassDecorator {
+export function projection(id: string = '', readModelType?: Constructor, eventSequenceId?: string): ClassDecorator {
     return (target: object) => {
         const constructor = target as Function;
         const projectionId = new ProjectionId(id || constructor.name);
-        const metadata: ProjectionMetadata = { id: projectionId, eventSequenceId };
+        const metadata: ProjectionMetadata = { id: projectionId, eventSequenceId, readModelType };
         Reflect.defineMetadata(PROJECTION_METADATA_KEY, metadata, target);
         TypeDiscoverer.default.register(
             DecoratorType.Projection,

package/Projections/modelBound/index.ts

@@ -1,8 +1,6 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { modelBound, getModelBoundMetadata, isModelBound } from './modelBound';
-export type { ModelBoundMetadata } from './modelBound';
 export { fromEvent, getFromEventMetadata, hasFromEventMetadata } from './fromEvent';
 export type { FromEventOptions } from './FromEventOptions';
 export type { FromEventMetadata } from './FromEventMetadata';

package/Projections/modelBound/setFromContext.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
+import { PropertyAccessor, PropertyPathResolverProxyHandler } from '@cratis/fundamentals';
+import type { EventContext } from '../../Events';
 import { TypeIntrospector } from '../../types';
 
 /** Metadata stored by the setFromContext property decorator. */
@@ -17,14 +19,30 @@ const METADATA_KEY = 'chronicle:projection:setFromContext';
 /**
  * Property decorator that maps a value from an event context property onto the decorated read model property.
  * @param eventType - The event constructor.
- * @param contextPropertyName - Optional event context property name. Defaults to the property name.
+ * @param contextPropertyOrAccessor - Optional event context property name or property accessor. Defaults to the property name.
  * @returns A property decorator.
  */
-export function setFromContext(eventType: Function, contextPropertyName?: string): PropertyDecorator {
+export function setFromContext(eventType: Function, contextPropertyName?: string): PropertyDecorator;
+export function setFromContext(eventType: Function, contextPropertyAccessor?: PropertyAccessor<EventContext>): PropertyDecorator;
+export function setFromContext(
+    eventType: Function,
+    contextPropertyOrAccessor?: string | PropertyAccessor<EventContext>
+): PropertyDecorator {
     return (target: object, propertyKey: string | symbol) => {
         const key = propertyKey.toString();
         TypeIntrospector.trackProperty((target as { constructor: Function }).constructor, key);
         const existing: SetFromContextMetadata[] = Reflect.getMetadata(METADATA_KEY, target, key) ?? [];
+
+        let contextPropertyName: string | undefined;
+        if (typeof contextPropertyOrAccessor === 'string') {
+            contextPropertyName = contextPropertyOrAccessor;
+        } else if (typeof contextPropertyOrAccessor === 'function') {
+            const handler = new PropertyPathResolverProxyHandler();
+            const proxy = new Proxy({}, handler);
+            contextPropertyOrAccessor(proxy as EventContext);
+            contextPropertyName = handler.property;
+        }
+
         const metadata: SetFromContextMetadata = { eventType, contextPropertyName };
         Reflect.defineMetadata(METADATA_KEY, [...existing, metadata], target, key);
     };

package/README.md

@@ -6,7 +6,7 @@ A TypeScript-idiomatic client for [Cratis Chronicle](https://github.com/Cratis/C
 
 `@cratis/chronicle` provides a clean, type-safe TypeScript API for interacting with the Chronicle Kernel. It builds on top of [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) (the gRPC contracts package) and exposes idiomatic TypeScript constructs including:
 
-- **Decorators** — `@eventType`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, `@modelBoundProjection`
+- **Decorators** — `@eventType`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
 - **Value objects** — `EventSequenceNumber`, `EventTypeId`, `EventStoreName`, etc.
 - **Fluent client** — `ChronicleClient` → `EventStore` → `EventLog` → `append()`
 

package/Reactors/Reactors.ts

@@ -233,6 +233,7 @@ export class Reactors implements IReactors {
                         }
 
                         const content = JSON.parse(event.Content) as Record<string, unknown>;
+                        this._logger.debug('Event content', { reactorId: id, eventTypeId, contentKeys: Object.keys(content), rawContent: event.Content.substring(0, 200) });
                         const context: EventContext = {
                             sequenceNumber: event.Context!.SequenceNumber,
                             eventSourceId: event.Context!.EventSourceId,

package/Reducers/Reducers.ts

@@ -4,14 +4,18 @@
 import 'reflect-metadata';
 import { diag } from '@opentelemetry/api';
 import { Constructor } from '@cratis/fundamentals';
-import { ObservationState, ReducerMessage } from '@cratis/chronicle.contracts';
+import { ObservationState, ReadModelObserverType, ReducerMessage } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts';
 import { ChronicleConnection } from '../connection';
+import { toContractsGuid } from '../connection/Guid';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle';
 import { getEventTypeMetadata } from '../Events/eventTypeDecorator';
 import { EventSequenceId } from '../EventSequences/EventSequenceId';
+import { WellKnownSinks } from '../sinks';
 import { IReducers } from './IReducers';
 import { getReducerMetadata } from './reducer';
+import { getReadModelMetadata } from '../ReadModels';
+import { JsonSchemaGenerator } from '../Schemas';
 
 /** Expression used to partition reducer observations by event source ID. */
 const EVENT_SOURCE_ID_KEY = '$eventSourceId';
@@ -139,6 +143,8 @@ export class Reducers implements IReducers {
             await this.discover();
         }
 
+        await this.registerReadModels();
+
         this._logger.info('Registering reducers', { count: this._reducers.size });
         for (const [id, reducerType] of this._reducers) {
             this.startObservation(id, reducerType);
@@ -147,6 +153,61 @@ export class Reducers implements IReducers {
         this._registered = true;
     }
 
+    private async registerReadModels(): Promise<void> {
+        if (this._reducers.size === 0) {
+            return;
+        }
+
+        const readModels = Array.from(this._reducers.entries()).map(([id, reducerType]) => {
+            const readModelName = (reducerType as Function).name;
+            return {
+                Type: {
+                    Identifier: readModelName,
+                    Generation: 1
+                },
+                ContainerName: readModelName,
+                DisplayName: readModelName,
+                Sink: {
+                    ConfigurationId: toContractsGuid(WellKnownSinks.Null),
+                    TypeId: toContractsGuid(WellKnownSinks.MongoDB)
+                },
+                Schema: this.getReducerSchema(reducerType, readModelName),
+                Indexes: [],
+                ObserverType: ReadModelObserverType.Reducer,
+                ObserverIdentifier: id,
+                Owner: 1,
+                Source: 1
+            };
+        });
+
+        this._logger.info('Registering read models for reducers', { count: readModels.length });
+        await this._connection.readModels.registerMany({
+            EventStore: this._eventStoreName,
+            Owner: 1,
+            ReadModels: readModels,
+            Source: 1
+        });
+    }
+
+    private getReducerSchema(reducerType: Constructor, readModelName: string): string {
+        const metadata = getReducerMetadata(reducerType);
+        if (metadata?.readModel) {
+            const readModelMeta = getReadModelMetadata(metadata.readModel);
+            if (readModelMeta?.schema) {
+                return JSON.stringify(readModelMeta.schema);
+            }
+            // No @readModel() decorator — generate from instance
+            return JSON.stringify(JsonSchemaGenerator.generate(metadata.readModel));
+        }
+
+        // No read model type declared — generate from a minimal schema
+        const minimalSchema = {
+            ...JsonSchemaGenerator.createEmptySchema(readModelName),
+            additionalProperties: true
+        };
+        return JSON.stringify(minimalSchema);
+    }
+
     private startObservation(id: string, reducerType: Constructor): void {
         const metadata = getReducerMetadata(reducerType)!;
         const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
@@ -191,7 +252,10 @@ export class Reducers implements IReducers {
                         })),
                         ReadModel: readModelName,
                         IsActive: true,
-                        Sink: { TypeId: { lo: 0, hi: 0 }, ConfigurationId: undefined },
+                        Sink: {
+                            TypeId: toContractsGuid(WellKnownSinks.MongoDB),
+                            ConfigurationId: toContractsGuid(WellKnownSinks.Null)
+                        },
                         Tags: [],
                         Filters: {
                             FilterTags: [],

package/Schemas/JsonSchemaGenerator.ts

@@ -44,14 +44,27 @@ export class JsonSchemaGenerator {
     static generate(target: Function, members?: ReadonlyMap<string, Function | undefined>): JsonSchema {
         const membersToUse = members ?? TypeIntrospector.getMembers(target);
         const schemaProperties: Record<string, JsonSchema> = {};
+
         for (const [memberName, memberType] of membersToUse.entries()) {
-            schemaProperties[memberName] = this.mapRuntimeTypeToSchema(memberType);
+            const propertySchema = this.mapRuntimeTypeToSchema(memberType);
+            // Only include properties whose type was resolved. An empty schema ({}) means
+            // the runtime type was unavailable (e.g. esbuild/tsx omits design:paramtypes).
+            if (Object.keys(propertySchema).length > 0) {
+                schemaProperties[memberName] = propertySchema;
+            }
+        }
+
+        // When no property types could be resolved, return a minimal schema with empty
+        // properties so the server uses its fallback path that preserves all event
+        // content as-is via ConvertUnknownSchemaTypeToClrType.
+        if (Object.keys(schemaProperties).length === 0) {
+            return this.createEmptySchema(target.name);
         }
 
         return {
             ...this.createEmptySchema(target.name),
             properties: schemaProperties,
-            required: Array.from(membersToUse.keys()),
+            required: Object.keys(schemaProperties),
         };
     }
 
@@ -77,7 +90,11 @@ export class JsonSchemaGenerator {
             return { type: 'array', items: { type: 'object' } };
         }
 
-        if (runtimeType && runtimeType !== Object) {
+        if (!runtimeType) {
+            return {};
+        }
+
+        if (runtimeType !== Object) {
             return this.generate(runtimeType);
         }
 

package/artifacts/DefaultClientArtifactsProvider.ts

@@ -48,9 +48,4 @@ export class DefaultClientArtifactsProvider implements IClientArtifactsProvider
     get projections(): Constructor[] {
         return this.discoverer.getTypesByDecoratorType(DecoratorType.Projection);
     }
-
-    /** @inheritdoc */
-    get modelBoundProjections(): Constructor[] {
-        return this.discoverer.getTypesByDecoratorType(DecoratorType.ModelBoundProjection);
-    }
 }

package/artifacts/IClientArtifactsProvider.ts

@@ -24,7 +24,4 @@ export interface IClientArtifactsProvider {
 
     /** Gets discovered declarative projection constructors. */
     readonly projections: Constructor[];
-
-    /** Gets discovered model-bound projection constructors. */
-    readonly modelBoundProjections: Constructor[];
 }

package/connection/Guid.ts

@@ -1,4 +1,32 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { Guid } from '@cratis/chronicle.contracts';
+import type { Guid as ContractsGuid } from '@cratis/chronicle.contracts';
+import { Guid as FundamentalGuid } from '@cratis/fundamentals';
+
+export { Guid } from '@cratis/fundamentals';
+
+/**
+ * Converts a Chronicle Guid into the protobuf-net bcl.Guid shape used by the
+ * contracts package.
+ */
+export function toContractsGuid(guid: FundamentalGuid): ContractsGuid {
+    const bytes = guid.bytes ?? FundamentalGuid.empty.bytes ?? [];
+    if (bytes.length !== 16) {
+        throw new Error(`Invalid Guid '${guid.toString()}'. Expected 16 bytes.`);
+    }
+
+    let lo = 0n;
+    let hi = 0n;
+    for (let index = 0; index < 8; index++) {
+        lo |= BigInt(bytes[index]) << BigInt(index * 8);
+        hi |= BigInt(bytes[index + 8]) << BigInt(index * 8);
+    }
+
+    // The runtime accepts strings for fixed64 values, which preserves the exact
+    // 64-bit payload instead of truncating through Number.
+    return {
+        lo: lo.toString() as unknown as number,
+        hi: hi.toString() as unknown as number
+    };
+}

package/dist/Auditing/Causation.d.ts

@@ -0,0 +1,22 @@
+import { CausationType } from './CausationType';
+/**
+ * Represents a causation instance.
+ */
+export declare class Causation {
+    readonly occurred: Date;
+    readonly type: CausationType;
+    readonly properties: Readonly<Record<string, string>>;
+    /**
+     * Creates an unknown causation instance.
+     * @returns A new {@link Causation} with the current time, type set to {@link CausationType.unknown}, and empty properties.
+     */
+    static unknown(): Causation;
+    /**
+     * Initializes a new instance of the {@link Causation} class.
+     * @param occurred - When it occurred.
+     * @param type - Type of causation.
+     * @param properties - Any properties associated with the causation.
+     */
+    constructor(occurred: Date, type: CausationType, properties: Readonly<Record<string, string>>);
+}
+//# sourceMappingURL=Causation.d.ts.map

package/dist/Auditing/Causation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Causation.d.ts","sourceRoot":"","sources":["../../Auditing/Causation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,qBAAa,SAAS;IAgBd,QAAQ,CAAC,QAAQ,EAAE,IAAI;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAjBzD;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,SAAS;IAI3B;;;;;OAKG;gBAEU,QAAQ,EAAE,IAAI,EACd,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAE5D"}

package/dist/Auditing/Causation.js

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { CausationType } from './CausationType';
+/**
+ * Represents a causation instance.
+ */
+export class Causation {
+    occurred;
+    type;
+    properties;
+    /**
+     * Creates an unknown causation instance.
+     * @returns A new {@link Causation} with the current time, type set to {@link CausationType.unknown}, and empty properties.
+     */
+    static unknown() {
+        return new Causation(new Date(), CausationType.unknown, {});
+    }
+    /**
+     * Initializes a new instance of the {@link Causation} class.
+     * @param occurred - When it occurred.
+     * @param type - Type of causation.
+     * @param properties - Any properties associated with the causation.
+     */
+    constructor(occurred, type, properties) {
+        this.occurred = occurred;
+        this.type = type;
+        this.properties = properties;
+    }
+}
+//# sourceMappingURL=Causation.js.map

package/dist/Auditing/Causation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Causation.js","sourceRoot":"","sources":["../../Auditing/Causation.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,OAAO,SAAS;IAgBL;IACA;IACA;IAjBb;;;OAGG;IACH,MAAM,CAAC,OAAO;QACV,OAAO,IAAI,SAAS,CAAC,IAAI,IAAI,EAAE,EAAE,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACH,YACa,QAAc,EACd,IAAmB,EACnB,UAA4C;QAF5C,aAAQ,GAAR,QAAQ,CAAM;QACd,SAAI,GAAJ,IAAI,CAAe;QACnB,eAAU,GAAV,UAAU,CAAkC;IACtD,CAAC;CACP"}

package/dist/Auditing/CausationManager.d.ts

@@ -0,0 +1,23 @@
+import { Causation } from './Causation';
+import { CausationType } from './CausationType';
+import { ICausationManager } from './ICausationManager';
+/**
+ * Implements {@link ICausationManager} using {@link AsyncLocalStorage} to scope the causation chain to the active async call context.
+ */
+export declare class CausationManager implements ICausationManager {
+    private readonly _storage;
+    private _root;
+    /** @inheritdoc */
+    get root(): Causation;
+    /** @inheritdoc */
+    getCurrentChain(): ReadonlyArray<Causation>;
+    /** @inheritdoc */
+    add(type: CausationType, properties: Record<string, string>): void;
+    /**
+     * Defines the root causation for the current process.
+     * @param properties - Properties associated with the root causation.
+     */
+    defineRoot(properties: Record<string, string>): void;
+    private _getOrInitChain;
+}
+//# sourceMappingURL=CausationManager.d.ts.map

package/dist/Auditing/CausationManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausationManager.d.ts","sourceRoot":"","sources":["../../Auditing/CausationManager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;GAEG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IACjE,OAAO,CAAC,KAAK,CAAgE;IAE7E,kBAAkB;IAClB,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,kBAAkB;IAClB,eAAe,IAAI,aAAa,CAAC,SAAS,CAAC;IAK3C,kBAAkB;IAClB,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKlE;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIpD,OAAO,CAAC,eAAe;CAU1B"}