arvo-core 2.3.1 → 3.0.0

package/dist/ArvoContract/SimpleArvoContract/index.d.ts

@@ -50,6 +50,7 @@ export declare const createSimpleArvoContract: <TUri extends string, TType exten
     uri: TUri;
     type: TType;
     versions: TVersions;
+    domain?: string;
     metadata?: TMetaData;
     description?: string;
 }) => SimpleArvoContract<TUri, TType, TVersions, TMetaData>;

package/dist/ArvoContract/SimpleArvoContract/index.js

@@ -61,6 +61,7 @@ var createSimpleArvoContract = function (param) {
     var emitType = "evt.".concat(param.type, ".success");
     return (0, helpers_1.createArvoContract)({
         uri: param.uri,
+        domain: param.domain,
         type: "com.".concat(param.type),
         description: param.description,
         metadata: mergedMetadata,

package/dist/ArvoContract/VersionedArvoContract/index.d.ts

@@ -26,6 +26,7 @@ export declare class VersionedArvoContract<TContract extends ArvoContract, TVers
     get emits(): TContract["versions"][TVersion]["emits"];
     get emitList(): { [K in keyof TContract["versions"][TVersion]["emits"] & string]: ArvoContractRecord<K, TContract["versions"][TVersion]["emits"][K]>; }[keyof TContract["versions"][TVersion]["emits"] & string][];
     get dataschema(): `${TContract["uri"]}/${TVersion}`;
+    get domain(): string | null;
     constructor(param: IVersionedArvoContract<TContract, TVersion>);
     /**
      * Converts the contract to JSON Schema format

package/dist/ArvoContract/VersionedArvoContract/index.js

@@ -98,6 +98,13 @@ var VersionedArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(VersionedArvoContract.prototype, "domain", {
+        get: function () {
+            return this._contract.domain;
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
      * Converts the contract to JSON Schema format
      * @returns Contract specification in JSON Schema format for documentation/serialization
@@ -107,6 +114,7 @@ var VersionedArvoContract = /** @class */ (function () {
             return {
                 uri: this.uri,
                 description: this.description,
+                domain: this.domain,
                 version: this.version,
                 metadata: this.metadata,
                 accepts: {

package/dist/ArvoContract/VersionedArvoContract/types.d.ts

@@ -30,6 +30,7 @@ export type ArvoContractRecordJsonSchema = {
 export type VersionedArvoContractJSONSchema = {
     uri: string;
     description: string | null;
+    domain: string | null;
     version: ArvoSemanticVersion;
     accepts: ArvoContractRecordJsonSchema;
     systemError: ArvoContractRecordJsonSchema;

package/dist/ArvoContract/helpers.d.ts

@@ -39,6 +39,7 @@ export declare const createArvoContract: <TUri extends string, TType extends str
     uri: TUri;
     type: TType;
     versions: TVersions;
+    domain?: string;
     metadata?: TMetaData;
     description?: string;
 }) => ArvoContract<TUri, TType, TVersions, TMetaData>;

package/dist/ArvoContract/helpers.js

@@ -39,7 +39,7 @@ var utils_1 = require("../utils");
  * ```
  */
 var createArvoContract = function (contract) {
-    var _a, _b;
+    var _a, _b, _c;
     var createErrorMessage = function (source, type, version) {
         var versionString = version ? ", version=".concat(version) : '';
         return (0, utils_1.cleanString)("\n      In contract (uri=".concat(contract.uri).concat(versionString, "), the '").concat(source, "' event (type=").concat(type, ") must not start\n      with '").concat(typegen_1.ArvoOrchestratorEventTypeGen.prefix, "' because this is a reserved pattern\n      for Arvo orchestrators.\n    "));
@@ -47,10 +47,10 @@ var createArvoContract = function (contract) {
     if (typegen_1.ArvoOrchestratorEventTypeGen.isOrchestratorEventType(contract.type)) {
         throw new Error(createErrorMessage('accepts', contract.type, null));
     }
-    for (var _i = 0, _c = Object.entries(contract.versions); _i < _c.length; _i++) {
-        var _d = _c[_i], version = _d[0], versionContract = _d[1];
-        for (var _e = 0, _f = Object.keys(versionContract['emits']); _e < _f.length; _e++) {
-            var emitType = _f[_e];
+    for (var _i = 0, _d = Object.entries(contract.versions); _i < _d.length; _i++) {
+        var _e = _d[_i], version = _e[0], versionContract = _e[1];
+        for (var _f = 0, _g = Object.keys(versionContract['emits']); _f < _g.length; _f++) {
+            var emitType = _g[_f];
             if (typegen_1.ArvoOrchestratorEventTypeGen.isOrchestratorEventType(emitType)) {
                 throw new Error(createErrorMessage('emits', emitType, version));
             }
@@ -59,8 +59,9 @@ var createArvoContract = function (contract) {
     return new _1.default({
         uri: contract.uri,
         type: contract.type,
-        description: (_a = contract.description) !== null && _a !== void 0 ? _a : null,
-        metadata: (_b = contract.metadata) !== null && _b !== void 0 ? _b : {},
+        domain: (_a = contract === null || contract === void 0 ? void 0 : contract.domain) !== null && _a !== void 0 ? _a : null,
+        description: (_b = contract.description) !== null && _b !== void 0 ? _b : null,
+        metadata: (_c = contract.metadata) !== null && _c !== void 0 ? _c : {},
         versions: contract.versions,
     });
 };

package/dist/ArvoContract/index.d.ts

@@ -46,11 +46,13 @@ export default class ArvoContract<TUri extends string = string, TType extends st
     protected readonly _versions: TVersions;
     protected readonly _description: string | null;
     protected readonly _metadata: TMetaData;
+    protected readonly _domain: string | null;
     get uri(): TUri;
     get type(): TType;
     get versions(): TVersions;
     get description(): string | null;
     get metadata(): TMetaData;
+    get domain(): string | null;
     /**
      * Creates a new ArvoContract instance with validated parameters.
      *
@@ -62,6 +64,7 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * @throws {Error} When version is a reserved wildcard version
      * @throws {Error} When emit type format is invalid
      * @throws {Error} When no versions are provided
+     * @throws {Error} When domain does not have follow the condition Domain must contain only lowercase letters, numbers, and dots
      */
     constructor(params: IArvoContract<TUri, TType, TVersions, TMetaData>);
     /**

package/dist/ArvoContract/index.js

@@ -49,16 +49,19 @@ var ArvoContract = /** @class */ (function () {
      * @throws {Error} When version is a reserved wildcard version
      * @throws {Error} When emit type format is invalid
      * @throws {Error} When no versions are provided
+     * @throws {Error} When domain does not have follow the condition Domain must contain only lowercase letters, numbers, and dots
      */
     function ArvoContract(params) {
         var _a;
+        validators_1.ArvoContractValidators.contract.uri.parse(params.uri);
+        validators_1.ArvoContractValidators.record.type.parse(params.type);
+        validators_1.ArvoContractValidators.contract.domain.parse(params.domain);
         this._uri = params.uri;
         this._type = params.type;
         this._versions = params.versions;
         this._description = (_a = params.description) !== null && _a !== void 0 ? _a : null;
         this._metadata = params.metadata;
-        validators_1.ArvoContractValidators.contract.uri.parse(params.uri);
-        validators_1.ArvoContractValidators.record.type.parse(params.type);
+        this._domain = params.domain;
         for (var _i = 0, _b = Object.entries(params.versions); _i < _b.length; _i++) {
             var _c = _b[_i], version = _c[0], versionContract = _c[1];
             schema_1.ArvoSemanticVersionSchema.parse(version);
@@ -109,6 +112,13 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(ArvoContract.prototype, "domain", {
+        get: function () {
+            return this._domain;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(ArvoContract.prototype, "systemError", {
         /**
          * Gets the system error event specification for this contract.
@@ -183,6 +193,7 @@ var ArvoContract = /** @class */ (function () {
         return {
             uri: this._uri,
             type: this._type,
+            domain: this._domain,
             description: this._description,
             versions: this._versions,
             metadata: this._metadata,
@@ -198,11 +209,13 @@ var ArvoContract = /** @class */ (function () {
         try {
             return {
                 uri: this._uri,
+                domain: this._domain,
                 description: this._description,
                 metadata: this._metadata,
                 versions: Object.keys(this._versions).map(function (version) {
                     var jsonSchema = _this.version(version).toJsonSchema();
                     return {
+                        domain: jsonSchema.domain,
                         version: jsonSchema.version,
                         accepts: jsonSchema.accepts,
                         systemError: jsonSchema.systemError,

package/dist/ArvoContract/types.d.ts

@@ -44,6 +44,8 @@ export interface IArvoContract<TUri extends string = string, TType extends strin
     metadata: TMetaData;
     /** A record mapping semantic versions to their corresponding schemas */
     versions: TVersions;
+    /** The domain of the contract handler */
+    domain: string | null;
 }
 /**
  * Represents the JSON Schema representation of an ArvoContract, used for serialization
@@ -51,6 +53,7 @@ export interface IArvoContract<TUri extends string = string, TType extends strin
  */
 export type ArvoContractJSONSchema = {
     uri: string;
+    domain: string | null;
     description: string | null;
     metadata: Record<string, any> | null;
     versions: Omit<VersionedArvoContractJSONSchema, 'uri' | 'description'>[];

package/dist/ArvoContract/validators.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 export declare const ArvoContractValidators: {
     contract: {
         uri: z.ZodEffects<z.ZodString, string, string>;
+        domain: z.ZodNullable<z.ZodString>;
     };
     record: {
         type: z.ZodString;

package/dist/ArvoContract/validators.js

@@ -10,6 +10,12 @@ exports.ArvoContractValidators = {
             .min(1, 'URI must be a non-empty string')
             .refine(utils_1.validateURI, 'The URI must a valid URI string')
             .describe((0, utils_1.cleanString)("\n      The addressable unique URI of the contract so that\n      it can be located and address for reference during\n      operations\n    ")),
+        domain: zod_1.z
+            .string()
+            .min(1, 'The domain must be non-empty string')
+            .regex(/^[a-z0-9.]+$/, 'Domain must contain only lowercase letters, numbers, and dots')
+            .nullable()
+            .describe('The contract handler domian'),
     },
     record: {
         type: zod_1.z

package/dist/ArvoEvent/helpers.js

@@ -13,7 +13,7 @@ var schema_1 = require("./schema");
  * Internal generator function for creating  instances.
  */
 var generator = function (event, extensions, otelHeaders) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     if (event.datacontenttype && event.datacontenttype !== schema_1.ArvoDataContentType) {
         var warning = (0, utils_1.cleanString)("\n    Warning! The provided datacontenttype(=".concat(event.datacontenttype, ")\n    is not ArvoEvent compatible (=").concat(schema_1.ArvoDataContentType, "). There may \n    be some limited functionality.\n  "));
         (0, OpenTelemetry_1.logToSpan)({
@@ -36,6 +36,8 @@ var generator = function (event, extensions, otelHeaders) {
         to: event.to ? encodeURI(event.to) : encodeURI(event.type),
         redirectto: event.redirectto ? encodeURI(event.redirectto) : null,
         dataschema: event.dataschema ? encodeURI(event.dataschema) : null,
+        parentid: event.parentid ? encodeURI(event.parentid) : null,
+        domain: (_l = event.domain) !== null && _l !== void 0 ? _l : null,
     }, event.data, extensions);
 };
 /**

package/dist/ArvoEvent/index.d.ts

@@ -1,37 +1,105 @@
 import type { InferArvoEvent } from '../types';
 import type { ArvoEventData, ArvoExtension, CloudEventContext, CloudEventExtension, OpenTelemetryExtension } from './types';
 /**
- * Represents an ArvoEvent, which extends the CloudEvent specification.
+ * Represents an ArvoEvent, which extends the CloudEvent specification with
+ * Arvo-specific extensions for event routing, access control, execution metrics,
+ * and OpenTelemetry distributed tracing support.
  */
 export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExtension extends CloudEventExtension = CloudEventExtension, TType extends string = string> {
+    /** Unique identifier of the event */
     readonly id: string;
+    /**
+     * URI reference identifying the context in which the event happened.
+     * Must be a properly encoded URI representing the event producer.
+     */
     readonly source: string;
+    /**
+     * The version of the CloudEvents specification which the event uses.
+     * Must be '1.0' for this version of the specification.
+     */
     readonly specversion: string;
+    /**
+     * Describes the type of event related to the originating occurrence.
+     * Must follow reverse-DNS naming convention (e.g., 'com.example.service.eventtype').
+     */
     readonly type: TType;
+    /**
+     * Identifies the subject of the event in the context of the event producer.
+     * In Arvo, this must be the Process ID and must be a properly encoded URI.
+     */
     readonly subject: string;
+    /**
+     * Content type of the data value following RFC 2046 format.
+     * Must contain 'application/cloudevents+json' or 'application/json'.
+     * Defaults to 'application/cloudevents+json;charset=UTF-8;profile=arvo'.
+     */
     readonly datacontenttype: string;
+    /**
+     * URI identifying the schema that the data adheres to.
+     * Must be a properly encoded URI if present, null otherwise.
+     */
     readonly dataschema: string | null;
+    /** The event data payload as a JSON serializable object */
     readonly data: TData;
+    /**
+     * Timestamp of when the occurrence happened in RFC 3339 format.
+     * If the actual occurrence time cannot be determined, this may be set
+     * to another time (such as current time) by the producer.
+     */
     readonly time: string;
     private readonly _extensions;
     /**
-     * Creates an instance of ArvoEvent.
-     * @param context - The CloudEvent context along with Arvo and OpenTelemetry extensions.
-     * @param data - The event data.
-     * @param extensions - Optional additional extensions.
+     * Creates an instance of ArvoEvent with CloudEvent context, data, and optional extensions.
      *
-     * @throws {Error} If the datacontenttype is {@link ArvoDataContentType} but the `to` field
-     *                 is not defined
+     * @param context - The CloudEvent context combined with required Arvo and OpenTelemetry extensions
+     * @param data - The event data payload (must be JSON serializable)
+     * @param extensions - Optional additional custom extensions with lowercase alphanumeric keys
+     *
+     * @throws {Error} If datacontenttype is "application/cloudevents+json;charset=UTF-8;profile=arvo" but the 'to' field is not defined
+     * @throws {Error} If any validation fails according to the respective schemas
+     *
+     * @example
+     * ```typescript
+     * const event = new ArvoEvent(
+     *   {
+     *     id: 'event-123',
+     *     source: 'https://example.com/service',
+     *     type: 'com.example.user.created',
+     *     subject: 'https://example.com/users/123',
+     *     time: new Date().toISOString(),
+     *     specversion: '1.0',
+     *     datacontenttype: 'application/cloudevents+json;charset=UTF-8;profile=arvo',
+     *     dataschema: null,
+     *     to: 'com.example.user.processor',
+     *     accesscontrol: 'role:admin;department:hr',
+     *     redirectto: null,
+     *     executionunits: 10,
+     *     parentid: 'parent-event-456',
+     *     domain: 'analytics',
+     *     traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+     *     tracestate: 'vendor=trace-data'
+     *   },
+     *   { userId: '123', name: 'John Doe' }
+     * );
+     * ```
      */
     constructor(context: CloudEventContext & ArvoExtension & OpenTelemetryExtension, data: TData, extensions?: TExtension);
     /**
-     * Gets the CloudEvent-specified default fields and extensions.
-     * @returns An object containing the base CloudEvent default fields and extensions.
-     * `default` fields are the standard CloudEvents attributes, which include:
-     * `extension` fields are additional attributes that provide extra context or functionality:
-     * - ArvoExtension: Arvo-specific extensions (to, accesscontrol, redirectto, executionunits)
-     * - OpenTelemetryExtension: OpenTelemetry-specific extensions (traceparent, tracestate)
-     * - TExtension: Any additional custom extensions
+     * Gets the CloudEvent-specified fields separated into default attributes and extensions.
+     *
+     * @returns An object containing:
+     * - `default`: Standard CloudEvent attributes (id, source, specversion, type, subject, datacontenttype, dataschema, data, time)
+     * - `extensions`: All extension attributes including:
+     *   - Arvo extensions
+     *   - OpenTelemetry extensions
+     *   - Custom extensions
+     *
+     * @example
+     * ```typescript
+     * const { default: defaults, extensions } = event.cloudevent;
+     * console.log(defaults.id); // Event ID
+     * console.log(extensions.to); // Arvo 'to' field
+     * ```
      */
     get cloudevent(): {
         default: {
@@ -50,36 +118,57 @@ export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExt
             accesscontrol: string | null;
             redirectto: string | null;
             executionunits: number | null;
+            parentid: string | null;
+            domain: string | null;
         } & {
             traceparent: string | null;
             tracestate: string | null;
         };
     };
     /**
-     * Converts the ArvoEvent to a JSON-serializable object.
-     * It bundles the extensions and the cloudevent fields into
-     * one object.
+     * Converts the ArvoEvent to a JSON-serializable object by combining
+     * all CloudEvent default fields with all extensions into a single flat object.
+     *
+     * @returns A flat object containing all CloudEvent fields and extensions,
+     * suitable for JSON serialization and network transmission
      *
      * @remarks
-     * This method combines the default CloudEvent fields and all extensions
-     * (including Arvo and OpenTelemetry extensions) into a single object.
-     * If you need to access the CloudEvent fields and extensions separately,
-     * use the `cloudevent` getter instead.
+     * This method creates a flattened representation where both standard CloudEvent
+     * fields and all extensions (Arvo, OpenTelemetry, and custom) are at the same level.
+     * For separated access to defaults and extensions, use the `cloudevent` getter instead.
+     *
+     * @example
+     * ```typescript
+     * const jsonObj = event.toJSON();
+     * // Contains: id, source, type, subject, data, time, to, traceparent, etc.
+     * ```
      */
     toJSON(): InferArvoEvent<typeof this>;
     /**
-     * Converts the ArvoEvent to a JSON string.
-     * @param [spacing=0] - The number of spaces to use for indentation in the resulting JSON string.
-     * @returns A JSON string representation of the ArvoEvent.
+     * Converts the ArvoEvent to a JSON string representation.
+     *
+     * @param spacing - The number of spaces to use for indentation (default: 0 for compact output)
+     * @returns A JSON string representation of the complete ArvoEvent
+     *
+     * @example
+     * ```typescript
+     * const compactJson = event.toString(); // Compact JSON
+     * const prettyJson = event.toString(2); // Pretty-printed with 2-space indentation
+     * ```
      */
     toString(spacing?: number): string;
     /**
-     * Gets OpenTelemetry attributes derived from the ArvoEvent.
-     * @returns An object containing OpenTelemetry attributes.
-     * The OpenTelemetry attributes for CloudEvents is as per
-     * the spec provided [in the official documentation](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloudevents/).
-     * Additionally, the Arvo extension attributed are also returned
-     * as `cloudevents.arvo.event_*` fields.
+     * Gets OpenTelemetry attributes derived from the ArvoEvent for distributed tracing.
+     *
+     * @returns An object containing OpenTelemetry semantic convention attributes:
+     * - Standard CloudEvent attributes prefixed with 'cloudevents.event_*'
+     * - Arvo-specific attributes prefixed with 'cloudevents.arvo.*'
+     * - Uses 'N/A' for undefined/null values to maintain telemetry consistency
+     *
+     * @remarks
+     * The attributes follow the OpenTelemetry semantic conventions for CloudEvents
+     * as specified in the official documentation:
+     * https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloudevents/
      */
     get otelAttributes(): {
         'cloudevents.event_id': string;
@@ -93,22 +182,66 @@ export default class ArvoEvent<TData extends ArvoEventData = ArvoEventData, TExt
         'cloudevents.arvo.event_redirectto': string;
         'cloudevents.arvo.event_to': string;
         'cloudevents.arvo.event_executionunits': string | number;
+        'cloudevents.arvo.event_parentid': string;
+        'cloudevents.arvo.event_domain': string;
     };
+    /**
+     * Gets the target consumer machine for event routing.
+     */
     get to(): string | null;
+    /**
+     * Gets the access control information for the event.
+     * Can contain:
+     * - A UserID (valid UUID)
+     * - An encrypted base64 string with access control data
+     * - Key-value pairs (semicolon-separated, colon-delimited)
+     *   Example: "role:admin;department:finance;clearance:top-secret"
+     */
     get accesscontrol(): string | null;
+    /**
+     * Gets the alternative recipient or destination for dynamic routing.
+     * Enables complex workflows and conditional event routing.
+     */
     get redirectto(): string | null;
+    /**
+     * Gets the execution units representing the cost associated with
+     * generating this event. Used for tracking financial impact and
+     * resource utilization in cloud-based systems.
+     */
     get executionunits(): number | null;
+    /**
+     * Gets the OpenTelemetry traceparent header containing trace context
+     * information including trace ID, parent span ID, and trace flags
+     * for distributed tracing across services.
+     */
     get traceparent(): string | null;
+    /**
+     * Gets the OpenTelemetry tracestate header containing vendor-specific
+     * trace information as key-value pairs propagated alongside traceparent
+     * in distributed tracing scenarios.
+     */
     get tracestate(): string | null;
     /**
-     * Gets the custom extensions of the ArvoEvent.
+     * Gets the unique identifier of the event that directly triggered
+     * the creation of this event within the Arvo ecosystem.
+     * Establishes direct causal relationships for event lineage tracking.
+     * Null indicates an initiating event or generation outside direct causation.
+     */
+    get parentid(): string | null;
+    /**
+     * Gets the processing domain for event routing and workflow orchestration.
+     */
+    get domain(): string | null;
+    /**
+     * Gets only the custom extensions (TExtension) added to the ArvoEvent,
+     * excluding the standard Arvo and OpenTelemetry extensions.
+     *
+     * @returns The custom extensions object with Arvo and OpenTelemetry fields removed
      *
      * @remarks
-     * This getter returns only the custom extensions (TExtension) added to the ArvoEvent,
-     * excluding the standard Arvo and OpenTelemetry extensions.
-     * For accessing all extensions including Arvo and OpenTelemetry,
-     * use `<ArvoEvent>.cloudevent.extensions`.
-     * For accessing the basic CloudEvent fields, use `<ArvoEvent>.cloudevent.default`.
+     * For accessing all extensions including Arvo and OpenTelemetry, use `cloudevent.extensions`.
+     * For accessing basic CloudEvent fields, use `cloudevent.default`.
+     * Custom extension keys must follow lowercase alphanumeric naming (a-z, 0-9 only).
      */
     get extensions(): TExtension;
 }

package/dist/ArvoEvent/index.js

@@ -25,17 +25,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var OpenTelemetry_1 = require("../OpenTelemetry");
 var schema_1 = require("./schema");
 /**
- * Represents an ArvoEvent, which extends the CloudEvent specification.
+ * Represents an ArvoEvent, which extends the CloudEvent specification with
+ * Arvo-specific extensions for event routing, access control, execution metrics,
+ * and OpenTelemetry distributed tracing support.
  */
 var ArvoEvent = /** @class */ (function () {
     /**
-     * Creates an instance of ArvoEvent.
-     * @param context - The CloudEvent context along with Arvo and OpenTelemetry extensions.
-     * @param data - The event data.
-     * @param extensions - Optional additional extensions.
+     * Creates an instance of ArvoEvent with CloudEvent context, data, and optional extensions.
      *
-     * @throws {Error} If the datacontenttype is {@link ArvoDataContentType} but the `to` field
-     *                 is not defined
+     * @param context - The CloudEvent context combined with required Arvo and OpenTelemetry extensions
+     * @param data - The event data payload (must be JSON serializable)
+     * @param extensions - Optional additional custom extensions with lowercase alphanumeric keys
+     *
+     * @throws {Error} If datacontenttype is "application/cloudevents+json;charset=UTF-8;profile=arvo" but the 'to' field is not defined
+     * @throws {Error} If any validation fails according to the respective schemas
+     *
+     * @example
+     * ```typescript
+     * const event = new ArvoEvent(
+     *   {
+     *     id: 'event-123',
+     *     source: 'https://example.com/service',
+     *     type: 'com.example.user.created',
+     *     subject: 'https://example.com/users/123',
+     *     time: new Date().toISOString(),
+     *     specversion: '1.0',
+     *     datacontenttype: 'application/cloudevents+json;charset=UTF-8;profile=arvo',
+     *     dataschema: null,
+     *     to: 'com.example.user.processor',
+     *     accesscontrol: 'role:admin;department:hr',
+     *     redirectto: null,
+     *     executionunits: 10,
+     *     parentid: 'parent-event-456',
+     *     domain: 'analytics',
+     *     traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+     *     tracestate: 'vendor=trace-data'
+     *   },
+     *   { userId: '123', name: 'John Doe' }
+     * );
+     * ```
      */
     function ArvoEvent(context, data, extensions) {
         var cloudEventContext = schema_1.CloudEventContextSchema.parse(context);
@@ -50,7 +78,7 @@ var ArvoEvent = /** @class */ (function () {
         this.data = schema_1.ArvoDataSchema.parse(data);
         var arvoExtension = schema_1.ArvoExtensionSchema.parse(context);
         var otelExtension = schema_1.OpenTelemetryExtensionSchema.parse(context);
-        this._extensions = __assign(__assign({}, (extensions ? schema_1.CloudEventExtensionSchema.parse(extensions) : {})), { to: arvoExtension.to, accesscontrol: arvoExtension.accesscontrol, redirectto: arvoExtension.redirectto, executionunits: arvoExtension.executionunits, traceparent: otelExtension.traceparent, tracestate: otelExtension.tracestate });
+        this._extensions = __assign(__assign({}, (extensions ? schema_1.CloudEventExtensionSchema.parse(extensions) : {})), { to: arvoExtension.to, accesscontrol: arvoExtension.accesscontrol, redirectto: arvoExtension.redirectto, executionunits: arvoExtension.executionunits, traceparent: otelExtension.traceparent, tracestate: otelExtension.tracestate, parentid: arvoExtension.parentid, domain: arvoExtension.domain });
         if (this.datacontenttype === schema_1.ArvoDataContentType) {
             if (!this._extensions.to) {
                 throw new Error("The ArvoEvent must have a non-empty 'to' field");
@@ -61,13 +89,21 @@ var ArvoEvent = /** @class */ (function () {
     }
     Object.defineProperty(ArvoEvent.prototype, "cloudevent", {
         /**
-         * Gets the CloudEvent-specified default fields and extensions.
-         * @returns An object containing the base CloudEvent default fields and extensions.
-         * `default` fields are the standard CloudEvents attributes, which include:
-         * `extension` fields are additional attributes that provide extra context or functionality:
-         * - ArvoExtension: Arvo-specific extensions (to, accesscontrol, redirectto, executionunits)
-         * - OpenTelemetryExtension: OpenTelemetry-specific extensions (traceparent, tracestate)
-         * - TExtension: Any additional custom extensions
+         * Gets the CloudEvent-specified fields separated into default attributes and extensions.
+         *
+         * @returns An object containing:
+         * - `default`: Standard CloudEvent attributes (id, source, specversion, type, subject, datacontenttype, dataschema, data, time)
+         * - `extensions`: All extension attributes including:
+         *   - Arvo extensions
+         *   - OpenTelemetry extensions
+         *   - Custom extensions
+         *
+         * @example
+         * ```typescript
+         * const { default: defaults, extensions } = event.cloudevent;
+         * console.log(defaults.id); // Event ID
+         * console.log(extensions.to); // Arvo 'to' field
+         * ```
          */
         get: function () {
             return {
@@ -89,23 +125,37 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     /**
-     * Converts the ArvoEvent to a JSON-serializable object.
-     * It bundles the extensions and the cloudevent fields into
-     * one object.
+     * Converts the ArvoEvent to a JSON-serializable object by combining
+     * all CloudEvent default fields with all extensions into a single flat object.
+     *
+     * @returns A flat object containing all CloudEvent fields and extensions,
+     * suitable for JSON serialization and network transmission
      *
      * @remarks
-     * This method combines the default CloudEvent fields and all extensions
-     * (including Arvo and OpenTelemetry extensions) into a single object.
-     * If you need to access the CloudEvent fields and extensions separately,
-     * use the `cloudevent` getter instead.
+     * This method creates a flattened representation where both standard CloudEvent
+     * fields and all extensions (Arvo, OpenTelemetry, and custom) are at the same level.
+     * For separated access to defaults and extensions, use the `cloudevent` getter instead.
+     *
+     * @example
+     * ```typescript
+     * const jsonObj = event.toJSON();
+     * // Contains: id, source, type, subject, data, time, to, traceparent, etc.
+     * ```
      */
     ArvoEvent.prototype.toJSON = function () {
         return __assign(__assign({}, this.cloudevent.default), this._extensions);
     };
     /**
-     * Converts the ArvoEvent to a JSON string.
-     * @param [spacing=0] - The number of spaces to use for indentation in the resulting JSON string.
-     * @returns A JSON string representation of the ArvoEvent.
+     * Converts the ArvoEvent to a JSON string representation.
+     *
+     * @param spacing - The number of spaces to use for indentation (default: 0 for compact output)
+     * @returns A JSON string representation of the complete ArvoEvent
+     *
+     * @example
+     * ```typescript
+     * const compactJson = event.toString(); // Compact JSON
+     * const prettyJson = event.toString(2); // Pretty-printed with 2-space indentation
+     * ```
      */
     ArvoEvent.prototype.toString = function (spacing) {
         if (spacing === void 0) { spacing = 0; }
@@ -113,15 +163,20 @@ var ArvoEvent = /** @class */ (function () {
     };
     Object.defineProperty(ArvoEvent.prototype, "otelAttributes", {
         /**
-         * Gets OpenTelemetry attributes derived from the ArvoEvent.
-         * @returns An object containing OpenTelemetry attributes.
-         * The OpenTelemetry attributes for CloudEvents is as per
-         * the spec provided [in the official documentation](https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloudevents/).
-         * Additionally, the Arvo extension attributed are also returned
-         * as `cloudevents.arvo.event_*` fields.
+         * Gets OpenTelemetry attributes derived from the ArvoEvent for distributed tracing.
+         *
+         * @returns An object containing OpenTelemetry semantic convention attributes:
+         * - Standard CloudEvent attributes prefixed with 'cloudevents.event_*'
+         * - Arvo-specific attributes prefixed with 'cloudevents.arvo.*'
+         * - Uses 'N/A' for undefined/null values to maintain telemetry consistency
+         *
+         * @remarks
+         * The attributes follow the OpenTelemetry semantic conventions for CloudEvents
+         * as specified in the official documentation:
+         * https://opentelemetry.io/docs/specs/semconv/attributes-registry/cloudevents/
          */
         get: function () {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e, _f;
             return {
                 'cloudevents.event_id': this.id || OpenTelemetry_1.OTelNull,
                 'cloudevents.event_source': this.source || OpenTelemetry_1.OTelNull,
@@ -134,12 +189,17 @@ var ArvoEvent = /** @class */ (function () {
                 'cloudevents.arvo.event_redirectto': (_b = this._extensions.redirectto) !== null && _b !== void 0 ? _b : OpenTelemetry_1.OTelNull,
                 'cloudevents.arvo.event_to': (_c = this._extensions.to) !== null && _c !== void 0 ? _c : OpenTelemetry_1.OTelNull,
                 'cloudevents.arvo.event_executionunits': (_d = this._extensions.executionunits) !== null && _d !== void 0 ? _d : OpenTelemetry_1.OTelNull,
+                'cloudevents.arvo.event_parentid': (_e = this._extensions.parentid) !== null && _e !== void 0 ? _e : OpenTelemetry_1.OTelNull,
+                'cloudevents.arvo.event_domain': (_f = this._extensions.domain) !== null && _f !== void 0 ? _f : OpenTelemetry_1.OTelNull,
             };
         },
         enumerable: false,
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "to", {
+        /**
+         * Gets the target consumer machine for event routing.
+         */
         get: function () {
             return this._extensions.to;
         },
@@ -147,6 +207,14 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "accesscontrol", {
+        /**
+         * Gets the access control information for the event.
+         * Can contain:
+         * - A UserID (valid UUID)
+         * - An encrypted base64 string with access control data
+         * - Key-value pairs (semicolon-separated, colon-delimited)
+         *   Example: "role:admin;department:finance;clearance:top-secret"
+         */
         get: function () {
             return this._extensions.accesscontrol;
         },
@@ -154,6 +222,10 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "redirectto", {
+        /**
+         * Gets the alternative recipient or destination for dynamic routing.
+         * Enables complex workflows and conditional event routing.
+         */
         get: function () {
             return this._extensions.redirectto;
         },
@@ -161,6 +233,11 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "executionunits", {
+        /**
+         * Gets the execution units representing the cost associated with
+         * generating this event. Used for tracking financial impact and
+         * resource utilization in cloud-based systems.
+         */
         get: function () {
             return this._extensions.executionunits;
         },
@@ -168,6 +245,11 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "traceparent", {
+        /**
+         * Gets the OpenTelemetry traceparent header containing trace context
+         * information including trace ID, parent span ID, and trace flags
+         * for distributed tracing across services.
+         */
         get: function () {
             return this._extensions.traceparent;
         },
@@ -175,26 +257,55 @@ var ArvoEvent = /** @class */ (function () {
         configurable: true
     });
     Object.defineProperty(ArvoEvent.prototype, "tracestate", {
+        /**
+         * Gets the OpenTelemetry tracestate header containing vendor-specific
+         * trace information as key-value pairs propagated alongside traceparent
+         * in distributed tracing scenarios.
+         */
         get: function () {
             return this._extensions.tracestate;
         },
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(ArvoEvent.prototype, "parentid", {
+        /**
+         * Gets the unique identifier of the event that directly triggered
+         * the creation of this event within the Arvo ecosystem.
+         * Establishes direct causal relationships for event lineage tracking.
+         * Null indicates an initiating event or generation outside direct causation.
+         */
+        get: function () {
+            return this._extensions.parentid;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(ArvoEvent.prototype, "domain", {
+        /**
+         * Gets the processing domain for event routing and workflow orchestration.
+         */
+        get: function () {
+            return this._extensions.domain;
+        },
+        enumerable: false,
+        configurable: true
+    });
     Object.defineProperty(ArvoEvent.prototype, "extensions", {
         /**
-         * Gets the custom extensions of the ArvoEvent.
+         * Gets only the custom extensions (TExtension) added to the ArvoEvent,
+         * excluding the standard Arvo and OpenTelemetry extensions.
+         *
+         * @returns The custom extensions object with Arvo and OpenTelemetry fields removed
          *
          * @remarks
-         * This getter returns only the custom extensions (TExtension) added to the ArvoEvent,
-         * excluding the standard Arvo and OpenTelemetry extensions.
-         * For accessing all extensions including Arvo and OpenTelemetry,
-         * use `<ArvoEvent>.cloudevent.extensions`.
-         * For accessing the basic CloudEvent fields, use `<ArvoEvent>.cloudevent.default`.
+         * For accessing all extensions including Arvo and OpenTelemetry, use `cloudevent.extensions`.
+         * For accessing basic CloudEvent fields, use `cloudevent.default`.
+         * Custom extension keys must follow lowercase alphanumeric naming (a-z, 0-9 only).
          */
         get: function () {
             var _a = this
-                ._extensions, traceparent = _a.traceparent, tracestate = _a.tracestate, to = _a.to, redirectto = _a.redirectto, accesscontrol = _a.accesscontrol, executionunits = _a.executionunits, rest = __rest(_a, ["traceparent", "tracestate", "to", "redirectto", "accesscontrol", "executionunits"]);
+                ._extensions, traceparent = _a.traceparent, tracestate = _a.tracestate, to = _a.to, redirectto = _a.redirectto, accesscontrol = _a.accesscontrol, executionunits = _a.executionunits, parentid = _a.parentid, domain = _a.domain, rest = __rest(_a, ["traceparent", "tracestate", "to", "redirectto", "accesscontrol", "executionunits", "parentid", "domain"]);
             return rest;
         },
         enumerable: false,

package/dist/ArvoEvent/schema.d.ts

@@ -58,16 +58,22 @@ export declare const ArvoExtensionSchema: z.ZodObject<{
     accesscontrol: z.ZodNullable<z.ZodString>;
     redirectto: z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>;
     executionunits: z.ZodNullable<z.ZodNumber>;
+    parentid: z.ZodNullable<z.ZodString>;
+    domain: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     to: string | null;
     accesscontrol: string | null;
     redirectto: string | null;
     executionunits: number | null;
+    parentid: string | null;
+    domain: string | null;
 }, {
     to: string | null;
     accesscontrol: string | null;
     redirectto: string | null;
     executionunits: number | null;
+    parentid: string | null;
+    domain: string | null;
 }>;
 /**
  * Zod schema for validating OpenTelemetry extensions to the CloudEvent.

package/dist/ArvoEvent/schema.js

@@ -101,6 +101,17 @@ exports.ArvoExtensionSchema = zod_1.z
         .number()
         .nullable()
         .describe((0, utils_1.cleanString)("\n      This data field represents the cost associated with \n      generating this specific cloudevent. It serves as a metric \n      to track and measure the financial impact of event generation\n      within cloud-based systems or applications.\n    ")),
+    parentid: zod_1.z
+        .string()
+        .min(1, 'ID must be a non-empty string')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      The unique identifier of the event that directly triggered the creation \n      of this event within the Arvo ecosystem. When set, it establishes a \n      direct causal relationship for event lineage tracking and workflow \n      orchestration. When null, it indicates this is an initiating event \n      or was generated outside of direct event causation.\n      ")),
+    domain: zod_1.z
+        .string()
+        .min(1, 'Domain must be non-empty string')
+        .regex(/^[a-z0-9.]+$/, 'Domain must contain only lowercase letters, numbers, and dots')
+        .nullable()
+        .describe((0, utils_1.cleanString)("\n      Specifies the processing domain for event routing and workflow orchestration.\n      Events can be assigned to specific domains (e.g., 'external', 'analytics', 'priority')\n      to enable specialized processing flows such as human-in-the-loop operations,\n      third-party integrations, or custom handling pipelines. Each event can only\n      belong to one domain - if an event needs to be processed by multiple domains,\n      separate identical events (with different IDs) must be created for each respective\n      domain. Domain names must contain only lowercase letters, numbers, and dots.\n    ")),
 })
     .describe('Schema for Arvo-specific extensions to the CloudEvent.');
 /**

package/dist/ArvoEvent/types.d.ts

@@ -59,4 +59,8 @@ export type CreateArvoEvent<TData extends ArvoEventData, TType extends string> =
     traceparent?: string;
     /** Conveys vendor-specific trace information across service boundaries (OpenTelemetry). */
     tracestate?: string;
+    /** The unique identifier of the event that directly triggered the creation of this event within the Arvo ecosystem. */
+    parentid?: string;
+    /** Specifies the processing domain for event routing and workflow orchestration. Must contain only lowercase letters, numbers, and dots. */
+    domain?: string;
 };

package/dist/ArvoEventFactory/Orchestrator.d.ts

@@ -27,8 +27,9 @@ export declare class ArvoOrchestratorEventFactory<TContract extends VersionedArv
      *
      * @throws Error if event validation fails
      */
-    init<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['accepts']['schema']>, TContract['accepts']['type']>, 'type' | 'datacontenttype' | 'dataschema' | 'subject'> & {
+    init<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['accepts']['schema']>, TContract['accepts']['type']>, 'type' | 'datacontenttype' | 'dataschema' | 'subject' | 'domain'> & {
         subject?: string;
+        domain?: string | null;
     }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TContract["accepts"]["schema"]>, TExtension, TContract["accepts"]["type"]>;
     /**
      * Creates a completion event for the orchestration flow.
@@ -40,7 +41,8 @@ export declare class ArvoOrchestratorEventFactory<TContract extends VersionedArv
      *
      * @throws Error if event validation fails or complete event type not configured
      */
-    complete<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['emits'][TContract['metadata']['completeEventType']]>, TContract['metadata']['completeEventType']>, 'datacontenttype' | 'dataschema' | 'type' | 'subject'> & {
+    complete<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['emits'][TContract['metadata']['completeEventType']]>, TContract['metadata']['completeEventType']>, 'datacontenttype' | 'dataschema' | 'type' | 'subject' | 'domain'> & {
         subject?: string;
+        domain?: string | null;
     }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TContract["emits"][TContract["metadata"]["completeEventType"]]>, TExtension, TContract["metadata"]["completeEventType"]>;
 }

package/dist/ArvoEventFactory/Orchestrator.js

@@ -77,7 +77,7 @@ var ArvoOrchestratorEventFactory = /** @class */ (function (_super) {
             name: "".concat(this._name, ".init"),
             spanOptions: (0, utils_2.createSpanOptions)(this.contract),
             fn: function (span) {
-                var _a, _b, _c, _d, _e, _f;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
                 var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
                 var validationResult = _this.contract.accepts.schema.safeParse(event.data);
                 if (!validationResult.success) {
@@ -97,13 +97,14 @@ var ArvoOrchestratorEventFactory = /** @class */ (function (_super) {
                         orchestator: _this.contract.accepts.type,
                         initiator: event.source,
                         version: _this.contract.version,
+                        domain: event.domain === null ? undefined : ((_d = (_c = event.domain) !== null && _c !== void 0 ? _c : _this.contract.domain) !== null && _d !== void 0 ? _d : undefined),
                         meta: event.redirectto
                             ? {
                                 redirectto: event.redirectto,
                             }
                             : undefined,
                     }));
-                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_d = (_c = event.traceparent) !== null && _c !== void 0 ? _c : otelHeaders.traceparent) !== null && _d !== void 0 ? _d : undefined, tracestate: (_f = (_e = event.tracestate) !== null && _e !== void 0 ? _e : otelHeaders.tracestate) !== null && _f !== void 0 ? _f : undefined, type: _this.contract.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data }), extensions, { disable: true });
+                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_f = (_e = event.traceparent) !== null && _e !== void 0 ? _e : otelHeaders.traceparent) !== null && _f !== void 0 ? _f : undefined, tracestate: (_h = (_g = event.tracestate) !== null && _g !== void 0 ? _g : otelHeaders.tracestate) !== null && _h !== void 0 ? _h : undefined, type: _this.contract.accepts.type, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data, domain: event.domain === null ? undefined : ((_k = (_j = event.domain) !== null && _j !== void 0 ? _j : _this.contract.domain) !== null && _k !== void 0 ? _k : undefined) }), extensions, { disable: true });
                 span.setAttributes(generatedEvent.otelAttributes);
                 return generatedEvent;
             },
@@ -125,7 +126,7 @@ var ArvoOrchestratorEventFactory = /** @class */ (function (_super) {
             name: "".concat(this._name, ".complete"),
             spanOptions: (0, utils_2.createSpanOptions)(this.contract),
             fn: function (span) {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
                 var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
                 var validationResult = (_b = (_a = _this.contract.emits) === null || _a === void 0 ? void 0 : _a[_this.contract.metadata.completeEventType]) === null || _b === void 0 ? void 0 : _b.safeParse(event.data);
                 if (!(validationResult === null || validationResult === void 0 ? void 0 : validationResult.success)) {
@@ -137,13 +138,14 @@ var ArvoOrchestratorEventFactory = /** @class */ (function (_super) {
                     initiator: event.source,
                     version: _this.contract.version,
                     orchestator: eventType,
+                    domain: event.domain === null ? undefined : ((_g = (_f = event.domain) !== null && _f !== void 0 ? _f : _this.contract.domain) !== null && _g !== void 0 ? _g : undefined),
                     meta: event.redirectto
                         ? {
                             redirectto: event.redirectto,
                         }
                         : undefined,
                 });
-                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, type: eventType, traceparent: (_g = (_f = event.traceparent) !== null && _f !== void 0 ? _f : otelHeaders.traceparent) !== null && _g !== void 0 ? _g : undefined, tracestate: (_j = (_h = event.tracestate) !== null && _h !== void 0 ? _h : otelHeaders.tracestate) !== null && _j !== void 0 ? _j : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data }), extensions, { disable: true });
+                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, type: eventType, traceparent: (_j = (_h = event.traceparent) !== null && _h !== void 0 ? _h : otelHeaders.traceparent) !== null && _j !== void 0 ? _j : undefined, tracestate: (_l = (_k = event.tracestate) !== null && _k !== void 0 ? _k : otelHeaders.tracestate) !== null && _l !== void 0 ? _l : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data, domain: event.domain === null ? undefined : ((_o = (_m = event.domain) !== null && _m !== void 0 ? _m : _this.contract.domain) !== null && _o !== void 0 ? _o : undefined) }), extensions, { disable: true });
                 span.setAttributes(generatedEvent.otelAttributes);
                 return generatedEvent;
             },

package/dist/ArvoEventFactory/index.d.ts

@@ -44,8 +44,9 @@ export default class ArvoEventFactory<TContract extends VersionedArvoContract<an
      * });
      * ```
      */
-    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['accepts']['schema']>, TContract['accepts']['type']>, 'type' | 'datacontenttype' | 'dataschema' | 'subject'> & {
+    accepts<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['accepts']['schema']>, TContract['accepts']['type']>, 'type' | 'datacontenttype' | 'dataschema' | 'subject' | 'domain'> & {
         subject?: string;
+        domain?: string | null;
     }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TContract["accepts"]["schema"]>, TExtension, TContract["accepts"]["type"]>;
     /**
      * Creates and validates an event matching one of the contract's emit specifications.
@@ -66,8 +67,9 @@ export default class ArvoEventFactory<TContract extends VersionedArvoContract<an
      * });
      * ```
      */
-    emits<U extends string & keyof TContract['emits'], TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['emits'][U]>, U>, 'datacontenttype' | 'dataschema' | 'subject'> & {
+    emits<U extends string & keyof TContract['emits'], TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<z.input<TContract['emits'][U]>, U>, 'datacontenttype' | 'dataschema' | 'subject' | 'domain'> & {
         subject?: string;
+        domain?: string | null;
     }, extensions?: TExtension): import("..").ArvoEvent<z.TypeOf<TContract["emits"][U]>, TExtension, U>;
     /**
      * Creates a system error event for error reporting and handling.
@@ -88,9 +90,10 @@ export default class ArvoEventFactory<TContract extends VersionedArvoContract<an
      * });
      * ```
      */
-    systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema' | 'subject'> & {
+    systemError<TExtension extends Record<string, any>>(event: Omit<CreateArvoEvent<any, any>, 'data' | 'type' | 'datacontenttype' | 'dataschema' | 'subject' | 'domain'> & {
         error: Error;
         subject?: string;
+        domain?: string | null;
     }, extensions?: TExtension): import("..").ArvoEvent<{
         errorName: string;
         errorMessage: string;

package/dist/ArvoEventFactory/index.js

@@ -81,7 +81,7 @@ var ArvoEventFactory = /** @class */ (function () {
             name: "".concat(this._name, ".accepts"),
             spanOptions: (0, utils_2.createSpanOptions)(this.contract),
             fn: function (span) {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _e, _f, _g;
                 var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
                 var validationResult = _this.contract.accepts.schema.safeParse(event.data);
                 if (!validationResult.success) {
@@ -98,7 +98,7 @@ var ArvoEventFactory = /** @class */ (function () {
                         }
                         : undefined,
                 });
-                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_c = (_b = event.traceparent) !== null && _b !== void 0 ? _b : otelHeaders.traceparent) !== null && _c !== void 0 ? _c : undefined, tracestate: (_e = (_d = event.tracestate) !== null && _d !== void 0 ? _d : otelHeaders.tracestate) !== null && _e !== void 0 ? _e : undefined, type: eventType, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data }), extensions, { disable: true });
+                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_c = (_b = event.traceparent) !== null && _b !== void 0 ? _b : otelHeaders.traceparent) !== null && _c !== void 0 ? _c : undefined, tracestate: (_e = (_d = event.tracestate) !== null && _d !== void 0 ? _d : otelHeaders.tracestate) !== null && _e !== void 0 ? _e : undefined, type: eventType, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data, domain: event.domain === null ? undefined : ((_g = (_f = event.domain) !== null && _f !== void 0 ? _f : _this.contract.domain) !== null && _g !== void 0 ? _g : undefined) }), extensions, { disable: true });
                 span.setAttributes(generatedEvent.otelAttributes);
                 return generatedEvent;
             },
@@ -129,7 +129,7 @@ var ArvoEventFactory = /** @class */ (function () {
             name: "".concat(this._name, ".emits<").concat(event.type, ">"),
             spanOptions: (0, utils_2.createSpanOptions)(this.contract),
             fn: function (span) {
-                var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+                var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
                 var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
                 var validationResult = (_b = (_a = _this.contract.emits) === null || _a === void 0 ? void 0 : _a[event.type]) === null || _b === void 0 ? void 0 : _b.safeParse(event.data);
                 if (!(validationResult === null || validationResult === void 0 ? void 0 : validationResult.success)) {
@@ -146,7 +146,7 @@ var ArvoEventFactory = /** @class */ (function () {
                         }
                         : undefined,
                 });
-                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_g = (_f = event.traceparent) !== null && _f !== void 0 ? _f : otelHeaders.traceparent) !== null && _g !== void 0 ? _g : undefined, tracestate: (_j = (_h = event.tracestate) !== null && _h !== void 0 ? _h : otelHeaders.tracestate) !== null && _j !== void 0 ? _j : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data }), extensions, { disable: true });
+                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, event), { subject: eventSubject, traceparent: (_g = (_f = event.traceparent) !== null && _f !== void 0 ? _f : otelHeaders.traceparent) !== null && _g !== void 0 ? _g : undefined, tracestate: (_j = (_h = event.tracestate) !== null && _h !== void 0 ? _h : otelHeaders.tracestate) !== null && _j !== void 0 ? _j : undefined, datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.create(_this.contract), data: validationResult.data, domain: event.domain === null ? undefined : ((_l = (_k = event.domain) !== null && _k !== void 0 ? _k : _this.contract.domain) !== null && _l !== void 0 ? _l : undefined) }), extensions, { disable: true });
                 span.setAttributes(generatedEvent.otelAttributes);
                 return generatedEvent;
             },
@@ -177,7 +177,7 @@ var ArvoEventFactory = /** @class */ (function () {
             name: "".concat(this._name, ".systemError"),
             spanOptions: (0, utils_2.createSpanOptions)(this.contract),
             fn: function (span) {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _e, _f, _g;
                 var otelHeaders = (0, OpenTelemetry_1.currentOpenTelemetryHeaders)();
                 var error = event.error, _event = __rest(event, ["error"]);
                 var eventType = _this.contract.systemError.type;
@@ -191,7 +191,7 @@ var ArvoEventFactory = /** @class */ (function () {
                         }
                         : undefined,
                 });
-                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, _event), { subject: eventSubject, traceparent: (_c = (_b = event.traceparent) !== null && _b !== void 0 ? _b : otelHeaders.traceparent) !== null && _c !== void 0 ? _c : undefined, tracestate: (_e = (_d = event.tracestate) !== null && _d !== void 0 ? _d : otelHeaders.tracestate) !== null && _e !== void 0 ? _e : undefined, type: eventType, data: (0, utils_1.createArvoError)(error), datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.createWithWildCardVersion(_this.contract) }), extensions, { disable: true });
+                var generatedEvent = (0, helpers_1.createArvoEvent)(__assign(__assign({}, _event), { subject: eventSubject, traceparent: (_c = (_b = event.traceparent) !== null && _b !== void 0 ? _b : otelHeaders.traceparent) !== null && _c !== void 0 ? _c : undefined, tracestate: (_e = (_d = event.tracestate) !== null && _d !== void 0 ? _d : otelHeaders.tracestate) !== null && _e !== void 0 ? _e : undefined, type: eventType, data: (0, utils_1.createArvoError)(error), datacontenttype: schema_1.ArvoDataContentType, dataschema: utils_1.EventDataschemaUtil.createWithWildCardVersion(_this.contract), domain: event.domain === null ? undefined : ((_g = (_f = event.domain) !== null && _f !== void 0 ? _f : _this.contract.domain) !== null && _g !== void 0 ? _g : undefined) }), extensions, { disable: true });
                 span.setAttributes(generatedEvent.otelAttributes);
                 return generatedEvent;
             },

package/dist/ArvoOrchestrationSubject/index.d.ts

@@ -40,6 +40,7 @@ export default class ArvoOrchestrationSubject {
         orchestator: string;
         version: ArvoSemanticVersion | null;
         initiator: string;
+        domain?: string;
         meta?: Record<string, string>;
     }): string;
     /**

package/dist/ArvoOrchestrationSubject/index.js

@@ -59,7 +59,7 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
      * ```
      */
     ArvoOrchestrationSubject.new = function (param) {
-        var _a, _b;
+        var _a, _b, _c;
         return ArvoOrchestrationSubject.create({
             orchestrator: {
                 name: param.orchestator,
@@ -68,8 +68,9 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
             execution: {
                 id: (0, uuid_1.v4)(),
                 initiator: param.initiator,
+                domain: (_b = param.domain) !== null && _b !== void 0 ? _b : null,
             },
-            meta: (_b = param.meta) !== null && _b !== void 0 ? _b : {},
+            meta: (_c = param.meta) !== null && _c !== void 0 ? _c : {},
         });
     };
     /**
@@ -106,13 +107,14 @@ var ArvoOrchestrationSubject = /** @class */ (function () {
      * ```
      */
     ArvoOrchestrationSubject.from = function (param) {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         var parsedSubject = ArvoOrchestrationSubject.parse(param.subject);
         return ArvoOrchestrationSubject.new({
             initiator: parsedSubject.orchestrator.name,
             version: (_a = param.version) !== null && _a !== void 0 ? _a : WildCardArvoSemanticVersion_1.WildCardArvoSemanticVersion,
             orchestator: param.orchestator,
-            meta: __assign(__assign({}, ((_b = parsedSubject.meta) !== null && _b !== void 0 ? _b : {})), ((_c = param.meta) !== null && _c !== void 0 ? _c : {})),
+            domain: (_b = parsedSubject.execution.domain) !== null && _b !== void 0 ? _b : undefined,
+            meta: __assign(__assign({}, ((_c = parsedSubject.meta) !== null && _c !== void 0 ? _c : {})), ((_d = param.meta) !== null && _d !== void 0 ? _d : {})),
         });
     };
     /**

package/dist/ArvoOrchestrationSubject/schema.d.ts

@@ -13,11 +13,14 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
     execution: z.ZodObject<{
         id: z.ZodEffects<z.ZodString, string, string>;
         initiator: z.ZodEffects<z.ZodString, string, string>;
+        domain: z.ZodNullable<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         id: string;
+        domain: string | null;
         initiator: string;
     }, {
         id: string;
+        domain: string | null;
         initiator: string;
     }>;
     meta: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -28,6 +31,7 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
     };
     execution: {
         id: string;
+        domain: string | null;
         initiator: string;
     };
     meta: Record<string, string>;
@@ -38,6 +42,7 @@ export declare const ArvoOrchestrationSubjectContentSchema: z.ZodObject<{
     };
     execution: {
         id: string;
+        domain: string | null;
         initiator: string;
     };
     meta: Record<string, string>;

package/dist/ArvoOrchestrationSubject/schema.js

@@ -29,6 +29,12 @@ exports.ArvoOrchestrationSubjectContentSchema = zod_1.z
             .regex(/^[a-z0-9]+(\.[a-z0-9]+)+\.[a-z0-9]+$/, 'Orchestration initiator should be prefixed with a reverse-DNS name')
             .refine(function (value) { return !value.includes(';'); }, 'Initiator must not contain semicolon')
             .describe('Entity or process that initiated the execution'),
+        domain: zod_1.z
+            .string()
+            .min(1, 'The domain must be non-empty string')
+            .regex(/^[a-z0-9.]+$/, 'Domain must contain only lowercase letters, numbers, and dots')
+            .nullable()
+            .describe('The domain of the orchestration init event'),
     })
         .describe('Details about the current execution'),
     meta: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).describe((0, utils_1.cleanString)("\n        Additional metadata for the orchestration process. Store essential key-value pairs \n        that provide context or configuration details necessary for the orchestration. \n        Use selectively to maintain clarity and avoid storing unnecessary information.  \n      ")),

package/dist/ArvoOrchestrationSubject/type.d.ts

@@ -48,6 +48,8 @@ export type ArvoOrchestrationSubjectContent = {
          * "com.example.initiator-service"
          */
         initiator: string;
+        /** The domain of the init event */
+        domain: string | null;
     };
     /**
      * Additional metadata for the orchestration process. Store essential key-value pairs

package/dist/ArvoOrchestratorContract/index.js

@@ -94,15 +94,16 @@ function isLowerAlphanumeric(input) {
  * ```
  */
 var createArvoOrchestratorContract = function (contract) {
-    var _a, _b;
+    var _a, _b, _c;
     if (!isLowerAlphanumeric(contract.name)) {
         throw new Error("Invalid 'name' = '".concat(contract.name, "'. The 'name' must only contain alphanumeric characters. e.g. test.orchestrator"));
     }
     var mergedMetaData = __assign(__assign({}, ((_a = contract.metadata) !== null && _a !== void 0 ? _a : {})), { contractType: 'ArvoOrchestratorContract', rootType: contract.name, completeEventType: typegen_1.ArvoOrchestratorEventTypeGen.complete(contract.name), initEventType: typegen_1.ArvoOrchestratorEventTypeGen.init(contract.name) });
     return new ArvoContract_1.default({
         uri: contract.uri,
+        domain: (_b = contract.domain) !== null && _b !== void 0 ? _b : null,
         type: typegen_1.ArvoOrchestratorEventTypeGen.init(contract.name),
-        description: (_b = contract.description) !== null && _b !== void 0 ? _b : null,
+        description: (_c = contract.description) !== null && _c !== void 0 ? _c : null,
         metadata: mergedMetaData,
         versions: Object.fromEntries(Object.entries(contract.versions).map(function (_a) {
             var _b;

package/dist/ArvoOrchestratorContract/types.d.ts

@@ -68,4 +68,5 @@ export interface ICreateArvoOrchestratorContract<TUri extends string, TName exte
     versions: TVersions;
     metadata?: TMetaData;
     description?: string;
+    domain?: string;
 }

package/dist/index.d.ts

@@ -74,16 +74,22 @@ declare const ArvoEventSchema: {
         accesscontrol: import("zod").ZodNullable<import("zod").ZodString>;
         redirectto: import("zod").ZodNullable<import("zod").ZodEffects<import("zod").ZodString, string, string>>;
         executionunits: import("zod").ZodNullable<import("zod").ZodNumber>;
+        parentid: import("zod").ZodNullable<import("zod").ZodString>;
+        domain: import("zod").ZodNullable<import("zod").ZodString>;
     }, "strip", import("zod").ZodTypeAny, {
         to: string | null;
         accesscontrol: string | null;
         redirectto: string | null;
         executionunits: number | null;
+        parentid: string | null;
+        domain: string | null;
     }, {
         to: string | null;
         accesscontrol: string | null;
         redirectto: string | null;
         executionunits: number | null;
+        parentid: string | null;
+        domain: string | null;
     }>;
     OpenTelemetryExtensionSchema: import("zod").ZodObject<{
         traceparent: import("zod").ZodNullable<import("zod").ZodString>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
   "main": "dist/index.js",
   "scripts": {