@pristine-ts/common 2.0.2 → 2.0.4

package/dist/lib/cjs/common.module.js

@@ -20,6 +20,7 @@ __exportStar(require("./contexts/contexts"), exports);
 __exportStar(require("./decorators/decorators"), exports);
 __exportStar(require("./enums/enums"), exports);
 __exportStar(require("./errors/errors"), exports);
+__exportStar(require("./managers/managers"), exports);
 __exportStar(require("./models/models"), exports);
 __exportStar(require("./interfaces/interfaces"), exports);
 __exportStar(require("./types/types"), exports);

package/dist/lib/cjs/common.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.module.js","sourceRoot":"","sources":["../../../src/common.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mEAA4D;AAG5D,sDAAoC;AACpC,0DAAwC;AACxC,gDAA8B;AAC9B,kDAAgC;AAChC,kDAAgC;AAChC,0DAAwC;AACxC,gDAA8B;AAC9B,gDAA8B;AAC9B,0DAAwC;AAE3B,QAAA,YAAY,GAAoB;IAC3C,OAAO,EAAE,2CAAmB;IAC5B,aAAa,EAAE,EAAE;IACjB,qBAAqB,EAAE,EAAE;CAC1B,CAAA"}
+{"version":3,"file":"common.module.js","sourceRoot":"","sources":["../../../src/common.module.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mEAA4D;AAG5D,sDAAoC;AACpC,0DAAwC;AACxC,gDAA8B;AAC9B,kDAAgC;AAChC,sDAAoC;AACpC,kDAAgC;AAChC,0DAAwC;AACxC,gDAA8B;AAC9B,gDAA8B;AAC9B,0DAAwC;AAE3B,QAAA,YAAY,GAAoB;IAC3C,OAAO,EAAE,2CAAmB;IAC5B,aAAa,EAAE,EAAE;IACjB,qBAAqB,EAAE,EAAE;CAC1B,CAAA"}

package/dist/lib/cjs/contexts/contexts.js

@@ -14,5 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./event-context"), exports);
 __exportStar(require("./tracing.context"), exports);
 //# sourceMappingURL=contexts.js.map

package/dist/lib/cjs/contexts/contexts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../../src/contexts/contexts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}
+{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../../src/contexts/contexts.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,oDAAkC"}

package/dist/lib/cjs/contexts/event-context.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventContext = void 0;
+/**
+ * Per-event runtime state — the framework's correlation primitives plus a handle to
+ * the per-event DI child container and the active trace. Propagated implicitly via
+ * `AsyncLocalStorage` (managed by `EventContextManager`) so downstream code doesn't
+ * have to thread these fields through every method signature.
+ *
+ * **Not to be confused with `ExecutionContextInterface` (in `@pristine-ts/core`):**
+ *   - `ExecutionContext` describes *where* the framework is running (AWS Lambda, CLI,
+ *     Express, etc.) — set once per `kernel.handle()` call, immutable, host-shaped.
+ *   - `EventContext` describes *which specific event* is being handled — set per event
+ *     in the pipeline, mutable (`traceId` / `trace` fill in once tracing starts),
+ *     correlation-shaped.
+ *
+ * One `kernel.handle()` call can produce multiple events (each event mapper can return
+ * a list); each event gets its own `EventContext` instance.
+ */
+class EventContext {
+}
+exports.EventContext = EventContext;
+//# sourceMappingURL=event-context.js.map

package/dist/lib/cjs/contexts/event-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../../../src/contexts/event-context.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;CAmBxB;AAnBD,oCAmBC"}

package/dist/lib/cjs/contexts/tracing.context.js

@@ -9,6 +9,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TracingContext = void 0;
 require("reflect-metadata");
 const tsyringe_1 = require("tsyringe");
+/**
+ * @deprecated Read the trace id from the active `EventContext` instead:
+ *
+ * ```ts
+ * import {EventContextManager} from "@pristine-ts/common";
+ *
+ * const traceId = EventContextManager.traceId();
+ * ```
+ *
+ * `TracingContext` predates the `AsyncLocalStorage`-backed `EventContext` and survives
+ * only as a back-compat shim. `TracingManager.startTracing()` still mirrors the trace id
+ * into this class so existing consumers keep working, but new code should read from
+ * `EventContextManager`. This class will be removed in a future major.
+ */
 let TracingContext = class TracingContext {
 };
 exports.TracingContext = TracingContext;

package/dist/lib/cjs/contexts/tracing.context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;;;;AAAA,4BAA0B;AAC1B,uCAAuD;AAIhD,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,qBAAU,GAAE;IACZ,IAAA,iBAAM,EAAC,oBAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}
+{"version":3,"file":"tracing.context.js","sourceRoot":"","sources":["../../../../src/contexts/tracing.context.ts"],"names":[],"mappings":";;;;;;;;;AAAA,4BAA0B;AAC1B,uCAAuD;AAEvD;;;;;;;;;;;;;GAaG;AAGI,IAAM,cAAc,GAApB,MAAM,cAAc;CAE1B,CAAA;AAFY,wCAAc;yBAAd,cAAc;IAF1B,IAAA,qBAAU,GAAE;IACZ,IAAA,iBAAM,EAAC,oBAAS,CAAC,eAAe,CAAC;GACrB,cAAc,CAE1B"}

package/dist/lib/cjs/decorators/decorators.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./inject-config.decorator"), exports);
 __exportStar(require("./module-scoped.decorator"), exports);
 __exportStar(require("./tag.decorator"), exports);
+__exportStar(require("./traced.decorator"), exports);
 //# sourceMappingURL=decorators.js.map

package/dist/lib/cjs/decorators/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,4DAA0C;AAC1C,kDAAgC"}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,4DAA0C;AAC1C,kDAAgC;AAChC,qDAAmC"}

package/dist/lib/cjs/decorators/traced.decorator.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traced = traced;
+const span_runner_1 = require("../utils/span-runner");
+/**
+ * Method decorator that wraps the decorated method in a span. The span is automatically
+ * ended when the method returns or throws, and the `TracingManager` is auto-resolved
+ * from the active `EventContext` — no need to inject it manually.
+ *
+ * ```ts
+ * class PaymentService {
+ *   @traced()                                // span name = "PaymentService.charge"
+ *   async charge(amount: number) { ... }
+ *
+ *   @traced("payment.refund.action")         // explicit name
+ *   async refund(chargeId: string) { ... }
+ * }
+ * ```
+ *
+ * **Behavior outside an event context.** When the decorated method runs without an
+ * active `EventContext` (e.g. a unit test calling the method directly, or background
+ * work that escaped the event lifecycle), the decorator is a no-op — the original
+ * method runs unchanged. Tracing must never throw or alter semantics.
+ *
+ * **Sync methods become async.** The decorator awaits the wrapped method internally,
+ * so any decorated method returns a `Promise`. Decorating a sync method changes its
+ * signature visible to callers — apply `@traced` to methods you'd already be awaiting
+ * (DB calls, HTTP, expensive computations), not to tight sync helpers.
+ *
+ * **Type-level caveat.** TypeScript's parameter and method decorator types don't carry
+ * enough information for the compiler to verify that the wrapped method's return type
+ * is compatible with `Promise<T>`. The wrapper is type-safe at runtime; the call site's
+ * static types are unchanged. Pair with explicit `: Promise<T>` annotations on the
+ * method when you want the static type to match what's actually returned.
+ *
+ * **Lives in `@pristine-ts/common`** so any package can use it without taking a direct
+ * dep on `@pristine-ts/telemetry`. The actual `TracingManager` implementation still
+ * lives in telemetry; this decorator only reads the active manager from the
+ * EventContext when one is present.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+function traced(spanName) {
+    return (target, propertyKey, descriptor) => {
+        var _a, _b, _c;
+        const original = descriptor.value;
+        if (typeof original !== "function") {
+            // Decorator was applied to something other than a method (a getter, a property
+            // with no initial value, etc.). Leave it alone — silently no-op rather than
+            // throw at decoration time.
+            return descriptor;
+        }
+        // Resolve a stable default name at decoration time. `target.constructor.name` is
+        // the class name for instance methods; for static methods, `target.name` is the
+        // class. We cover both via the fallback chain.
+        const className = (_c = (_b = (_a = target === null || target === void 0 ? void 0 : target.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : target === null || target === void 0 ? void 0 : target.name) !== null && _c !== void 0 ? _c : "anonymous";
+        const resolvedName = spanName !== null && spanName !== void 0 ? spanName : `${className}.${String(propertyKey)}`;
+        descriptor.value = function (...args) {
+            return span_runner_1.spanRunner.runWithSpan(resolvedName, () => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=traced.decorator.js.map

package/dist/lib/cjs/decorators/traced.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced.decorator.js","sourceRoot":"","sources":["../../../../src/decorators/traced.decorator.ts"],"names":[],"mappings":";;AAyCA,wBAsBC;AA/DD,sDAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,MAAM,CAAC,QAAiB;IACtC,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;;QACnF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,+EAA+E;YAC/E,4EAA4E;YAC5E,4BAA4B;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,iFAAiF;QACjF,gFAAgF;QAChF,+CAA+C;QAC/C,MAAM,SAAS,GAAW,MAAA,MAAA,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,0CAAE,IAAI,mCAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,WAAW,CAAC;QACnF,MAAM,YAAY,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,GAAG,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEvE,UAAU,CAAC,KAAK,GAAG,UAAyB,GAAG,IAAW;YACxD,OAAO,wBAAU,CAAC,WAAW,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAChF,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/cjs/enums/enums.js

@@ -18,4 +18,5 @@ __exportStar(require("./http-method.enum"), exports);
 __exportStar(require("./internal-container-parameter.enum"), exports);
 __exportStar(require("./metadata.enum"), exports);
 __exportStar(require("./service-definition-tag.enum"), exports);
+__exportStar(require("./span-keyname.enum"), exports);
 //# sourceMappingURL=enums.js.map

package/dist/lib/cjs/enums/enums.js.map

@@ -1 +1 @@
-{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,sEAAoD;AACpD,kDAAgC;AAChC,gEAA8C"}
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,sEAAoD;AACpD,kDAAgC;AAChC,gEAA8C;AAC9C,sDAAoC"}

package/dist/lib/cjs/enums/span-keyname.enum.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanKeynameEnum = void 0;
+/**
+ * This enum is for the different span names that are integrated in Pristine.
+ */
+var SpanKeynameEnum;
+(function (SpanKeynameEnum) {
+    SpanKeynameEnum["ChildContainerCreation"] = "child.container.creation";
+    SpanKeynameEnum["ChildContainerRegistration"] = "child.container.registration";
+    SpanKeynameEnum["ConfigurationInitialization"] = "configuration.initialization";
+    SpanKeynameEnum["ErrorResponseInterceptors"] = "error.response.interceptors";
+    SpanKeynameEnum["EventDispatcherResolver"] = "event.dispatcher.resolver";
+    SpanKeynameEnum["EventExecution"] = "event.execution";
+    SpanKeynameEnum["EventInitialization"] = "event.initialization";
+    SpanKeynameEnum["EventPreMappingInterception"] = "event.pre-mapping.interception";
+    SpanKeynameEnum["EventPostMappingInterception"] = "event.post-mapping.interception";
+    SpanKeynameEnum["EventPreResponseMappingInterception"] = "event.pre-response-mapping.interception";
+    SpanKeynameEnum["EventPostResponseMappingInterception"] = "event.post-response-mapping.interception";
+    SpanKeynameEnum["EventMapping"] = "event.mapping";
+    SpanKeynameEnum["KernelInitialization"] = "kernel.initialization";
+    SpanKeynameEnum["ModuleInitialization"] = "module.initialization";
+    SpanKeynameEnum["ModuleInitializationImportModules"] = "module.initialization.import.modules";
+    SpanKeynameEnum["RequestExecution"] = "request.execution";
+    SpanKeynameEnum["RequestInterceptors"] = "request.interceptors";
+    SpanKeynameEnum["ResponseInterceptors"] = "response.interceptors";
+    SpanKeynameEnum["RootExecution"] = "root.execution";
+    SpanKeynameEnum["RouterControllerResolver"] = "router.controller.resolver";
+    SpanKeynameEnum["RouterFindMethodRouterNode"] = "router.find.method.router.node";
+    SpanKeynameEnum["RouterRequestAuthentication"] = "router.request.authentication";
+    SpanKeynameEnum["RouterRequestExecution"] = "router.request.execution";
+    SpanKeynameEnum["RouterSetup"] = "router.setup";
+})(SpanKeynameEnum || (exports.SpanKeynameEnum = SpanKeynameEnum = {}));
+//# sourceMappingURL=span-keyname.enum.js.map

package/dist/lib/cjs/enums/span-keyname.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-keyname.enum.js","sourceRoot":"","sources":["../../../../src/enums/span-keyname.enum.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,IAAY,eAyBX;AAzBD,WAAY,eAAe;IACzB,sEAAmD,CAAA;IACnD,8EAA2D,CAAA;IAC3D,+EAA4D,CAAA;IAC5D,4EAAyD,CAAA;IACzD,wEAAqD,CAAA;IACrD,qDAAkC,CAAA;IAClC,+DAA4C,CAAA;IAC5C,iFAA8D,CAAA;IAC9D,mFAAgE,CAAA;IAChE,kGAA+E,CAAA;IAC/E,oGAAiF,CAAA;IACjF,iDAA8B,CAAA;IAC9B,iEAA8C,CAAA;IAC9C,iEAA8C,CAAA;IAC9C,6FAA0E,CAAA;IAC1E,yDAAsC,CAAA;IACtC,+DAA4C,CAAA;IAC5C,iEAA8C,CAAA;IAC9C,mDAAgC,CAAA;IAChC,0EAAuD,CAAA;IACvD,gFAA6D,CAAA;IAC7D,gFAA6D,CAAA;IAC7D,sEAAmD,CAAA;IACnD,+CAA4B,CAAA;AAC9B,CAAC,EAzBW,eAAe,+BAAf,eAAe,QAyB1B"}

package/dist/lib/cjs/interfaces/interfaces.js

@@ -25,5 +25,6 @@ __exportStar(require("./module-scoped-registration.interface"), exports);
 __exportStar(require("./resolver.interface"), exports);
 __exportStar(require("./tagged-registration.interface"), exports);
 __exportStar(require("./token-provider-registration.interface"), exports);
+__exportStar(require("./tracing-manager.interface"), exports);
 __exportStar(require("./value-provider-registration.interface"), exports);
 //# sourceMappingURL=interfaces.js.map

package/dist/lib/cjs/interfaces/interfaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../../src/interfaces/interfaces.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,0EAAwD;AACxD,4DAA0C;AAC1C,6EAA2D;AAC3D,4EAA0D;AAC1D,uDAAqC;AACrC,qDAAmC;AACnC,yEAAuD;AACvD,uDAAqC;AACrC,kEAAgD;AAChD,0EAAwD;AACxD,0EAAwD"}
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../../src/interfaces/interfaces.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,0EAAwD;AACxD,4DAA0C;AAC1C,6EAA2D;AAC3D,4EAA0D;AAC1D,uDAAqC;AACrC,qDAAmC;AACnC,yEAAuD;AACvD,uDAAqC;AACrC,kEAAgD;AAChD,0EAAwD;AACxD,8DAA4C;AAC5C,0EAAwD"}

package/dist/lib/cjs/interfaces/tracing-manager.interface.js

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

package/dist/lib/cjs/interfaces/tracing-manager.interface.js.map

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

package/dist/lib/cjs/managers/event-context.manager.js

@@ -0,0 +1,107 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var EventContextManager_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventContextManager = void 0;
+const async_hooks_1 = require("async_hooks");
+const tsyringe_1 = require("tsyringe");
+/**
+ * Owns the `AsyncLocalStorage` instance that propagates the active `EventContext`
+ * across `await` boundaries, `Promise.all`, `setImmediate`, and the rest of Node's
+ * async machinery. Provides:
+ *
+ *   - `run(ctx, fn)` — install the context for the duration of `fn`. **Framework-only**;
+ *     normal application code never calls this. Pristine's event pipeline calls it once
+ *     per event.
+ *   - Read accessors — `current()`, `eventId()`, `traceId()`, `container()`. Available
+ *     as instance methods (DI-resolved) and as static convenience methods.
+ *   - `bind(fn)` — escape hatch for background work that breaks the natural async
+ *     chain (raw `setImmediate`, `EventEmitter`-based code, certain native modules).
+ *     Captures the current context and returns a wrapped function that restores it
+ *     on call.
+ *
+ * Why static state inside an `@injectable()` class: the `AsyncLocalStorage` instance
+ * itself must be a single process-wide singleton — multiple instances would each track
+ * their own propagation chain and contexts wouldn't be visible across them. Making the
+ * ALS `private static readonly` while keeping the class `@injectable()` lets DI consumers
+ * resolve it normally (and substitute fakes in tests) while the underlying state stays
+ * shared and consistent.
+ */
+let EventContextManager = EventContextManager_1 = class EventContextManager {
+    run(ctx, fn) {
+        return EventContextManager_1.als.run(ctx, fn);
+    }
+    /** Returns the active `EventContext`, or `undefined` if no context is installed
+     *  (i.e. we're outside any `run()` call). */
+    current() {
+        return EventContextManager_1.als.getStore();
+    }
+    /** Convenience: the `eventId` of the active context, or `undefined`. */
+    eventId() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.eventId;
+    }
+    /** Convenience: the `traceId` of the active context, or `undefined`. */
+    traceId() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.traceId;
+    }
+    /** Convenience: the per-event DI child container, or `undefined`. */
+    container() {
+        var _a;
+        return (_a = this.current()) === null || _a === void 0 ? void 0 : _a.container;
+    }
+    /**
+     * Returns a wrapped version of `fn` that restores the current context on call. Use
+     * when you need to spawn work that escapes the natural async chain (e.g. a callback
+     * registered with a third-party `EventEmitter`, or a `setImmediate` whose callback
+     * runs after the parent function returned). Without `bind`, that work would see no
+     * context.
+     *
+     * If no context is active when `bind` is called, returns `fn` unchanged.
+     */
+    bind(fn) {
+        const ctx = this.current();
+        if (ctx === undefined)
+            return fn;
+        const als = EventContextManager_1.als;
+        return ((...args) => als.run(ctx, () => fn(...args)));
+    }
+    // ── Static convenience mirrors. ────────────────────────────────────────────────
+    // For callers that don't want DI noise (e.g. utility code, decorators, helpers
+    // that don't have a constructor to inject through). All forwarding to the same
+    // shared ALS instance.
+    static current() {
+        return EventContextManager_1.als.getStore();
+    }
+    static eventId() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.eventId;
+    }
+    static traceId() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.traceId;
+    }
+    static container() {
+        var _a;
+        return (_a = EventContextManager_1.current()) === null || _a === void 0 ? void 0 : _a.container;
+    }
+    static bind(fn) {
+        const ctx = EventContextManager_1.current();
+        if (ctx === undefined)
+            return fn;
+        const als = EventContextManager_1.als;
+        return ((...args) => als.run(ctx, () => fn(...args)));
+    }
+};
+exports.EventContextManager = EventContextManager;
+EventContextManager.als = new async_hooks_1.AsyncLocalStorage();
+exports.EventContextManager = EventContextManager = EventContextManager_1 = __decorate([
+    (0, tsyringe_1.injectable)()
+], EventContextManager);
+//# sourceMappingURL=event-context.manager.js.map

package/dist/lib/cjs/managers/event-context.manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-context.manager.js","sourceRoot":"","sources":["../../../../src/managers/event-context.manager.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,6CAA8C;AAC9C,uCAAyD;AAGzD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEI,IAAM,mBAAmB,2BAAzB,MAAM,mBAAmB;IAU9B,GAAG,CAAI,GAAiB,EAAE,EAAwB;QAChD,OAAO,qBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;iDAC6C;IAC7C,OAAO;QACL,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,OAAO;;QACL,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IACjC,CAAC;IAED,qEAAqE;IACrE,SAAS;;QACP,OAAO,MAAA,IAAI,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAoC,EAAK;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;IAED,kFAAkF;IAClF,+EAA+E;IAC/E,+EAA+E;IAC/E,uBAAuB;IAEvB,MAAM,CAAC,OAAO;QACZ,OAAO,qBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,OAAO;;QACZ,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,OAAO,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,SAAS;;QACd,OAAO,MAAA,qBAAmB,CAAC,OAAO,EAAE,0CAAE,SAAS,CAAC;IAClD,CAAC;IAED,MAAM,CAAC,IAAI,CAAoC,EAAK;QAClD,MAAM,GAAG,GAAG,qBAAmB,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,qBAAmB,CAAC,GAAG,CAAC;QACpC,OAAO,CAAC,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAM,CAAC;IACpE,CAAC;;AA7EU,kDAAmB;AACN,uBAAG,GAAG,IAAI,+BAAiB,EAAgB,AAAxC,CAAyC;8BADzD,mBAAmB;IAD/B,IAAA,qBAAU,GAAE;GACA,mBAAmB,CA8E/B"}

package/dist/lib/cjs/managers/managers.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./event-context.manager"), exports);
+//# sourceMappingURL=managers.js.map

package/dist/lib/cjs/managers/managers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managers.js","sourceRoot":"","sources":["../../../../src/managers/managers.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0DAAwC"}

package/dist/lib/cjs/models/models.js

@@ -16,4 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./request"), exports);
 __exportStar(require("./response"), exports);
+__exportStar(require("./span-event.model"), exports);
+__exportStar(require("./span.model"), exports);
+__exportStar(require("./trace.model"), exports);
 //# sourceMappingURL=models.js.map

package/dist/lib/cjs/models/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,6CAA2B"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../../../src/models/models.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4CAA0B;AAC1B,6CAA2B;AAC3B,qDAAmC;AACnC,+CAA6B;AAC7B,gDAA8B"}

package/dist/lib/cjs/models/span-event.model.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanEvent = void 0;
+/**
+ * A named, timestamped marker attached to a `Span`. Represents a noteworthy moment
+ * inside the span's lifetime that doesn't warrant a child span of its own — e.g.
+ * "validation passed", "rate limit check ok", "found 50 rows in DB".
+ *
+ * Modeled after OpenTelemetry's "span events" concept: a `Span` carries `events: SpanEvent[]`
+ * alongside its `children: Span[]`. Renderers (the console/file tracer output, etc.) interleave
+ * events with spans by timestamp to produce a chronological trail of what happened during the span.
+ *
+ * Use `TracingManager.addEventToCurrentSpan(message, attributes?)` to add one — it finds
+ * the most-recently-started in-progress span and attaches the event there.
+ */
+class SpanEvent {
+    constructor(message, attributes) {
+        this.message = message;
+        /**
+         * The timestamp in milliseconds at which the event was created. Used to interleave
+         * events with sibling spans when rendering a sorted trail.
+         */
+        this.timestamp = Date.now();
+        this.attributes = attributes;
+    }
+}
+exports.SpanEvent = SpanEvent;
+//# sourceMappingURL=span-event.model.js.map

package/dist/lib/cjs/models/span-event.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-event.model.js","sourceRoot":"","sources":["../../../../src/models/span-event.model.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;GAWG;AACH,MAAa,SAAS;IAapB,YAA4B,OAAe,EAAE,UAAsC;QAAvD,YAAO,GAAP,OAAO,CAAQ;QAZ3C;;;WAGG;QACa,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAS7C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAhBD,8BAgBC"}

package/dist/lib/cjs/models/span.model.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Span = void 0;
+const crypto_1 = require("crypto");
+/**
+ * This model represents a span.
+ */
+class Span {
+    /**
+     * This model represents a span.
+     * @param keyname The keyname of the span.
+     * @param id The unique id of the span.
+     * @param context The context to associate with the span.
+     */
+    constructor(keyname, id, context) {
+        this.keyname = keyname;
+        /**
+         * The timestamp in milliseconds at which the span was started.
+         */
+        this.startDate = Date.now();
+        /**
+         * The children spans.
+         */
+        this.children = [];
+        /**
+         * Named, timestamped markers attached to this span. Use these for noteworthy moments
+         * inside the span's lifetime that don't warrant their own child span — e.g.
+         * "validation passed", "found 50 rows in DB". Empty by default; populated by
+         * `TracingManager.addEventToCurrentSpan(...)`.
+         */
+        this.events = [];
+        /**
+         * The context associated with the span.
+         */
+        this.context = {};
+        /**
+         * Whether or not the span is in progress, meaning it has not ended.
+         */
+        this.inProgress = true;
+        this.id = id !== null && id !== void 0 ? id : (0, crypto_1.randomUUID)();
+        this.context = context !== null && context !== void 0 ? context : {};
+    }
+    /**
+     * This method returns the duration of the span in milliseconds.
+     */
+    getDuration() {
+        var _a;
+        return ((_a = this.endDate) !== null && _a !== void 0 ? _a : Date.now()) - this.startDate;
+    }
+    /**
+     * This method ends the span.
+     */
+    end() {
+        var _a;
+        (_a = this.tracingManager) === null || _a === void 0 ? void 0 : _a.endSpan(this);
+    }
+    /**
+     * This method sets the trace for the span and all of its children.
+     * @param trace The trace the span should be attached to.
+     */
+    setTrace(trace) {
+        this.trace = trace;
+        this.children.forEach(childSpan => childSpan.setTrace(trace));
+    }
+    /**
+     * This method adds a child span to the current span. It only adds it if it's not already part of the children.
+     * @param span The span to add as a child.
+     */
+    addChild(span) {
+        const existingChildSpan = this.children.find(childSpan => childSpan.id === span.id);
+        if (existingChildSpan) {
+            return;
+        }
+        span.parentSpan = this;
+        this.children.push(span);
+    }
+}
+exports.Span = Span;
+//# sourceMappingURL=span.model.js.map

package/dist/lib/cjs/models/span.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.model.js","sourceRoot":"","sources":["../../../../src/models/span.model.ts"],"names":[],"mappings":";;;AAAA,mCAAkC;AAclC;;GAEG;AACH,MAAa,IAAI;IAuDf;;;;;OAKG;IACH,YAA0B,OAAe,EAAE,EAAW,EAAE,OAAmC;QAAjE,YAAO,GAAP,OAAO,CAAQ;QA5CzC;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;WAEG;QACI,aAAQ,GAAW,EAAE,CAAC;QAE7B;;;;;WAKG;QACI,WAAM,GAAgB,EAAE,CAAC;QAEhC;;WAEG;QACI,YAAO,GAA8B,EAAE,CAAC;QAE/C;;WAEG;QACI,eAAU,GAAG,IAAI,CAAC;QASvB,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,IAAA,mBAAU,GAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;IAED;;OAEG;IACI,GAAG;;QACR,MAAA,IAAI,CAAC,cAAc,0CAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,KAAY;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAEnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACI,QAAQ,CAAC,IAAU;QACxB,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QAEpF,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;CACF;AAxGD,oBAwGC"}

package/dist/lib/cjs/models/trace.model.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Trace = void 0;
+const crypto_1 = require("crypto");
+/**
+ * This model represents a trace.
+ */
+class Trace {
+    /**
+     * This model represents a trace.
+     * @param id The unique id of the trace.
+     * @param context The context associated with the trace.
+     */
+    constructor(id, context) {
+        /**
+         * The timestamp in milliseconds at which the trace was started.
+         */
+        this.startDate = Date.now();
+        /**
+         * Index of all spans in this trace by keyname, populated by `TracingManager.addSpan`.
+         * Lives on the Trace (not on a particular TracingManager instance) so any TracingManager
+         * reading the active trace through `EventContext.trace` sees the same index — required
+         * for cross-container span lookup (kernel-resolved manager vs per-event resolved manager).
+         */
+        this.spansByKeyname = {};
+        /**
+         * The context associated with the trace.
+         */
+        this.context = {};
+        /**
+         * Whether or not the trace was ended.
+         */
+        this.hasEnded = false;
+        this.id = id !== null && id !== void 0 ? id : (0, crypto_1.randomUUID)();
+        this.context = context !== null && context !== void 0 ? context : {};
+    }
+    /**
+     * This returns the duration of the trace in miliseconds.
+     */
+    getDuration() {
+        var _a;
+        return ((_a = this.endDate) !== null && _a !== void 0 ? _a : Date.now()) - this.startDate;
+    }
+}
+exports.Trace = Trace;
+//# sourceMappingURL=trace.model.js.map

package/dist/lib/cjs/models/trace.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.model.js","sourceRoot":"","sources":["../../../../src/models/trace.model.ts"],"names":[],"mappings":";;;AAAA,mCAAkC;AAGlC;;GAEG;AACH,MAAa,KAAK;IAuChB;;;;OAIG;IACH,YAAmB,EAAW,EAAE,OAAmC;QAtCnE;;WAEG;QACI,cAAS,GAAW,IAAI,CAAC,GAAG,EAAE,CAAC;QAYtC;;;;;WAKG;QACI,mBAAc,GAAkC,EAAE,CAAC;QAE1D;;WAEG;QACI,YAAO,GAA+B,EAAE,CAAC;QAEhD;;WAEG;QACI,aAAQ,GAAY,KAAK,CAAC;QAQ/B,IAAI,CAAC,EAAE,GAAG,EAAE,aAAF,EAAE,cAAF,EAAE,GAAI,IAAA,mBAAU,GAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,WAAW;;QAChB,OAAO,CAAC,MAAA,IAAI,CAAC,OAAO,mCAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;IACvD,CAAC;CACF;AAvDD,sBAuDC"}