@dudousxd/nestjs-diagnostics 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.3.0
+
+### Minor Changes
+
+- [#7](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/7) [`a78672e`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/a78672ef871610df13fb3cb875d15bc993c564ad) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - feat: ecosystem improvements across the diagnostics core and Telescope watcher.
+
+  - **Envelope schema version (`v`):** every emitted envelope now carries an explicit schema-version field (`v`) so recorders and watchers can evolve the payload shape over time and detect/route by version. The Telescope watcher reads `v` when recording entries.
+  - **Per-emit sampling hook:** emit accepts an optional per-emit sampling decision, letting callers cheaply drop a fraction of events at the emit site (before payload work is done) without disabling a channel wholesale.
+  - **`tracingChannel()` + `trace()` helper:** a span-like wrapper over `node:diagnostics_channel`'s tracing-channel semantics that pairs `start`/`end`/`asyncStart`/`asyncEnd`/`error` events for a single logical operation, so a synchronous block or a promise can be traced with correct begin/finish/error correlation. The `trace()` helper wraps a function (sync or async) and publishes the matched lifecycle events automatically, including the `error` channel on throw/reject.
+  - **Typed channel registry:** the channel registry is now generic over a compile-time payload-type map, so `channel(name)` and the corresponding publish/subscribe surfaces are typed to the registered payload for that channel name — catching mismatched payloads at compile time while staying erased at runtime.
+  - **Packaging hygiene:** the core package declares a conservative `sideEffects` allowlist (rather than `false`) that preserves the module-level `globalThis` / `Symbol.for` registry and context-accessor registration so a bundler can never tree-shake the cross-copy-stable global state away; pure modules remain tree-shakeable.
+
+  Also includes a `LICENSE` file at the repo root.
+
+### Patch Changes
+
+- [#7](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/7) [`a78672e`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/a78672ef871610df13fb3cb875d15bc993c564ad) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - chore: packaging hygiene — declare `sideEffects` for safe tree-shaking.
+
+  The core package now declares `sideEffects` as an explicit allowlist of the modules that register process-global state at import time (the cross-copy-stable channel registry and context accessor on `globalThis` via `Symbol.for`, plus the reset hooks): `registry`, `context-accessor`, `channel`, and `trace`. It is deliberately **not** `false`, so a bundler can never tree-shake those global registrations away and break cross-copy registry stability; pure modules stay tree-shakeable.
+
+  The telescope package declares `sideEffects: false` — it has no module-level side effects (the watcher subscribes to channels only at runtime, inside `register()`), so consumers get full tree-shaking.
+
+  No runtime behavior changes; the `exports`/`types` maps already resolve correctly under NodeNext.
+
 ## 0.2.3
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/channel.d.ts

@@ -1,7 +1,14 @@
 import { type Channel } from 'node:diagnostics_channel';
-import type { EmitOptions } from './types.js';
+import type { EmitOptions, EventOf, LibOf, PayloadOf } from './types.js';
 /** The prefix all channels created by this convention share. */
 export declare const CHANNEL_PREFIX = "aviary";
+/**
+ * Current envelope schema version, stamped onto every emitted
+ * {@link DiagnosticEvent} as `v`. Bump this only when the wire shape changes in a
+ * way observers must adapt to. Observers should tolerate envelopes without `v`
+ * (legacy emitters published before versioning) and treat them as version `1`.
+ */
+export declare const SCHEMA_VERSION = 1;
 /**
  * The channel name for a `<lib>`/`<event>` pair: `aviary:<lib>:<event>`. This is
  * the cross-repo wire contract — keep it identical on producer and observer.
@@ -28,11 +35,22 @@ export declare function getChannel(lib: string, event: string): Channel;
  *   registered context accessor (if resolvable), else left undefined.
  * - The envelope is built and published ONLY when the channel `hasSubscribers`,
  *   so emitting is effectively free when nothing is listening.
+ * - When `opts.sample` is given, it is consulted AFTER the `hasSubscribers` gate
+ *   and BEFORE the envelope is built: a falsy result sheds this event without
+ *   allocating anything. Default (no `sample`) always publishes when subscribed.
+ * - The envelope carries the current {@link SCHEMA_VERSION} as `v`.
  * - Never throws: emitting observability must not break the caller.
  *
  * ```ts
  * emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+ * // Shed 90% of a hot event:
+ * emit('authz', 'decision', payload, { sample: () => Math.random() < 0.1 });
  * ```
+ *
+ * When `(lib, event)` is declared in the typed
+ * {@link import('./types.js').ChannelRegistry ChannelRegistry}, `payload` is
+ * checked against the declared type at compile time; every other pair keeps the
+ * untyped `unknown` payload. The runtime behavior is identical either way.
  */
-export declare function emit(lib: string, event: string, payload: unknown, opts?: EmitOptions): void;
+export declare function emit<TLib extends LibOf, TEvent extends EventOf<TLib>>(lib: TLib, event: TEvent, payload: PayloadOf<TLib, TEvent>, opts?: EmitOptions): void;
 //# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAA4B,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAmB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D,gEAAgE;AAChE,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAc9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAU3F"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAA4B,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAmB,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1F,gEAAgE;AAChE,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAc9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EACnE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAChC,IAAI,CAAC,EAAE,WAAW,GACjB,IAAI,CAoBN"}

package/dist/channel.js

@@ -3,6 +3,13 @@ import { resolveTraceId } from './context-accessor.js';
 import { onRegistryReset, registerChannel } from './registry.js';
 /** The prefix all channels created by this convention share. */
 export const CHANNEL_PREFIX = 'aviary';
+/**
+ * Current envelope schema version, stamped onto every emitted
+ * {@link DiagnosticEvent} as `v`. Bump this only when the wire shape changes in a
+ * way observers must adapt to. Observers should tolerate envelopes without `v`
+ * (legacy emitters published before versioning) and treat them as version `1`.
+ */
+export const SCHEMA_VERSION = 1;
 /**
  * The channel name for a `<lib>`/`<event>` pair: `aviary:<lib>:<event>`. This is
  * the cross-repo wire contract — keep it identical on producer and observer.
@@ -64,19 +71,41 @@ export function getChannel(lib, event) {
  *   registered context accessor (if resolvable), else left undefined.
  * - The envelope is built and published ONLY when the channel `hasSubscribers`,
  *   so emitting is effectively free when nothing is listening.
+ * - When `opts.sample` is given, it is consulted AFTER the `hasSubscribers` gate
+ *   and BEFORE the envelope is built: a falsy result sheds this event without
+ *   allocating anything. Default (no `sample`) always publishes when subscribed.
+ * - The envelope carries the current {@link SCHEMA_VERSION} as `v`.
  * - Never throws: emitting observability must not break the caller.
  *
  * ```ts
  * emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+ * // Shed 90% of a hot event:
+ * emit('authz', 'decision', payload, { sample: () => Math.random() < 0.1 });
  * ```
+ *
+ * When `(lib, event)` is declared in the typed
+ * {@link import('./types.js').ChannelRegistry ChannelRegistry}, `payload` is
+ * checked against the declared type at compile time; every other pair keeps the
+ * untyped `unknown` payload. The runtime behavior is identical either way.
  */
 export function emit(lib, event, payload, opts) {
     const channel = getChannel(lib, event);
     if (!channel.hasSubscribers)
         return;
     try {
+        // Load-shedding gate: consulted only when subscribed, before any allocation.
+        // A throwing sampler is treated as a skip (caught below) — never published.
+        if (opts?.sample !== undefined && !opts.sample())
+            return;
         const traceId = opts?.traceId ?? resolveTraceId();
-        const envelope = { ts: Date.now(), lib, event, traceId, payload };
+        const envelope = {
+            v: SCHEMA_VERSION,
+            ts: Date.now(),
+            lib,
+            event,
+            traceId,
+            payload,
+        };
         channel.publish(envelope);
     }
     catch {

package/dist/channel.js.map

@@ -1 +1 @@
-{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,OAAO,GAAG,cAAc,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE7D,8EAA8E;AAC9E,6EAA6E;AAC7E,eAAe,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,IAAI,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;QACrC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,GAAW,EAAE,KAAa,EAAE,OAAgB,EAAE,IAAkB;IACnF,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,cAAc;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAoB,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACnF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGjE,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,OAAO,GAAG,cAAc,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE7D,8EAA8E;AAC9E,6EAA6E;AAC7E,eAAe,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,IAAI,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;IAC1C,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;QACrC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,IAAI,CAClB,GAAS,EACT,KAAa,EACb,OAAgC,EAChC,IAAkB;IAElB,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,cAAc;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO;QACzD,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAoB;YAChC,CAAC,EAAE,cAAc;YACjB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,GAAG;YACH,KAAK;YACL,OAAO;YACP,OAAO;SACR,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { CHANNEL_PREFIX, channelName, emit, getChannel } from './channel.js';
+export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
 export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, getContextAccessor, resolveTraceId, setContextAccessor, type UserRef, } from './context-accessor.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
-export type { DiagnosticEvent, EmitOptions } from './types.js';
+export { SPAN_SCHEMA_VERSION, trace, type TraceChannelNames, traceChannelNames, type TracingChannel, tracingChannel, } from './trace.js';
+export type { ChannelRegistry, DiagnosticEvent, EmitOptions, EventOf, LibOf, PayloadOf, SpanEvent, SpanPhase, TraceOptions, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
-export { CHANNEL_PREFIX, channelName, emit, getChannel } from './channel.js';
+export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
 export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
+export { SPAN_SCHEMA_VERSION, trace, traceChannelNames, tracingChannel, } from './trace.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/trace.d.ts

@@ -0,0 +1,74 @@
+import type { EventOf, LibOf, PayloadOf, TraceOptions } from './types.js';
+/**
+ * Span envelope schema version, stamped onto every {@link SpanEvent} as `v`.
+ * Versioned independently of the POINT `SCHEMA_VERSION` so the two wire shapes
+ * can evolve apart. Observers should treat an absent `v` as version `1`.
+ */
+export declare const SPAN_SCHEMA_VERSION = 1;
+/**
+ * The five span sub-channel names for a `(lib, event)` pair. They extend the
+ * POINT `aviary:<lib>:<event>` name with a `:<phase>` suffix, mirroring Node's
+ * own `tracingChannel` sub-channels (start/end/asyncStart/asyncEnd/error) while
+ * staying inside the `aviary:` convention so the same generic observer can read
+ * both POINT and SPAN traffic.
+ */
+export interface TraceChannelNames {
+    start: string;
+    end: string;
+    asyncStart: string;
+    asyncEnd: string;
+    error: string;
+}
+/** Build the five span sub-channel names for a `(lib, event)` pair. */
+export declare function traceChannelNames(lib: string, event: string): TraceChannelNames;
+/**
+ * Wrap an (async) operation and publish span-like start / end / asyncStart /
+ * asyncEnd / error events over `node:diagnostics_channel`, so consumers get real
+ * start/end/error pairing with timing for authz decisions, durable steps, etc.
+ *
+ * Naming follows the existing convention: events ride
+ * `aviary:<lib>:<event>:<phase>` (see {@link traceChannelNames}). `emit` is
+ * unchanged — `trace` is the additional span surface.
+ *
+ * Lifecycle:
+ * - Sync `fn`: publishes `start` then, on return, `end` (with `result`); on
+ *   throw, `error`. The value/throw is propagated to the caller unchanged.
+ * - Async `fn` (returns a promise): publishes `start` synchronously, `asyncStart`
+ *   when the promise settles begins resolving, then `asyncEnd` (with `result`)
+ *   on fulfilment or `error` on rejection. The promise is returned to the caller.
+ *
+ * Cost: when NO span sub-channel has a subscriber, `trace` calls `fn` and returns
+ * its value directly — no span id, no envelope, no timing — so the hot path is a
+ * handful of `hasSubscribers` reads.
+ *
+ * Trace id: resolved once at span start from `opts.traceId` (wins) else the
+ * registered context accessor, and stamped on every phase event.
+ *
+ * ```ts
+ * const decision = trace('authz', 'decision', () => evaluate(req), { subject });
+ * const out = await trace('durable', 'step', () => runStep(), { name });
+ * ```
+ */
+export declare function trace<TLib extends LibOf, TEvent extends EventOf<TLib>, R>(lib: TLib, event: TEvent, fn: () => R, payload?: PayloadOf<TLib, TEvent>, opts?: TraceOptions): R;
+/** A {@link trace} bound to one `(lib, event)` pair — see {@link tracingChannel}. */
+export interface TracingChannel<TPayload = unknown> {
+    /** The base `aviary:<lib>:<event>` channel name. */
+    readonly name: string;
+    /** The five span sub-channel names. */
+    readonly channels: TraceChannelNames;
+    /** Trace an operation on this channel; same semantics as {@link trace}. */
+    trace<R>(fn: () => R, payload?: TPayload, opts?: TraceOptions): R;
+}
+/**
+ * A {@link trace} factory bound to a single `(lib, event)` pair — the ergonomic,
+ * reusable form for a hot call site that always traces the same operation. Named
+ * after Node's `diagnostics_channel.tracingChannel()` (whose sub-channels we
+ * mirror) but kept inside the `aviary:` convention.
+ *
+ * ```ts
+ * const decision = tracingChannel('authz', 'decision');
+ * decision.trace(() => evaluate(req), { subject });
+ * ```
+ */
+export declare function tracingChannel<TLib extends LibOf, TEvent extends EventOf<TLib>>(lib: TLib, event: TEvent): TracingChannel<PayloadOf<TLib, TEvent>>;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAwB,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAS/E;AA0GD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EACvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,CAAC,CAyDH;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,2EAA2E;IAC3E,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC;CACnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,IAAI,CAAC,EAC7E,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GACZ,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAMzC"}

package/dist/trace.js

@@ -0,0 +1,196 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { channelName } from './channel.js';
+import { resolveTraceId } from './context-accessor.js';
+import { onRegistryReset, registerChannel } from './registry.js';
+/**
+ * Span envelope schema version, stamped onto every {@link SpanEvent} as `v`.
+ * Versioned independently of the POINT `SCHEMA_VERSION` so the two wire shapes
+ * can evolve apart. Observers should treat an absent `v` as version `1`.
+ */
+export const SPAN_SCHEMA_VERSION = 1;
+/** Build the five span sub-channel names for a `(lib, event)` pair. */
+export function traceChannelNames(lib, event) {
+    const base = channelName(lib, event);
+    return {
+        start: `${base}:start`,
+        end: `${base}:end`,
+        asyncStart: `${base}:asyncStart`,
+        asyncEnd: `${base}:asyncEnd`,
+        error: `${base}:error`,
+    };
+}
+/**
+ * Per-`(lib, event)` cache of the resolved span {@link Channel}s, keyed by `lib`
+ * then `event` — the same two-level memo strategy `getChannel` uses, so the
+ * steady state is two `Map.get`s with no string allocation. The first trace of a
+ * pair pays the name builds + `diagnostics_channel.channel()` lookups + registry
+ * insert; every call after returns the cached object.
+ */
+const spanCache = new Map();
+// Drop the memo cache whenever the registry is reset (test-only), so the next
+// trace re-registers the base channel. Mirrors channel.ts.
+onRegistryReset(() => spanCache.clear());
+function getSpanChannels(lib, event) {
+    let byEvent = spanCache.get(lib);
+    if (byEvent !== undefined) {
+        const cached = byEvent.get(event);
+        if (cached !== undefined)
+            return cached;
+    }
+    else {
+        byEvent = new Map();
+        spanCache.set(lib, byEvent);
+    }
+    const names = traceChannelNames(lib, event);
+    const channels = {
+        base: channelName(lib, event),
+        start: diagnostics_channel.channel(names.start),
+        end: diagnostics_channel.channel(names.end),
+        asyncStart: diagnostics_channel.channel(names.asyncStart),
+        asyncEnd: diagnostics_channel.channel(names.asyncEnd),
+        error: diagnostics_channel.channel(names.error),
+    };
+    // Register the BASE channel name for discovery: a generic observer that knows
+    // the base name can derive all five span sub-channels via traceChannelNames.
+    registerChannel(channels.base);
+    byEvent.set(event, channels);
+    return channels;
+}
+/** True when ANY of the five span sub-channels currently has a subscriber. */
+function anySubscribed(ch) {
+    return (ch.start.hasSubscribers ||
+        ch.end.hasSubscribers ||
+        ch.asyncStart.hasSubscribers ||
+        ch.asyncEnd.hasSubscribers ||
+        ch.error.hasSubscribers);
+}
+let spanCounter = 0;
+/** A cheap, process-unique span id. Allocated only when a span is observed. */
+function nextSpanId() {
+    spanCounter = (spanCounter + 1) >>> 0;
+    return `${Date.now().toString(36)}-${spanCounter.toString(36)}`;
+}
+/** Publish one phase event on its sub-channel, never throwing. */
+function publishPhase(channel, phase, lib, event, spanId, traceId, extra) {
+    if (!channel.hasSubscribers)
+        return;
+    try {
+        const envelope = {
+            v: SPAN_SCHEMA_VERSION,
+            ts: Date.now(),
+            lib,
+            event,
+            phase,
+            spanId,
+            traceId,
+            ...extra,
+        };
+        channel.publish(envelope);
+    }
+    catch {
+        // Observability must never break the traced code path.
+    }
+}
+/** Detect a thenable so a sync `fn` returning a promise is traced as async. */
+function isPromiseLike(value) {
+    return (value != null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+/**
+ * Wrap an (async) operation and publish span-like start / end / asyncStart /
+ * asyncEnd / error events over `node:diagnostics_channel`, so consumers get real
+ * start/end/error pairing with timing for authz decisions, durable steps, etc.
+ *
+ * Naming follows the existing convention: events ride
+ * `aviary:<lib>:<event>:<phase>` (see {@link traceChannelNames}). `emit` is
+ * unchanged — `trace` is the additional span surface.
+ *
+ * Lifecycle:
+ * - Sync `fn`: publishes `start` then, on return, `end` (with `result`); on
+ *   throw, `error`. The value/throw is propagated to the caller unchanged.
+ * - Async `fn` (returns a promise): publishes `start` synchronously, `asyncStart`
+ *   when the promise settles begins resolving, then `asyncEnd` (with `result`)
+ *   on fulfilment or `error` on rejection. The promise is returned to the caller.
+ *
+ * Cost: when NO span sub-channel has a subscriber, `trace` calls `fn` and returns
+ * its value directly — no span id, no envelope, no timing — so the hot path is a
+ * handful of `hasSubscribers` reads.
+ *
+ * Trace id: resolved once at span start from `opts.traceId` (wins) else the
+ * registered context accessor, and stamped on every phase event.
+ *
+ * ```ts
+ * const decision = trace('authz', 'decision', () => evaluate(req), { subject });
+ * const out = await trace('durable', 'step', () => runStep(), { name });
+ * ```
+ */
+export function trace(lib, event, fn, payload, opts) {
+    const channels = getSpanChannels(lib, event);
+    // Hot path: nothing is listening → run fn directly, allocate nothing.
+    if (!anySubscribed(channels)) {
+        return fn();
+    }
+    const spanId = nextSpanId();
+    const traceId = opts?.traceId ?? resolveTraceId();
+    const startedAt = performance.now();
+    publishPhase(channels.start, 'start', lib, event, spanId, traceId, { payload });
+    let result;
+    try {
+        result = fn();
+    }
+    catch (error) {
+        publishPhase(channels.error, 'error', lib, event, spanId, traceId, {
+            error,
+            durationMs: performance.now() - startedAt,
+        });
+        throw error;
+    }
+    if (isPromiseLike(result)) {
+        // Async op: end marks the synchronous portion completing; asyncStart marks
+        // the continuation; asyncEnd carries the settled result/error + duration.
+        publishPhase(channels.end, 'end', lib, event, spanId, traceId, {
+            durationMs: performance.now() - startedAt,
+        });
+        publishPhase(channels.asyncStart, 'asyncStart', lib, event, spanId, traceId, {});
+        const settled = Promise.resolve(result).then((value) => {
+            publishPhase(channels.asyncEnd, 'asyncEnd', lib, event, spanId, traceId, {
+                result: value,
+                durationMs: performance.now() - startedAt,
+            });
+            return value;
+        }, (error) => {
+            publishPhase(channels.error, 'error', lib, event, spanId, traceId, {
+                error,
+                durationMs: performance.now() - startedAt,
+            });
+            throw error;
+        });
+        return settled;
+    }
+    // Sync success.
+    publishPhase(channels.end, 'end', lib, event, spanId, traceId, {
+        result,
+        durationMs: performance.now() - startedAt,
+    });
+    return result;
+}
+/**
+ * A {@link trace} factory bound to a single `(lib, event)` pair — the ergonomic,
+ * reusable form for a hot call site that always traces the same operation. Named
+ * after Node's `diagnostics_channel.tracingChannel()` (whose sub-channels we
+ * mirror) but kept inside the `aviary:` convention.
+ *
+ * ```ts
+ * const decision = tracingChannel('authz', 'decision');
+ * decision.trace(() => evaluate(req), { subject });
+ * ```
+ */
+export function tracingChannel(lib, event) {
+    return {
+        name: channelName(lib, event),
+        channels: traceChannelNames(lib, event),
+        trace: (fn, payload, opts) => trace(lib, event, fn, payload, opts),
+    };
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

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

package/dist/types.d.ts

@@ -6,6 +6,14 @@
  * emitting library and identified by `lib` + `event`.
  */
 export interface DiagnosticEvent<TPayload = unknown> {
+    /**
+     * Envelope schema version — bumped only when this wire shape changes in a way
+     * observers must adapt to. Stamped by `emit` with the current
+     * {@link import('./channel.js').SCHEMA_VERSION SCHEMA_VERSION}. Optional on the
+     * type so observers stay tolerant of legacy envelopes published before
+     * versioning existed (treat an absent `v` as the original, unversioned shape).
+     */
+    v?: number;
     /** Epoch millis when the event was emitted (`Date.now()` at publish time). */
     ts: number;
     /** The emitting library, e.g. `'billing'` — the `<lib>` in `aviary:<lib>:<event>`. */
@@ -21,6 +29,116 @@ export interface DiagnosticEvent<TPayload = unknown> {
     /** The library-defined payload. Opaque to this package and to observers. */
     payload: TPayload;
 }
+/**
+ * The optional, consumer-augmented typed channel registry: a `lib → event →
+ * payload` map. It is EMPTY by default — the untyped path (`payload: unknown`)
+ * is always available and unchanged. A library declares its channels by
+ * augmenting this interface via TypeScript declaration merging:
+ *
+ * ```ts
+ * declare module '@dudousxd/nestjs-diagnostics' {
+ *   interface ChannelRegistry {
+ *     billing: {
+ *       'invoice-paid': { invoiceId: string; amount: number };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * Once augmented, `emit('billing', 'invoice-paid', ...)` and
+ * `trace('billing', 'invoice-paid', ...)` get compile-time payload checking for
+ * that channel; every other `(lib, event)` pair keeps the untyped `unknown`
+ * payload. This is purely a type-level mechanism: there is no runtime registry
+ * of payload shapes and nothing is allocated.
+ */
+export interface ChannelRegistry {
+}
+/**
+ * `string`, kept assignable from any literal but offering autocomplete for the
+ * registered names. The `& {}` defeats literal-union widening so registered
+ * keys still surface as suggestions while every other string is accepted — this
+ * is what keeps the untyped path open even after the registry is augmented.
+ */
+type LooseString = string & {};
+/**
+ * Every `lib` declared in the {@link ChannelRegistry} (for autocomplete), plus
+ * any other `string` (the untyped path). Collapses to plain `string` when the
+ * registry is empty.
+ */
+export type LibOf = (keyof ChannelRegistry & string) | LooseString;
+/**
+ * Every `event` declared for `TLib` in the {@link ChannelRegistry} (for
+ * autocomplete), plus any other `string` (the untyped path). Collapses to plain
+ * `string` when `TLib` is not a registered lib.
+ */
+export type EventOf<TLib extends string> = TLib extends keyof ChannelRegistry ? (keyof ChannelRegistry[TLib] & string) | LooseString : string;
+/**
+ * The declared payload type for `(TLib, TEvent)` in the {@link ChannelRegistry},
+ * or `unknown` when the pair is not registered. This is what gives `emit`/`trace`
+ * their compile-time payload types for registered channels while leaving every
+ * other call on the original untyped `unknown` path.
+ */
+export type PayloadOf<TLib extends string, TEvent extends string> = TLib extends keyof ChannelRegistry ? TEvent extends keyof ChannelRegistry[TLib] ? ChannelRegistry[TLib][TEvent] : unknown : unknown;
+/**
+ * The phase of a traced operation, published as `phase` on every
+ * {@link SpanEvent}. Mirrors Node's `tracingChannel` sub-channels so observers
+ * can pair start/end and start/error into span-like records.
+ */
+export type SpanPhase = 'start' | 'end' | 'asyncStart' | 'asyncEnd' | 'error';
+/**
+ * The envelope published on the span sub-channels by `trace`. Extends the
+ * {@link DiagnosticEvent} POINT shape with span correlation + timing so a
+ * consumer can reconstruct real start/end/error pairs:
+ *
+ * - `aviary:<lib>:<event>:start` — `phase: 'start'`, carries `payload`.
+ * - `aviary:<lib>:<event>:end` — sync (or settled) completion, carries `result`
+ *   + `durationMs`.
+ * - `aviary:<lib>:<event>:asyncStart` / `:asyncEnd` — the async continuation of
+ *   a promise-returning op; `asyncEnd` carries `result`/`error` + `durationMs`.
+ * - `aviary:<lib>:<event>:error` — `phase: 'error'`, carries `error` (+
+ *   `durationMs`).
+ *
+ * Every event of a single span shares a `spanId` so observers can correlate
+ * them without relying on subscription ordering.
+ */
+export interface SpanEvent<TPayload = unknown, TResult = unknown> {
+    /**
+     * Span envelope schema version, stamped by `trace` with
+     * {@link import('./trace.js').SPAN_SCHEMA_VERSION SPAN_SCHEMA_VERSION}.
+     * Versioned independently of the POINT {@link DiagnosticEvent} `v`. Optional
+     * so observers stay tolerant of legacy/untagged envelopes.
+     */
+    v?: number;
+    /** Epoch millis when this phase event was published (`Date.now()`). */
+    ts: number;
+    /** The emitting library — the `<lib>` in `aviary:<lib>:<event>`. */
+    lib: string;
+    /** The traced operation name — the `<event>` in `aviary:<lib>:<event>`. */
+    event: string;
+    /** Which phase of the span this is. */
+    phase: SpanPhase;
+    /**
+     * Stable per-span correlation id shared by every phase event of one `trace`
+     * call. Lets observers pair start↔end / start↔error regardless of ordering.
+     */
+    spanId: string;
+    /**
+     * Trace id for the current request, when resolvable. Same semantics + stable
+     * monomorphic shape as {@link DiagnosticEvent.traceId}.
+     */
+    traceId?: string | undefined;
+    /** The caller-supplied payload, present on the `start` event. */
+    payload?: TPayload;
+    /** The operation's return value, present on `end`/`asyncEnd` on success. */
+    result?: TResult;
+    /** The thrown/rejected value, present on `error` (and `asyncEnd` on failure). */
+    error?: unknown;
+    /**
+     * Wall-clock duration in fractional millis from `start` to this phase,
+     * present on `end`/`asyncEnd`/`error`. Measured with `performance.now()`.
+     */
+    durationMs?: number;
+}
 /** Optional per-emit overrides. */
 export interface EmitOptions {
     /**
@@ -29,5 +147,24 @@ export interface EmitOptions {
      * any), or leave `traceId` undefined.
      */
     traceId?: string;
+    /**
+     * Optional load-shedding hook. Consulted by `emit` only AFTER the channel has
+     * subscribers and BEFORE the envelope is built/published: return `false` to
+     * drop this event without allocating the envelope, `true` to publish. Omit for
+     * the default (always publish when subscribed). A thrown sampler is treated as
+     * a skip — observability must never break the caller. Hot libraries can pass a
+     * cheap probabilistic predicate, e.g. `{ sample: () => Math.random() < 0.1 }`.
+     */
+    sample?: () => boolean;
+}
+/** Optional per-`trace` overrides. */
+export interface TraceOptions {
+    /**
+     * An explicit trace id for the whole span. When provided it wins over the
+     * registered {@link ContextAccessor} and is stamped on every phase event.
+     * Omit to auto-fill from the accessor (resolved once at span start).
+     */
+    traceId?: string;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD;;;;;;OAMG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;CAAG;AAEnC;;;;;GAKG;AACH,KAAK,WAAW,GAAG,MAAM,GAAG,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,IAAI,IAAI,SAAS,MAAM,eAAe,GACzE,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,WAAW,GACpD,MAAM,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CACnB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,IACnB,IAAI,SAAS,MAAM,eAAe,GAClC,MAAM,SAAS,MAAM,eAAe,CAAC,IAAI,CAAC,GACxC,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAC7B,OAAO,GACT,OAAO,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9D;;;;;OAKG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,17 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "//sideEffects": "NOT false: registry.ts and context-accessor.ts register process-global state on globalThis via Symbol.for AT IMPORT TIME (the cross-copy-stable channel registry + context accessor), and channel.ts/trace.ts register a reset hook at module load. A bundler told sideEffects:false could tree-shake these initializers away, breaking cross-copy global stability. The array lists exactly the side-effectful modules (matching both src and published dist paths); pure modules (index, types) stay tree-shakeable.",
+  "sideEffects": [
+    "**/registry.js",
+    "**/registry.ts",
+    "**/context-accessor.js",
+    "**/context-accessor.ts",
+    "**/channel.js",
+    "**/channel.ts",
+    "**/trace.js",
+    "**/trace.ts"
+  ],
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0",