@nextage/era-lib 1.0.174 → 1.0.176

package/build/events/base-event.controller.d.ts

@@ -30,6 +30,35 @@ export declare abstract class BaseEventCtrl<TCreate extends Event, TUpdate exten
      */
     publish(item: TAttrs, type: QueueEventType, context: NxContext): Promise<void>;
     /**
+     * Overridable post-write / post-read enrichment of the RETURNED document (e.g.
+     * populate references, attach a joined aggregate). Runs AFTER the atomic write
+     * and event dispatch, so a subclass can shape the doc handed back to its
+     * resolvers WITHOUT overriding create / update / get — which would shadow the
+     * transactional outbox (that was the E3 regression). Default: identity.
+     *
+     * @param doc
+     * @param context
+     */
+    protected decorateDoc(doc: TDoc, context: NxContext): Promise<TDoc>;
+    /**
+     * Read one entity and apply the subclass `decorateDoc` enrichment.
+     *
+     * @param id
+     * @param context
+     */
+    get(id: string, context?: NxContext): Promise<TDoc | null>;
+    /**
+     *
+     * @param item
+     * @param context
+     * @returns
+     */
+    /**
+     * Create the entity and its outbox row ATOMICALLY (same transaction when the
+     * deployment supports it), then dispatch the event and mark the row sent after
+     * commit. A broker failure leaves the row at sent:false (recoverable), never a
+     * lost event (fixes the E2 non-atomic gap; the per-controller override that used
+     * to do this 3-op dance is removed — E3).
      *
      * @param item
      * @param context
@@ -38,6 +67,7 @@ export declare abstract class BaseEventCtrl<TCreate extends Event, TUpdate exten
     create(item: TAttrs, context: NxContext): Promise<TDoc>;
     /**
      *
+     * @param id
      * @param item
      * @param context
      * @returns
@@ -45,10 +75,31 @@ export declare abstract class BaseEventCtrl<TCreate extends Event, TUpdate exten
     update(id: string, item: TAttrs, context: NxContext): Promise<TDoc>;
     /**
      *
-     * @param item
+     * @param id
      * @param context
      * @returns
      */
     remove(id: string, context: NxContext): Promise<TDoc>;
+    /**
+     * Persist an outbox row (sent:false) for `item` inside the caller's transaction.
+     * Returns the row id, or undefined when no outbox is registered (the event is
+     * then still published, just not tracked).
+     *
+     * @param item
+     * @param type
+     * @param context
+     */
+    private enqueueOutbox;
+    /**
+     * Dispatch the event to the broker, then mark the outbox row as sent. Runs AFTER
+     * the transaction commits, so `publish` (a non-DB side effect) is never retried
+     * by `withTransaction` and a broker failure leaves a recoverable sent:false row.
+     *
+     * @param item
+     * @param type
+     * @param outboxId
+     * @param context
+     */
+    private dispatchOutbox;
 }
 //# sourceMappingURL=base-event.controller.d.ts.map

package/build/events/base-event.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-event.controller.d.ts","sourceRoot":"","sources":["../../src/events/base-event.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAc,mDAAmD,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAW,wDAAwD,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAS,wDAAwD,CAAC;AAC3F,OAAO,EAAE,SAAS,EAAE,MAAc,sBAAsB,CAAC;AAGzD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAS,eAAe,CAAC;AAOlD,8BAAsB,aAAa,CAAC,OAAO,SAAS,KAAK,EAAE,OAAO,SAAS,KAAK,EAAE,OAAO,SAAS,KAAK,EAAE,MAAM,EAAE,IAAI,SAAS,YAAY,EAAE,MAAM,SAAS,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAE,SAAQ,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;IAMnO,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAC3F,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAC3F,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAE3F,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAK1D,OAAO,CAAC,aAAa,CAAC,CAAmD;IAEzE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;;;;OAKG;IAoBH;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpF;;;;;OAKG;IACY,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtE;;;;;OAKG;IACY,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlF;;;;;OAKG;IACY,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAOrE"}
+{"version":3,"file":"base-event.controller.d.ts","sourceRoot":"","sources":["../../src/events/base-event.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAc,mDAAmD,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAW,wDAAwD,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAS,wDAAwD,CAAC;AAE3F,OAAO,EAAE,SAAS,EAAE,MAAc,sBAAsB,CAAC;AAGzD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAKjD,OAAO,EAAE,cAAc,EAAE,MAAS,eAAe,CAAC;AAOlD,8BAAsB,aAAa,CAAC,OAAO,SAAS,KAAK,EAAE,OAAO,SAAS,KAAK,EAAE,OAAO,SAAS,KAAK,EAAE,MAAM,EAAE,IAAI,SAAS,YAAY,EAAE,MAAM,SAAS,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAE,SAAQ,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC;IAMnO,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAC3F,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAC3F,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAI,OAAO,CAAC,MAAM,CAAC;IAE3F,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1D,SAAS,CAAC,QAAQ,CAAC,eAAe,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IAK1D,OAAO,CAAC,aAAa,CAAC,CAAmD;IAEzE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;;;;OAKG;IAoBH;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpF;;;;;;;;;OASG;cACa,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;;;;OAKG;IACY,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAMzE;;;;;OAKG;IACH;;;;;;;;;;OAUG;IACY,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBtE;;;;;;OAMG;IACY,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlF;;;;;OAKG;IACY,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBpE;;;;;;;;OAQG;YACW,aAAa;IAY3B;;;;;;;;;OASG;YACW,cAAc;CAQ7B"}

package/build/events/base-event.controller.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseEventCtrl = void 0;
 const base_controller_1 = require("@nextage/nx-frame-be/build/common/base/base.controller");
+const mongo_utils_1 = require("@nextage/nx-frame-be/build/common/base/mongo-utils");
+const outbox_1 = require("./outbox");
+const cascade_1 = require("./cascade");
 const enums_1 = require("./types/enums");
 class BaseEventCtrl extends base_controller_1.BaseController {
     /**
@@ -59,41 +62,132 @@ class BaseEventCtrl extends base_controller_1.BaseController {
         if (!publishers?.length || !parser)
             return;
         const data = parser(item, type);
-        await Promise.all(publishers.map(pub => pub.publish(data)));
+        const meta = (0, cascade_1.outgoingMeta)(context?._event);
+        await Promise.all(publishers.map(pub => pub.publish(data, meta)));
     }
     /**
+     * Overridable post-write / post-read enrichment of the RETURNED document (e.g.
+     * populate references, attach a joined aggregate). Runs AFTER the atomic write
+     * and event dispatch, so a subclass can shape the doc handed back to its
+     * resolvers WITHOUT overriding create / update / get — which would shadow the
+     * transactional outbox (that was the E3 regression). Default: identity.
+     *
+     * @param doc
+     * @param context
+     */
+    async decorateDoc(doc, context) {
+        return doc;
+    }
+    /**
+     * Read one entity and apply the subclass `decorateDoc` enrichment.
+     *
+     * @param id
+     * @param context
+     */
+    async get(id, context) {
+        const doc = await super.get(id, context);
+        return doc ? this.decorateDoc(doc, context ?? {}) : doc;
+    }
+    /**
+     *
+     * @param item
+     * @param context
+     * @returns
+     */
+    /**
+     * Create the entity and its outbox row ATOMICALLY (same transaction when the
+     * deployment supports it), then dispatch the event and mark the row sent after
+     * commit. A broker failure leaves the row at sent:false (recoverable), never a
+     * lost event (fixes the E2 non-atomic gap; the per-controller override that used
+     * to do this 3-op dance is removed — E3).
      *
      * @param item
      * @param context
      * @returns
      */
     async create(item, context) {
-        const res = await super.create(item, context); // this.model.create(item, context);
-        await this.publish(res.toJSON(), enums_1.QueueEventType.create, context);
-        return res;
+        let payload;
+        let outboxId;
+        const res = await this.withTransaction(context, async (ctx) => {
+            const created = await super.create(item, ctx);
+            payload = created.toJSON();
+            outboxId = await this.enqueueOutbox(payload, enums_1.QueueEventType.create, ctx);
+            return created;
+        });
+        await this.dispatchOutbox(payload, enums_1.QueueEventType.create, outboxId, context);
+        return this.decorateDoc(res, context);
     }
     /**
      *
+     * @param id
      * @param item
      * @param context
      * @returns
      */
     async update(id, item, context) {
-        const res = await super.update(id, item, context);
-        await this.publish({ id, ...res.toObject() }, enums_1.QueueEventType.update, context);
-        return res;
+        let payload;
+        let outboxId;
+        const res = await this.withTransaction(context, async (ctx) => {
+            const updated = await super.update(id, item, ctx);
+            payload = { id, ...updated.toObject() };
+            outboxId = await this.enqueueOutbox(payload, enums_1.QueueEventType.update, ctx);
+            return updated;
+        });
+        await this.dispatchOutbox(payload, enums_1.QueueEventType.update, outboxId, context);
+        return this.decorateDoc(res, context);
     }
     /**
      *
-     * @param item
+     * @param id
      * @param context
      * @returns
      */
     async remove(id, context) {
-        const res = await this.model.remove(id, context);
-        await this.publish({ id, ...res.toObject() }, enums_1.QueueEventType.remove, context);
+        let payload;
+        let outboxId;
+        const res = await this.withTransaction(context, async (ctx) => {
+            const removed = await this.model.remove(id, ctx);
+            payload = { id, ...removed.toObject() };
+            outboxId = await this.enqueueOutbox(payload, enums_1.QueueEventType.remove, ctx);
+            return removed;
+        });
+        await this.dispatchOutbox(payload, enums_1.QueueEventType.remove, outboxId, context);
         return res;
     }
+    /**
+     * Persist an outbox row (sent:false) for `item` inside the caller's transaction.
+     * Returns the row id, or undefined when no outbox is registered (the event is
+     * then still published, just not tracked).
+     *
+     * @param item
+     * @param type
+     * @param context
+     */
+    async enqueueOutbox(item, type, context) {
+        const outbox = (0, outbox_1.getOutbox)();
+        if (!outbox)
+            return undefined;
+        const id = (0, mongo_utils_1.genObjectId)().toString();
+        const evt = { id, type, data: item };
+        await outbox.create(evt, context);
+        return id;
+    }
+    /**
+     * Dispatch the event to the broker, then mark the outbox row as sent. Runs AFTER
+     * the transaction commits, so `publish` (a non-DB side effect) is never retried
+     * by `withTransaction` and a broker failure leaves a recoverable sent:false row.
+     *
+     * @param item
+     * @param type
+     * @param outboxId
+     * @param context
+     */
+    async dispatchOutbox(item, type, outboxId, context) {
+        await this.publish(item, type, context);
+        const outbox = (0, outbox_1.getOutbox)();
+        if (outbox && outboxId)
+            await outbox.markSent(outboxId, context);
+    }
 }
 exports.BaseEventCtrl = BaseEventCtrl;
 //# sourceMappingURL=base-event.controller.js.map

package/build/events/base-event.controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-event.controller.js","sourceRoot":"","sources":["../../src/events/base-event.controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-event.controller.js","sourceRoot":"","sources":["../../src/events/base-event.controller.ts"],"names":[],"mappings":"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"}

package/build/events/base-listener.d.ts

@@ -1,5 +1,7 @@
+import { NxContext } from '@nextage/nx-frame-be';
 import { Message } from './event-message';
 import { Event, MsgClientInterface, EventSubOptions } from './interfaces';
+import { EventContext, IncomingEventRef } from './types/event-envelope.interfaces';
 export declare abstract class Listener<T extends Event> {
     abstract subject: T['subject'];
     abstract queueGroupName: string;
@@ -8,6 +10,7 @@ export declare abstract class Listener<T extends Event> {
     private subscription;
     private messageStack;
     private wait;
+    protected _incoming: IncomingEventRef | undefined;
     protected ackWait: number;
     constructor(client: MsgClientInterface);
     subscriptionOptions(): EventSubOptions;
@@ -17,6 +20,20 @@ export declare abstract class Listener<T extends Event> {
      * @returns
      */
     checkMessages(): Promise<void>;
+    /**
+     * Process a single message: unwrap the envelope, apply the cascade loop-guard,
+     * then dispatch to `onMessage`. A guard violation (runaway depth or revisited
+     * subject) is skipped — the in-memory bus has no ack/redelivery to fight — and
+     * the in-flight reference is always cleared so `nextContext` never leaks the
+     * previous event.
+     */
+    protected handleMessage(msg: Message): Promise<void>;
+    /**
+     * Build a child context carrying the in-flight event reference, so any event
+     * this listener republishes inherits the correlation and advances the cascade
+     * depth / visited lineage. Returns a fresh object (never mutates `base`).
+     */
+    protected nextContext(base?: NxContext): EventContext;
     /**
      *
      */

package/build/events/base-listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-listener.d.ts","sourceRoot":"","sources":["../../src/events/base-listener.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAA2C,iBAAiB,CAAC;AAE/E,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE1E,8BAAsB,QAAQ,CAAC,CAAC,SAAS,KAAK;IAE5C,QAAQ,CAAC,OAAO,EAAS,CAAC,CAAC,SAAS,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,YAAY,CAAmC;IAEvD,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,IAAI,CAA+B;IAE3C,SAAS,CAAC,OAAO,EAAQ,MAAM,CAAe;gBAEjC,MAAM,EAAE,kBAAkB;IAIvC,mBAAmB,IAAI,eAAe;IAKhC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB7B;;;OAGG;IACG,aAAa;IAkBnB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAKrB"}
+{"version":3,"file":"base-listener.d.ts","sourceRoot":"","sources":["../../src/events/base-listener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,SAAS,EAAE,MAAqB,sBAAsB,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,MAAyC,iBAAiB,CAAC;AAE7E,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAkB,mCAAmC,CAAC;AAG/F,8BAAsB,QAAQ,CAAC,CAAC,SAAS,KAAK;IAE5C,QAAQ,CAAC,OAAO,EAAS,CAAC,CAAC,SAAS,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,YAAY,CAAmC;IAEvD,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,IAAI,CAA+B;IAI3C,SAAS,CAAC,SAAS,EAAM,gBAAgB,GAAG,SAAS,CAAC;IAEtD,SAAS,CAAC,OAAO,EAAQ,MAAM,CAAe;gBAEjC,MAAM,EAAE,kBAAkB;IAIvC,mBAAmB,IAAI,eAAe;IAKhC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB7B;;;OAGG;IACG,aAAa;IAsBnB;;;;;;OAMG;cACa,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB1D;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,GAAE,SAAc,GAAG,YAAY;IAKzD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAKrB"}

package/build/events/base-listener.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Listener = void 0;
 const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const cascade_1 = require("./cascade");
 class Listener {
     constructor(client) {
         this.messageStack = [];
@@ -33,11 +34,45 @@ class Listener {
         if (!msg)
             return;
         this.wait = true;
-        const parsedData = this.parseMessage(msg);
-        const res = await this.onMessage(parsedData, msg);
-        this.wait = false;
+        try {
+            await this.handleMessage(msg);
+        }
+        finally {
+            this.wait = false;
+        }
         await this.checkMessages();
     }
+    /**
+     * Process a single message: unwrap the envelope, apply the cascade loop-guard,
+     * then dispatch to `onMessage`. A guard violation (runaway depth or revisited
+     * subject) is skipped — the in-memory bus has no ack/redelivery to fight — and
+     * the in-flight reference is always cleared so `nextContext` never leaks the
+     * previous event.
+     */
+    async handleMessage(msg) {
+        try {
+            const { id, data, meta } = (0, cascade_1.unwrapEnvelope)(this.parseMessage(msg));
+            const violation = (0, cascade_1.cascadeViolation)(meta, this.subject);
+            if (violation) {
+                nx_frame_be_1.APP.logger.warn(`🔁 Cascade guard tripped on '${this.subject}': ${violation}`, (0, nx_frame_be_1.logClassCtx)(this));
+            }
+            else {
+                this._incoming = { id, subject: this.subject, meta };
+                await this.onMessage(data, msg);
+            }
+        }
+        finally {
+            this._incoming = undefined;
+        }
+    }
+    /**
+     * Build a child context carrying the in-flight event reference, so any event
+     * this listener republishes inherits the correlation and advances the cascade
+     * depth / visited lineage. Returns a fresh object (never mutates `base`).
+     */
+    nextContext(base = {}) {
+        return this._incoming ? { ...base, _event: this._incoming } : { ...base };
+    }
     /**
      *
      */

package/build/events/base-listener.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-listener.js","sourceRoot":"","sources":["../../src/events/base-listener.ts"],"names":[],"mappings":";;;AAAA,sDAAoF;AAKpF,MAAsB,QAAQ;IAe5B,YAAa,MAA0B;QAL/B,iBAAY,GAAiB,EAAE,CAAC;QAChC,SAAI,GAAyB,KAAK,CAAC;QAEjC,YAAO,GAAoB,CAAC,GAAG,IAAI,CAAC;QAG5C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,mBAAmB;QAEjB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,MAAM;QAEV,IAAI,CAAC,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAC7C,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,cAAc,EACnB,IAAI,CAAC,mBAAmB,EAAE,CAC3B,CAAC;QAEF,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,GAAY,EAAE,EAAE;YAEhD,iBAAG,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,IAAI,CAAC,OAAO,MAAM,IAAI,CAAC,cAAc,EAAE,EAAE,IAAA,yBAAW,EAAC,IAAI,CAAC,CAAC,CAAC;YAEvG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,6CAA6C;YAC7C,mCAAmC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,aAAa;QAEjB,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM;YACxC,OAAO;QAET,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAEtC,IAAI,CAAC,GAAG;YACN,OAAO;QAET,IAAI,CAAC,IAAI,GAAU,IAAI,CAAC;QACxB,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAU,MAAM,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,GAAU,KAAK,CAAC;QAEzB,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QAER,IAAI,IAAI,CAAC,YAAY;YACnB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,GAAY;QAE/B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;QAC3B,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACzF,CAAC;CACF;AApFD,4BAoFC"}
+{"version":3,"file":"base-listener.js","sourceRoot":"","sources":["../../src/events/base-listener.ts"],"names":[],"mappings":"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"}

package/build/events/base-nats-listener.d.ts

@@ -1,4 +1,6 @@
+import { NxContext } from '@nextage/nx-frame-be';
 import { Event, MsgClientInterface, EventSubOptions } from './interfaces';
+import { EventContext, IncomingEventRef } from './types/event-envelope.interfaces';
 import { JsMsg } from 'nats';
 export declare abstract class NatsListener<T extends Event> {
     private readonly client;
@@ -7,6 +9,7 @@ export declare abstract class NatsListener<T extends Event> {
     abstract streamName: string;
     private consumer?;
     private isListening;
+    protected _incoming?: IncomingEventRef;
     protected ackWait: number;
     protected maxDeliver: number;
     protected nakBackoffMs: number[];
@@ -37,6 +40,20 @@ export declare abstract class NatsListener<T extends Event> {
      * than `term()`, so an unreachable DLQ never causes silent message loss.
      */
     protected handleMessage(msg: JsMsg): Promise<void>;
+    /**
+     * Park a cascade-guard violation on the DLQ and terminate it so it never
+     * re-enters the source stream. Falls back to `nak` only if the DLQ is
+     * unreachable, so a loop is never silently lost.
+     */
+    protected dropCascadeViolation(msg: JsMsg, reason: string): Promise<void>;
+    /**
+     * Build a child context carrying the in-flight event reference, so any event
+     * this listener republishes inherits the correlation, is marked as caused by
+     * the current event, and advances the cascade depth / visited lineage. Returns
+     * a fresh object (never mutates the shared base context). At the root — or when
+     * no event is in flight — it is just a copy of `base`.
+     */
+    protected nextContext(base?: NxContext): EventContext;
     /**
      * Parks a failed message on the DLQ stream. Returns `true` on success so the
      * caller can safely `term()` the original; returns `false` if the DLQ could

package/build/events/base-nats-listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-nats-listener.d.ts","sourceRoot":"","sources":["../../src/events/base-nats-listener.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E,OAAO,EAAY,KAAK,EAAE,MAAiC,MAAM,CAAC;AAElE,8BAAsB,YAAY,CAAC,CAAC,SAAS,KAAK;IAqBnC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBpC,QAAQ,CAAC,OAAO,EAAS,CAAC,CAAC,SAAS,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAM,MAAM,CAAC;IAEhC,OAAO,CAAC,QAAQ,CAAC,CAAiB;IAClC,OAAO,CAAC,WAAW,CAAsB;IAEzC,SAAS,CAAC,OAAO,EAAQ,MAAM,CAAuB;IACtD,SAAS,CAAC,UAAU,EAAK,MAAM,CAAK;IAMpC,SAAS,CAAC,YAAY,EAAG,MAAM,EAAE,CAAuB;IAGxD,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;gBAEhC,MAAM,EAAE,kBAAkB;IAExD;;;OAGG;IACH,mBAAmB,IAAI,eAAe;IAKtC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB7B;;;;OAIG;YACW,eAAe;IAqB7B;;;;;;;;OAQG;cACa,aAAa,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCxD;;;;OAIG;cACa,gBAAgB,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB9E;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAe3B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAKd;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAYrB"}
+{"version":3,"file":"base-nats-listener.d.ts","sourceRoot":"","sources":["../../src/events/base-nats-listener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,SAAS,EAAE,MAAkC,sBAAsB,CAAC;AAClF,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAkB,mCAAmC,CAAC;AAE/F,OAAO,EAAY,KAAK,EAAE,MAAiC,MAAM,CAAC;AAElE,8BAAsB,YAAY,CAAC,CAAC,SAAS,KAAK;IA2BnC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAzBpC,QAAQ,CAAC,OAAO,EAAS,CAAC,CAAC,SAAS,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAM,MAAM,CAAC;IAEhC,OAAO,CAAC,QAAQ,CAAC,CAAiB;IAClC,OAAO,CAAC,WAAW,CAAsB;IAMzC,SAAS,CAAC,SAAS,CAAC,EAAK,gBAAgB,CAAC;IAE1C,SAAS,CAAC,OAAO,EAAQ,MAAM,CAAuB;IACtD,SAAS,CAAC,UAAU,EAAK,MAAM,CAAK;IAMpC,SAAS,CAAC,YAAY,EAAG,MAAM,EAAE,CAAuB;IAGxD,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;gBAEhC,MAAM,EAAE,kBAAkB;IAExD;;;OAGG;IACH,mBAAmB,IAAI,eAAe;IAKtC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB7B;;;;OAIG;YACW,eAAe;IAqB7B;;;;;;;;OAQG;cACa,aAAa,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAmDxD;;;;OAIG;cACa,oBAAoB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/E;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,GAAE,SAAc,GAAG,YAAY;IAKzD;;;;OAIG;cACa,gBAAgB,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB9E;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAe3B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAKd;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAYrB"}

package/build/events/base-nats-listener.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsListener = void 0;
 const nx_frame_be_1 = require("@nextage/nx-frame-be");
 const dlq_constants_1 = require("./types/dlq.constants");
+const cascade_1 = require("./cascade");
 class NatsListener {
     constructor(client) {
         this.client = client;
@@ -75,8 +76,19 @@ class NatsListener {
     async handleMessage(msg) {
         try {
             nx_frame_be_1.APP.logger.info(`📥 Received message on '${this.subject}'`);
-            const parsed = this.parseMessage(msg);
-            await this.onMessage(parsed.data, msg);
+            const { id, data, meta } = (0, cascade_1.unwrapEnvelope)(this.parseMessage(msg));
+            // Cascade governance: a runaway depth or a revisited subject is a loop, not
+            // a transient failure — park it on the DLQ and drop it immediately (no
+            // retries, which would only replay the same loop three more times).
+            const violation = (0, cascade_1.cascadeViolation)(meta, this.subject);
+            if (violation) {
+                await this.dropCascadeViolation(msg, violation);
+                return;
+            }
+            // Expose the in-flight event so `onMessage` can thread its metadata into any
+            // republished event via `nextContext`.
+            this._incoming = { id, subject: this.subject, meta };
+            await this.onMessage(data, msg);
             msg.ack();
             nx_frame_be_1.APP.logger.info(`✅ Message acknowledged on '${this.subject}'`);
         }
@@ -94,6 +106,32 @@ class NatsListener {
                 msg.nak(this.backoffFor(deliveries));
             }
         }
+        finally {
+            this._incoming = undefined;
+        }
+    }
+    /**
+     * Park a cascade-guard violation on the DLQ and terminate it so it never
+     * re-enters the source stream. Falls back to `nak` only if the DLQ is
+     * unreachable, so a loop is never silently lost.
+     */
+    async dropCascadeViolation(msg, reason) {
+        nx_frame_be_1.APP.logger.warn(`🔁 Cascade guard tripped on '${this.subject}': ${reason}`);
+        const parked = await this.sendToDeadLetter(msg, new Error(`cascade-guard: ${reason}`));
+        if (parked)
+            msg.term();
+        else
+            msg.nak(this.backoffFor(this.deliveryAttempt(msg)));
+    }
+    /**
+     * Build a child context carrying the in-flight event reference, so any event
+     * this listener republishes inherits the correlation, is marked as caused by
+     * the current event, and advances the cascade depth / visited lineage. Returns
+     * a fresh object (never mutates the shared base context). At the root — or when
+     * no event is in flight — it is just a copy of `base`.
+     */
+    nextContext(base = {}) {
+        return this._incoming ? { ...base, _event: this._incoming } : { ...base };
     }
     /**
      * Parks a failed message on the DLQ stream. Returns `true` on success so the

package/build/events/base-nats-listener.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-nats-listener.js","sourceRoot":"","sources":["../../src/events/base-nats-listener.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-nats-listener.js","sourceRoot":"","sources":["../../src/events/base-nats-listener.ts"],"names":[],"mappings":"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"}

package/build/events/base-nats-publisher.d.ts

@@ -1,14 +1,19 @@
 import { JetStreamPublishOptions } from 'nats';
 import { Event, IPublisher, MsgClientInterface } from './interfaces';
+import { EventMeta } from './types/event-envelope.interfaces';
 export declare abstract class NatsPublisher<T extends Event> implements IPublisher<T, Partial<JetStreamPublishOptions>> {
     private readonly client;
     abstract subject: T['subject'];
     constructor(client: MsgClientInterface);
     /**
+     * Emit the event wrapped in the shared in-band envelope (id / subject / data /
+     * timestamp / cascade meta). The metadata rides in the payload so loop-guard and
+     * causation tracing stay transport agnostic.
      *
      * @param data
+     * @param meta
      * @param options
      */
-    publish(data: T['data'], options?: Partial<JetStreamPublishOptions>): Promise<void>;
+    publish(data: T['data'], meta?: EventMeta, options?: Partial<JetStreamPublishOptions>): Promise<void>;
 }
 //# sourceMappingURL=base-nats-publisher.d.ts.map

package/build/events/base-nats-publisher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-nats-publisher.d.ts","sourceRoot":"","sources":["../../src/events/base-nats-publisher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAoB,MAAM,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErE,8BAAsB,aAAa,CAAC,CAAC,SAAS,KAAK,CAAE,YAAW,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAIjG,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;gBAEF,MAAM,EAAE,kBAAkB;IAEvD;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB1F"}
+{"version":3,"file":"base-nats-publisher.d.ts","sourceRoot":"","sources":["../../src/events/base-nats-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAoB,MAAM,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAkC,mCAAmC,CAAC;AAG1F,8BAAsB,aAAa,CAAC,CAAC,SAAS,KAAK,CAAE,YAAW,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAIjG,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;gBAEF,MAAM,EAAE,kBAAkB;IAEvD;;;;;;;;OAQG;IACG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiB5G"}

package/build/events/base-nats-publisher.js

@@ -1,25 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsPublisher = void 0;
-const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const cascade_1 = require("./cascade");
 class NatsPublisher {
     constructor(client) {
         this.client = client;
     }
     /**
+     * Emit the event wrapped in the shared in-band envelope (id / subject / data /
+     * timestamp / cascade meta). The metadata rides in the payload so loop-guard and
+     * causation tracing stay transport agnostic.
      *
      * @param data
+     * @param meta
      * @param options
      */
-    async publish(data, options) {
+    async publish(data, meta, options) {
         try {
-            const message = {
-                id: (0, nx_frame_be_1.uuid)(),
-                subject: this.subject,
-                data,
-                timestamp: new Date().toISOString(),
-            };
-            await this.client.publish(this.subject, JSON.stringify(message), options);
+            const envelope = (0, cascade_1.buildEnvelope)(this.subject, data, meta);
+            await this.client.publish(this.subject, JSON.stringify(envelope), options);
         }
         catch (error) {
             console.error(`❌ Failed to publish to '${this.subject}':`, error);

package/build/events/base-nats-publisher.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-nats-publisher.js","sourceRoot":"","sources":["../../src/events/base-nats-publisher.ts"],"names":[],"mappings":";;;AAAA,sDAA6E;AAI7E,MAAsB,aAAa;IAIjC,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAE3D;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,IAAe,EAAE,OAA0C;QAExE,IAAI,CAAC;YAEF,MAAM,OAAO,GAAG;gBACd,EAAE,EAAO,IAAA,kBAAI,GAAE;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;YAEF,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CACvB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EACvB,OAAO,CACR,CAAC;QAEJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,OAAO,IAAI,EAAE,KAAK,CAAC,CAAC;YAClE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAjCD,sCAiCC"}
+{"version":3,"file":"base-nats-publisher.js","sourceRoot":"","sources":["../../src/events/base-nats-publisher.ts"],"names":[],"mappings":";;;AAGA,uCAAkE;AAElE,MAAsB,aAAa;IAIjC,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAE3D;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CAAC,IAAe,EAAE,IAAgB,EAAE,OAA0C;QAE1F,IAAI,CAAC;YAEF,MAAM,QAAQ,GAAG,IAAA,uBAAa,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAEzD,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CACvB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EACxB,OAAO,CACR,CAAC;QAEJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,2BAA2B,IAAI,CAAC,OAAO,IAAI,EAAE,KAAK,CAAC,CAAC;YAClE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAhCD,sCAgCC"}

package/build/events/base-publisher.d.ts

@@ -1,13 +1,17 @@
 import { Event, IPublisher, MsgClientInterface } from './interfaces';
+import { EventMeta } from './types/event-envelope.interfaces';
 export declare abstract class Publisher<T extends Event> implements IPublisher<T> {
     abstract subject: T['subject'];
     private readonly client;
     constructor(client: MsgClientInterface);
     /**
+     * Emit the event wrapped in the shared in-band envelope, so the msg bus carries
+     * the same cascade metadata as the NATS transport (transport-agnostic tracing).
      *
      * @param data
+     * @param meta
      * @returns
      */
-    publish(data: T['data']): Promise<void>;
+    publish(data: T['data'], meta?: EventMeta): Promise<void>;
 }
 //# sourceMappingURL=base-publisher.d.ts.map

package/build/events/base-publisher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-publisher.d.ts","sourceRoot":"","sources":["../../src/events/base-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAErE,8BAAsB,SAAS,CAAC,CAAC,SAAS,KAAK,CAAE,YAAW,UAAU,CAAC,CAAC,CAAC;IAEvE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,EAAE,kBAAkB;IAKtC;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAI9C"}
+{"version":3,"file":"base-publisher.d.ts","sourceRoot":"","sources":["../../src/events/base-publisher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAkC,mCAAmC,CAAC;AAG1F,8BAAsB,SAAS,CAAC,CAAC,SAAS,KAAK,CAAE,YAAW,UAAU,CAAC,CAAC,CAAC;IAEvE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;gBAEhC,MAAM,EAAE,kBAAkB;IAKtC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAKhE"}

package/build/events/base-publisher.js

@@ -1,17 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Publisher = void 0;
+const cascade_1 = require("./cascade");
 class Publisher {
     constructor(client) {
         this.client = client;
     }
     /**
+     * Emit the event wrapped in the shared in-band envelope, so the msg bus carries
+     * the same cascade metadata as the NATS transport (transport-agnostic tracing).
      *
      * @param data
+     * @param meta
      * @returns
      */
-    async publish(data) {
-        return await this.client.publish(this.subject, JSON.stringify(data));
+    async publish(data, meta) {
+        const envelope = (0, cascade_1.buildEnvelope)(this.subject, data, meta);
+        return await this.client.publish(this.subject, JSON.stringify(envelope));
     }
 }
 exports.Publisher = Publisher;

package/build/events/base-publisher.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-publisher.js","sourceRoot":"","sources":["../../src/events/base-publisher.ts"],"names":[],"mappings":";;;AAEA,MAAsB,SAAS;IAM7B,YAAY,MAA0B;QAEpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,IAAe;QAE3B,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE,CAAC;CACF;AApBD,8BAoBC"}
+{"version":3,"file":"base-publisher.js","sourceRoot":"","sources":["../../src/events/base-publisher.ts"],"names":[],"mappings":";;;AAEA,uCAAkE;AAElE,MAAsB,SAAS;IAM7B,YAAY,MAA0B;QAEpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,IAAe,EAAE,IAAgB;QAE7C,MAAM,QAAQ,GAAG,IAAA,uBAAa,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACzD,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC;CACF;AAxBD,8BAwBC"}

package/build/events/cascade.d.ts

@@ -0,0 +1,13 @@
+import { EventEnvelope, EventMeta, IncomingEventRef } from './types/event-envelope.interfaces';
+export declare function rootMeta(): EventMeta;
+export declare function nextMeta(incoming: IncomingEventRef): EventMeta;
+export declare function outgoingMeta(incoming?: IncomingEventRef): EventMeta;
+export declare function normalizeMeta(meta?: Partial<EventMeta>): EventMeta;
+export declare function unwrapEnvelope<T = any>(parsed: any): {
+    id: string;
+    data: T;
+    meta: EventMeta;
+};
+export declare function cascadeViolation(meta: EventMeta, subject: string): string | undefined;
+export declare function buildEnvelope<T>(subject: string, data: T, meta?: EventMeta): EventEnvelope<T>;
+//# sourceMappingURL=cascade.d.ts.map

package/build/events/cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/events/cascade.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAY/F,wBAAgB,QAAQ,IAAI,SAAS,CAGpC;AAKD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAQ9D;AAID,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAGnE;AAID,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,SAAS,CAWlE;AAQD,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAW7F;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASrF;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,CAS7F"}

package/build/events/cascade.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rootMeta = rootMeta;
+exports.nextMeta = nextMeta;
+exports.outgoingMeta = outgoingMeta;
+exports.normalizeMeta = normalizeMeta;
+exports.unwrapEnvelope = unwrapEnvelope;
+exports.cascadeViolation = cascadeViolation;
+exports.buildEnvelope = buildEnvelope;
+const nx_frame_be_1 = require("@nextage/nx-frame-be");
+const event_envelope_constants_1 = require("./types/event-envelope.constants");
+// ──────────────────────────────────────────────────────────────────────────────
+//  Cascade metadata helpers
+//
+//  Pure functions that derive and validate the tracing metadata carried by every
+//  event. They are transport agnostic (no NATS / msg types) so both listener
+//  families and `BaseEventCtrl` share exactly the same rules.
+// ──────────────────────────────────────────────────────────────────────────────
+// Metadata for a ROOT event (no parent in flight): a brand-new correlation.
+function rootMeta() {
+    return { correlationId: (0, nx_frame_be_1.uuid)(), depth: 0, visited: [] };
+}
+// Metadata for an event published WHILE processing `incoming`: same correlation,
+// caused by `incoming`, one hop deeper, with `incoming.subject` appended to the
+// visited lineage (so a later re-touch of that subject is detectable as a cycle).
+function nextMeta(incoming) {
+    return {
+        correlationId: incoming.meta.correlationId,
+        causationId: incoming.id,
+        depth: incoming.meta.depth + 1,
+        visited: [...incoming.meta.visited, incoming.subject],
+    };
+}
+// Outgoing metadata for a publish: `nextMeta` when a parent event is in flight
+// (cascade), otherwise a fresh `rootMeta` (root command).
+function outgoingMeta(incoming) {
+    return incoming ? nextMeta(incoming) : rootMeta();
+}
+// Normalize possibly-missing/partial metadata read off the wire into a full
+// `EventMeta` (legacy / bare payloads have none → treated as a fresh root).
+function normalizeMeta(meta) {
+    if (!meta || typeof meta.depth !== 'number' || !Array.isArray(meta.visited) || !meta.correlationId)
+        return rootMeta();
+    return {
+        correlationId: meta.correlationId,
+        causationId: meta.causationId,
+        depth: meta.depth,
+        visited: meta.visited,
+    };
+}
+// Unwrap a parsed payload into `{ id, data, meta }`, tolerating three shapes:
+//  - full envelope  { id, subject, data, timestamp, meta }  (current)
+//  - NATS envelope  { id, subject, data, timestamp }         (pre-meta)
+//  - bare data      the event data object itself             (legacy msg path)
+// The heuristic keys on `data` + (`meta` | `subject`); event data objects never
+// carry a `subject` field, so bare payloads are never mistaken for envelopes.
+function unwrapEnvelope(parsed) {
+    const isEnvelope = parsed
+        && typeof parsed === 'object'
+        && 'data' in parsed
+        && ('meta' in parsed || 'subject' in parsed);
+    if (isEnvelope)
+        return { id: parsed.id ?? (0, nx_frame_be_1.uuid)(), data: parsed.data, meta: normalizeMeta(parsed.meta) };
+    return { id: (0, nx_frame_be_1.uuid)(), data: parsed, meta: rootMeta() };
+}
+// Decide whether processing `subject` at this `meta` violates cascade governance.
+// Returns a human-readable reason (for the DLQ / logs) or `undefined` when safe:
+//  - depth ceiling reached → runaway loop
+//  - `subject` already visited in this lineage → cycle
+function cascadeViolation(meta, subject) {
+    if (meta.depth >= event_envelope_constants_1.MAX_CASCADE_DEPTH)
+        return `cascade depth ${meta.depth} >= ${event_envelope_constants_1.MAX_CASCADE_DEPTH} (runaway loop)`;
+    if (meta.visited.includes(subject))
+        return `cascade cycle: subject '${subject}' already visited [${meta.visited.join(' -> ')}]`;
+    return undefined;
+}
+// Build the envelope a publisher puts on the wire.
+function buildEnvelope(subject, data, meta) {
+    return {
+        id: (0, nx_frame_be_1.uuid)(),
+        subject,
+        data,
+        timestamp: new Date().toISOString(),
+        meta: meta ?? rootMeta(),
+    };
+}
+//# sourceMappingURL=cascade.js.map

package/build/events/cascade.js.map

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

package/build/events/index.d.ts

@@ -2,6 +2,8 @@ export * from './types/enums';
 export * from './interfaces';
 export * from './types';
 export * from './base-event.controller';
+export * from './cascade';
+export * from './outbox';
 export * from './msg-client-manager';
 export * from './msg-wrapper';
 export * from './base-listener';

package/build/events/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AAExB,cAAc,yBAAyB,CAAC;AAGxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AAGvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAGhC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AAExB,cAAc,yBAAyB,CAAC;AACxC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AAGzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AAGvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAGhC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AAGjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/build/events/index.js

@@ -18,6 +18,8 @@ __exportStar(require("./types/enums"), exports);
 __exportStar(require("./interfaces"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./base-event.controller"), exports);
+__exportStar(require("./cascade"), exports);
+__exportStar(require("./outbox"), exports);
 // messages on memory
 __exportStar(require("./msg-client-manager"), exports);
 __exportStar(require("./msg-wrapper"), exports);

package/build/events/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,+CAA6B;AAC7B,0CAAwB;AAExB,0DAAwC;AAExC,qBAAqB;AACrB,uDAAqC;AACrC,gDAA8B;AAC9B,kDAAgC;AAChC,mDAAiC;AAEjC,mBAAmB;AACnB,wDAAsC;AACtC,iDAA+B;AAC/B,uDAAqC;AACrC,wDAAsC;AAEtC,YAAY;AACZ,iDAA+B;AAC/B,yCAAuB;AAEvB,aAAa;AACb,kDAAgC;AAChC,gDAA8B;AAC9B,6CAA2B;AAC3B,mDAAiC;AACjC,iDAA+B;AAC/B,4CAA0B;AAC1B,sDAAoC;AACpC,2CAAyB;AACzB,kDAAgC;AAEhC,cAAc;AACd,4CAA0B;AAC1B,kDAAgC;AAChC,oDAAkC;AAClC,qDAAmC;AACnC,qDAAmC;AACnC,oDAAkC;AAClC,iDAA+B;AAC/B,mDAAiC;AAEjC,oBAAoB;AACpB,kDAAgC;AAChC,+CAA6B;AAE7B,kBAAkB;AAClB,mCAAmC;AAEnC,cAAc"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,+CAA6B;AAC7B,0CAAwB;AAExB,0DAAwC;AACxC,4CAA0B;AAC1B,2CAAyB;AAEzB,qBAAqB;AACrB,uDAAqC;AACrC,gDAA8B;AAC9B,kDAAgC;AAChC,mDAAiC;AAEjC,mBAAmB;AACnB,wDAAsC;AACtC,iDAA+B;AAC/B,uDAAqC;AACrC,wDAAsC;AAEtC,YAAY;AACZ,iDAA+B;AAC/B,yCAAuB;AAEvB,aAAa;AACb,kDAAgC;AAChC,gDAA8B;AAC9B,6CAA2B;AAC3B,mDAAiC;AACjC,iDAA+B;AAC/B,4CAA0B;AAC1B,sDAAoC;AACpC,2CAAyB;AACzB,kDAAgC;AAEhC,cAAc;AACd,4CAA0B;AAC1B,kDAAgC;AAChC,oDAAkC;AAClC,qDAAmC;AACnC,qDAAmC;AACnC,oDAAkC;AAClC,iDAA+B;AAC/B,mDAAiC;AAEjC,oBAAoB;AACpB,kDAAgC;AAChC,+CAA6B;AAE7B,kBAAkB;AAClB,mCAAmC;AAEnC,cAAc"}

package/build/events/interfaces.d.ts

@@ -1,4 +1,5 @@
 import { Subjects } from './types/enums';
+import { EventMeta } from './types/event-envelope.interfaces';
 import { NxObject } from '@nextage/nx-frame-be';
 export interface MsgClientInterface {
     publish: (subject: string, payload: string, options?: NxObject) => Promise<any>;
@@ -15,6 +16,6 @@ export interface Event {
 }
 export interface IPublisher<T extends Event, O = undefined> {
     subject: T['subject'];
-    publish(data: T['data'], options?: O): Promise<void>;
+    publish(data: T['data'], meta?: EventMeta, options?: O): Promise<void>;
 }
 //# sourceMappingURL=interfaces.d.ts.map

package/build/events/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/events/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IACnF,SAAS,EAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IACrC,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAK,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,QAAQ,CAAC;IAClB,IAAI,EAAK,GAAG,CAAC;CACd;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,GAAG,SAAS;IACxD,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IACtB,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/events/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAO,eAAe,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAO,sBAAsB,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IACnF,SAAS,EAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IACrC,WAAW,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAK,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,QAAQ,CAAC;IAClB,IAAI,EAAK,GAAG,CAAC;CACd;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,GAAG,SAAS;IACxD,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IACtB,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE"}

package/build/events/outbox.d.ts

@@ -0,0 +1,12 @@
+import { OutboxPort } from './types/outbox.interfaces';
+/**
+ * Register the process-wide outbox implementation. Called once, at service
+ * bootstrap (app-layer phase), with the service's own `event` model.
+ */
+export declare const registerOutbox: (port: OutboxPort) => void;
+/**
+ * Current outbox implementation, or `undefined` when none was registered (the
+ * controller then publishes WITHOUT persisting an outbox row — graceful default).
+ */
+export declare const getOutbox: () => OutboxPort | undefined;
+//# sourceMappingURL=outbox.d.ts.map

package/build/events/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/events/outbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAIvD;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,UAAU,KAAG,IAA2B,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,SAAS,QAAO,UAAU,GAAG,SAAoB,CAAC"}

package/build/events/outbox.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOutbox = exports.registerOutbox = void 0;
+let _outbox;
+/**
+ * Register the process-wide outbox implementation. Called once, at service
+ * bootstrap (app-layer phase), with the service's own `event` model.
+ */
+const registerOutbox = (port) => { _outbox = port; };
+exports.registerOutbox = registerOutbox;
+/**
+ * Current outbox implementation, or `undefined` when none was registered (the
+ * controller then publishes WITHOUT persisting an outbox row — graceful default).
+ */
+const getOutbox = () => _outbox;
+exports.getOutbox = getOutbox;
+//# sourceMappingURL=outbox.js.map

package/build/events/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/events/outbox.ts"],"names":[],"mappings":";;;AAEA,IAAI,OAA+B,CAAC;AAEpC;;;GAGG;AACI,MAAM,cAAc,GAAG,CAAC,IAAgB,EAAQ,EAAE,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;AAAjE,QAAA,cAAc,kBAAmD;AAE9E;;;GAGG;AACI,MAAM,SAAS,GAAG,GAA2B,EAAE,CAAC,OAAO,CAAC;AAAlD,QAAA,SAAS,aAAyC"}

package/build/events/types/event-envelope.constants.d.ts

@@ -0,0 +1,2 @@
+export declare const MAX_CASCADE_DEPTH = 10;
+//# sourceMappingURL=event-envelope.constants.d.ts.map

package/build/events/types/event-envelope.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.constants.d.ts","sourceRoot":"","sources":["../../../src/events/types/event-envelope.constants.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,iBAAiB,KAAK,CAAC"}

package/build/events/types/event-envelope.constants.js

@@ -0,0 +1,11 @@
+"use strict";
+// ──────────────────────────────────────────────────────────────────────────────
+//  Cascade governance constants
+// ──────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CASCADE_DEPTH = void 0;
+// Maximum number of cascade hops before an event is treated as a runaway loop and
+// dead-lettered instead of processed. The real cascades are depth <= 2; this is a
+// wide anti-runaway ceiling, not a tuning knob.
+exports.MAX_CASCADE_DEPTH = 10;
+//# sourceMappingURL=event-envelope.constants.js.map

package/build/events/types/event-envelope.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.constants.js","sourceRoot":"","sources":["../../../src/events/types/event-envelope.constants.ts"],"names":[],"mappings":";AAAA,iFAAiF;AACjF,gCAAgC;AAChC,iFAAiF;;;AAEjF,kFAAkF;AAClF,kFAAkF;AAClF,gDAAgD;AACnC,QAAA,iBAAiB,GAAG,EAAE,CAAC"}

package/build/events/types/event-envelope.interfaces.d.ts

@@ -0,0 +1,23 @@
+import { NxContext } from '@nextage/nx-frame-be';
+export interface EventMeta {
+    correlationId: string;
+    causationId?: string;
+    depth: number;
+    visited: string[];
+}
+export interface EventEnvelope<T = any> {
+    id: string;
+    subject: string;
+    data: T;
+    timestamp: string;
+    meta: EventMeta;
+}
+export interface IncomingEventRef {
+    id: string;
+    subject: string;
+    meta: EventMeta;
+}
+export interface EventContext extends NxContext {
+    _event?: IncomingEventRef;
+}
+//# sourceMappingURL=event-envelope.interfaces.d.ts.map

package/build/events/types/event-envelope.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.interfaces.d.ts","sourceRoot":"","sources":["../../../src/events/types/event-envelope.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAiBjD,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAG,MAAM,CAAC;IACtB,KAAK,EAAU,MAAM,CAAC;IACtB,OAAO,EAAQ,MAAM,EAAE,CAAC;CACzB;AAGD,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IACpC,EAAE,EAAS,MAAM,CAAC;IAClB,OAAO,EAAI,MAAM,CAAC;IAClB,IAAI,EAAO,CAAC,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAO,SAAS,CAAC;CACtB;AAKD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAO,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAK,SAAS,CAAC;CACpB;AAGD,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B"}

package/build/events/types/event-envelope.interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=event-envelope.interfaces.js.map

package/build/events/types/event-envelope.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-envelope.interfaces.js","sourceRoot":"","sources":["../../../src/events/types/event-envelope.interfaces.ts"],"names":[],"mappings":""}

package/build/events/types/index.d.ts

@@ -14,10 +14,13 @@ export * from './treatment.enums';
 export * from './vulnerability.enums';
 export * from './asset.constants';
 export * from './dlq.constants';
+export * from './event-envelope.constants';
 export * from './asset.interfaces';
 export * from './control.interfaces';
 export * from './dlq.interfaces';
+export * from './event-envelope.interfaces';
 export * from './events.interfaces';
+export * from './outbox.interfaces';
 export * from './risk-analysis.interfaces';
 export * from './threat.interfaces';
 export * from './vulnerability.interfaces';

package/build/events/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/events/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AAExB,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/events/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AAExB,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAG3C,cAAc,kBAAkB,CAAC"}

package/build/events/types/index.js

@@ -30,10 +30,13 @@ __exportStar(require("./treatment.enums"), exports);
 __exportStar(require("./vulnerability.enums"), exports);
 __exportStar(require("./asset.constants"), exports);
 __exportStar(require("./dlq.constants"), exports);
+__exportStar(require("./event-envelope.constants"), exports);
 __exportStar(require("./asset.interfaces"), exports);
 __exportStar(require("./control.interfaces"), exports);
 __exportStar(require("./dlq.interfaces"), exports);
+__exportStar(require("./event-envelope.interfaces"), exports);
 __exportStar(require("./events.interfaces"), exports);
+__exportStar(require("./outbox.interfaces"), exports);
 __exportStar(require("./risk-analysis.interfaces"), exports);
 __exportStar(require("./threat.interfaces"), exports);
 __exportStar(require("./vulnerability.interfaces"), exports);

package/build/events/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/events/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AAExB,wDAAsC;AACtC,gDAA8B;AAC9B,sDAAoC;AACpC,wDAAsC;AACtC,uDAAqC;AACrC,kDAAgC;AAChC,4DAA0C;AAC1C,iDAA+B;AAC/B,uDAAqC;AACrC,wDAAsC;AACtC,iDAA+B;AAC/B,oDAAkC;AAClC,wDAAsC;AAEtC,oDAAkC;AAClC,kDAAgC;AAEhC,qDAAmC;AACnC,uDAAqC;AACrC,mDAAiC;AACjC,sDAAoC;AACpC,6DAA2C;AAC3C,sDAAoC;AACpC,6DAA2C;AAE3C,YAAY;AACZ,mDAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/events/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AAExB,wDAAsC;AACtC,gDAA8B;AAC9B,sDAAoC;AACpC,wDAAsC;AACtC,uDAAqC;AACrC,kDAAgC;AAChC,4DAA0C;AAC1C,iDAA+B;AAC/B,uDAAqC;AACrC,wDAAsC;AACtC,iDAA+B;AAC/B,oDAAkC;AAClC,wDAAsC;AAEtC,oDAAkC;AAClC,kDAAgC;AAChC,6DAA2C;AAE3C,qDAAmC;AACnC,uDAAqC;AACrC,mDAAiC;AACjC,8DAA4C;AAC5C,sDAAoC;AACpC,sDAAoC;AACpC,6DAA2C;AAC3C,sDAAoC;AACpC,6DAA2C;AAE3C,YAAY;AACZ,mDAAiC"}

package/build/events/types/outbox.interfaces.d.ts

@@ -0,0 +1,12 @@
+import { NxContext } from '@nextage/nx-frame-be';
+import { QueueEventType } from './enums';
+export interface OutboxEvent {
+    id: string;
+    type: QueueEventType;
+    data: any;
+}
+export interface OutboxPort {
+    create(evt: OutboxEvent, context: NxContext): Promise<void>;
+    markSent(id: string, context: NxContext): Promise<void>;
+}
+//# sourceMappingURL=outbox.interfaces.d.ts.map

package/build/events/types/outbox.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.interfaces.d.ts","sourceRoot":"","sources":["../../../src/events/types/outbox.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAW,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKzC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAI,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,GAAG,CAAC;CACX;AASD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,GAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAQ,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D"}

package/build/events/types/outbox.interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=outbox.interfaces.js.map

package/build/events/types/outbox.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.interfaces.js","sourceRoot":"","sources":["../../../src/events/types/outbox.interfaces.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextage/era-lib",
-  "version": "1.0.174",
+  "version": "1.0.176",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "files": [
@@ -22,7 +22,7 @@
   "license": "ISC",
   "description": "ERA shared backend library (@nextage/era-lib): events, models, services, bootstrap orchestrator and utils on top of @nextage/nx-frame-be. See README.md and CHANGELOG.md.",
   "dependencies": {
-    "@nextage/nx-frame-be": "^1.0.40",
+    "@nextage/nx-frame-be": "^1.0.41",
     "@types/express-jwt": "^7.4.2",
     "@types/express-rate-limit": "^6.0.0",
     "@types/express-session": "^1.18.2",