@dudousxd/nestjs-diagnostics 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.6.1
+
+### Patch Changes
+
+- [#14](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/14) [`cced7fc`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/cced7fc843c84eaf7b51686321294355bf2dd346) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ship TanStack Intent agent skills (SKILL.md) inside the package.
+
+## 0.6.0
+
+### Minor Changes
+
+- [`16bd3a5`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/16bd3a5ae975edb8e8b9b8ea59d52e7a9a0b470f) - Diagnostics events can carry an optional `durationMs`. `emit(lib, event, payload, { durationMs })` stamps a wall-clock duration onto the envelope, and the generic Telescope watcher forwards it to the recorded entry's `durationMs`. This lets an observer (e.g. the Telescope OTel exporter) turn an `aviary:<lib>:<event>` stream into a **duration histogram** (p95/p99) instead of only a counter — so latency metrics can move onto the diagnostics→telescope path without losing their distribution.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -33,10 +33,19 @@ interface DiagnosticEvent<TPayload = unknown> {
 
 ## Emitting
 
+Call `emit` from your provider wherever something interesting happens:
+
 ```ts
+import { Injectable } from '@nestjs/common';
 import { emit } from '@dudousxd/nestjs-diagnostics';
 
-emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+@Injectable()
+export class BillingService {
+  async markInvoicePaid(invoiceId: string, amount: number) {
+    // … your domain logic …
+    emit('billing', 'invoice-paid', { invoiceId, amount });
+  }
+}
 ```
 
 `emit` builds and publishes the envelope **only when the channel has
@@ -44,10 +53,11 @@ subscribers** (`channel.hasSubscribers`), so a production process with no
 observer attached pays essentially nothing per call. It never throws —
 observability must not break the emitting code path.
 
-Need an explicit trace id? Pass it in `opts`:
+Need an explicit trace id? Pass it in `opts` — e.g. inside a handler that
+already holds a correlation id:
 
 ```ts
-emit('billing', 'invoice-paid', payload, { traceId: req.id });
+emit('billing', 'invoice-paid', payload, { traceId });
 ```
 
 ## Trace correlation

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,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"}
+{"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,CAuBN"}

package/dist/channel.js

@@ -105,6 +105,9 @@ export function emit(lib, event, payload, opts) {
             event,
             traceId,
             payload,
+            // Only set the key when a duration was provided — omitting it keeps the
+            // envelope shape monomorphic (no undefined-valued key on common events).
+            ...(opts?.durationMs !== undefined && { durationMs: opts.durationMs }),
         };
         channel.publish(envelope);
     }

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;;;;;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"}
+{"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;YACP,wEAAwE;YACxE,yEAAyE;YACzE,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;SACvE,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -28,6 +28,13 @@ export interface DiagnosticEvent<TPayload = unknown> {
     traceId?: string | undefined;
     /** The library-defined payload. Opaque to this package and to observers. */
     payload: TPayload;
+    /**
+     * Wall-clock duration of the operation this event describes, in milliseconds,
+     * when known. Lets observers build duration histograms (e.g. OTel histogram
+     * instruments) instead of only counters. Omit when the event is not tied to a
+     * timed operation. Stamped from {@link EmitOptions.durationMs} by `emit`.
+     */
+    durationMs?: number;
 }
 /**
  * The optional, consumer-augmented typed channel registry: a `lib → event →
@@ -156,6 +163,13 @@ export interface EmitOptions {
      * cheap probabilistic predicate, e.g. `{ sample: () => Math.random() < 0.1 }`.
      */
     sample?: () => boolean;
+    /**
+     * Wall-clock duration of the operation this event describes, in milliseconds.
+     * When provided, `emit` stamps it onto the {@link DiagnosticEvent} envelope as
+     * `durationMs`, letting downstream observers (e.g. the Telescope OTel exporter)
+     * build duration histograms instead of only counters.
+     */
+    durationMs?: number;
 }
 /** Optional per-`trace` overrides. */
 export interface TraceOptions {

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;;;;;;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"}
+{"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;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;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;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;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.5.0",
+  "version": "0.6.1",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -43,7 +43,8 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "//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": [
@@ -75,7 +76,8 @@
     "diagnostics-channel",
     "observability",
     "telemetry",
-    "events"
+    "events",
+    "tanstack-intent"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/capabilities/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: capabilities
+description: Share cross-library DI tokens via the capability half of the @dudousxd/nestjs-diagnostics protocol. capability(lib, name) mints a Symbol.for('@dudousxd/nestjs-<lib>:<name>') token producer and consumer resolve identically without importing each other; InjectCapability(lib, name) from /nestjs optionally injects a peer's capability; assertCapabilityNaming guards naming drift in contract tests; CapabilityRegistry/CapabilityOf give typed tokens via declaration merging. Mirrors channelName for events.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-diagnostics"
+  library_version: 0.6.0
+  framework: nestjs
+---
+
+# Cross-library capabilities (DI tokens)
+
+`@dudousxd/nestjs-diagnostics` carries two halves of one ecosystem protocol: the
+**event** transport (`emit` / channels) and **capabilities** — stable DI tokens
+two `@dudousxd/nestjs-*` libraries share **without importing each other**. A
+capability token is `Symbol.for('@dudousxd/nestjs-<lib>:<name>')`; because it goes
+through the global symbol registry, producer and consumer resolve the SAME symbol.
+It is the dependency-injection mirror of `channelName(lib, event)` for events.
+
+## Setup
+
+```bash
+pnpm add @dudousxd/nestjs-diagnostics
+# InjectCapability requires @nestjs/common
+```
+
+A producer library binds its capability under the shared token:
+
+```ts
+import { Module } from '@nestjs/common';
+import { capability } from '@dudousxd/nestjs-diagnostics';
+import { ContextAccessorImpl } from './accessor.js';
+
+// token === Symbol.for('@dudousxd/nestjs-context:accessor')
+@Module({
+  providers: [
+    ContextAccessorImpl,
+    { provide: capability('context', 'accessor'), useExisting: ContextAccessorImpl },
+  ],
+  exports: [capability('context', 'accessor')],
+})
+export class ContextModule {}
+```
+
+Source: `packages/core/src/capability.ts`, `packages/core/src/inject-capability.ts`.
+
+## Core patterns
+
+### 1. capability(lib, name) — the shared token
+
+`capability('context', 'accessor')` returns
+`Symbol.for('@dudousxd/nestjs-context:accessor')`. Any code in any package that
+calls it with the same `(lib, name)` gets the identical symbol, so a consumer can
+inject a producer's capability with no static dependency between them.
+
+```ts
+import { capability } from '@dudousxd/nestjs-diagnostics';
+const TOKEN = capability('context', 'accessor');
+```
+
+Source: `packages/core/src/capability.ts` (`capability`).
+
+### 2. InjectCapability(lib, name) — optional cross-lib injection
+
+From the `/nestjs` subpath, `InjectCapability` is shorthand for
+`@Optional() @Inject(capability(lib, name))` — when the producer library is
+absent, the parameter is `undefined` instead of breaking injection:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { InjectCapability } from '@dudousxd/nestjs-diagnostics/nestjs';
+import type { ContextAccessor } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class AuditService {
+  constructor(
+    @InjectCapability('context', 'accessor')
+    private readonly ctx?: ContextAccessor, // undefined when nestjs-context absent
+  ) {}
+}
+```
+
+You annotate the parameter type yourself (capability payload types are not auto-
+inferred across repos).
+
+Source: `packages/core/src/inject-capability.ts` (`InjectCapability`).
+
+### 3. assertCapabilityNaming — anti-drift guard for contract tests
+
+Assert every exported token of a library follows the canonical
+`@dudousxd/nestjs-<lib>:<name>` naming (i.e. was minted by `capability(lib, …)`).
+It throws naming the offending export, turning drift into a red test:
+
+```ts
+import { assertCapabilityNaming, capability } from '@dudousxd/nestjs-diagnostics';
+
+const tokens = { ACCESSOR: capability('context', 'accessor') };
+
+it('all capability tokens follow the naming convention', () => {
+  expect(() => assertCapabilityNaming('context', tokens)).not.toThrow();
+});
+```
+
+Source: `packages/core/src/conformance.ts` (`assertCapabilityNaming`).
+
+## Common mistakes
+
+### Minting the token with Symbol() instead of capability()
+
+```ts
+// Wrong — a unique symbol; the consumer's capability('context','accessor') won't match it.
+const TOKEN = Symbol('@dudousxd/nestjs-context:accessor');
+```
+
+```ts
+// Correct — Symbol.for via capability() so all copies resolve the same token.
+import { capability } from '@dudousxd/nestjs-diagnostics';
+const TOKEN = capability('context', 'accessor');
+```
+
+`Symbol(desc)` is always unique; only `Symbol.for(key)` (what `capability` uses)
+returns a process-shared symbol that producer and consumer both resolve.
+Source: `packages/core/src/capability.ts` (`capability`).
+
+### Injecting a capability without @Optional and crashing when the peer is absent
+
+```ts
+// Wrong — hard @Inject throws "Nest can't resolve dependency" when the producer isn't loaded.
+constructor(@Inject(capability('context', 'accessor')) private ctx: ContextAccessor) {}
+```
+
+```ts
+// Correct — InjectCapability is already optional; ctx is undefined when absent.
+constructor(@InjectCapability('context', 'accessor') private ctx?: ContextAccessor) {}
+```
+
+`InjectCapability` applies `Optional()` then `Inject(token)`, so a missing peer
+yields `undefined` rather than a resolution error — the whole point of an optional
+cross-library capability.
+Source: `packages/core/src/inject-capability.ts` (`Optional()` + `Inject(token)`).
+
+### Confusing capability tokens with event channels
+
+```ts
+// Wrong — capability is a DI token, not a channel; you cannot subscribe to it.
+import diagnostics_channel from 'node:diagnostics_channel';
+diagnostics_channel.channel(capability('context', 'accessor') as any); // type/runtime error
+```
+
+```ts
+// Correct — events go over channelName(); capabilities are injected.
+import { channelName } from '@dudousxd/nestjs-diagnostics';
+diagnostics_channel.channel(channelName('billing', 'invoice-paid')).subscribe(fn);
+```
+
+Capabilities (`Symbol.for(...)` DI tokens) and channels (`aviary:<lib>:<event>`
+strings) are the two distinct halves of the protocol — one is injected, the other
+is published/subscribed.
+Source: `packages/core/src/capability.ts`, `packages/core/src/channel.ts`.

package/skills/emit-diagnostics/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: emit-diagnostics
+description: Emit observability events from @dudousxd/nestjs-diagnostics with emit(lib, event, payload, opts) over node:diagnostics_channel on aviary:<lib>:<event>. Covers the DiagnosticEvent envelope (v, ts, lib, event, traceId, payload, durationMs), zero-overhead hasSubscribers gating, EmitOptions sampling and durationMs, typed ChannelRegistry declaration merging, and trace correlation via setContextAccessor / CONTEXT_ACCESSOR. No module to register; the core barrel is framework-agnostic.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-diagnostics"
+  library_version: 0.6.0
+  framework: nestjs
+---
+
+# Emit diagnostics events
+
+`@dudousxd/nestjs-diagnostics` is a tiny convention for emitting observability
+events over Node's built-in `node:diagnostics_channel`. A library calls
+`emit('billing', 'invoice-paid', payload)` and is done — whoever wants to observe
+subscribes. Emitting is effectively free when nothing is listening.
+
+There is **nothing to register** to emit: no module, no provider. The main barrel
+is a set of pure functions and is framework-agnostic (importable from non-Nest
+code).
+
+## Setup
+
+```bash
+pnpm add @dudousxd/nestjs-diagnostics
+```
+
+Call `emit` from any provider where something interesting happens:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { emit } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class BillingService {
+  async markInvoicePaid(invoiceId: string, amount: number) {
+    // … your domain logic …
+    emit('billing', 'invoice-paid', { invoiceId, amount });
+  }
+}
+```
+
+Every event flows over a channel named `aviary:<lib>:<event>` and carries a
+standard `DiagnosticEvent` envelope:
+
+```ts
+interface DiagnosticEvent<TPayload = unknown> {
+  v?: number;        // SCHEMA_VERSION stamped by emit (currently 1)
+  ts: number;        // Date.now() at publish time
+  lib: string;       // the <lib>, e.g. "billing"
+  event: string;     // the <event>, e.g. "invoice-paid"
+  traceId?: string;  // auto-filled from a context accessor when present
+  payload: TPayload; // your library-defined data
+  durationMs?: number; // set only when EmitOptions.durationMs is passed
+}
+```
+
+Source: `packages/core/src/channel.ts`, `packages/core/src/types.ts`.
+
+## Core patterns
+
+### 1. Zero-overhead emit (the central guarantee)
+
+`emit` builds and publishes the envelope **only when the channel has
+subscribers** (`channel.hasSubscribers`), so a production process with no
+observer attached pays essentially nothing per call — just two `Map.get`s and a
+boolean read. It also **never throws**: observability must never break the
+emitting code path.
+
+```ts
+// In prod with no Telescope/observer attached, this allocates no envelope.
+emit('authz', 'decision', { subject, allow: true });
+```
+
+Source: `packages/core/src/channel.ts` (`emit`, the `hasSubscribers` gate).
+
+### 2. EmitOptions: explicit traceId, sampling, durationMs
+
+```ts
+import { emit } from '@dudousxd/nestjs-diagnostics';
+
+// Explicit trace id (wins over the registered accessor):
+emit('billing', 'invoice-paid', payload, { traceId });
+
+// Load-shedding on a hot event — shed 90%, consulted only AFTER hasSubscribers
+// and BEFORE the envelope is built (no allocation when skipped):
+emit('authz', 'decision', payload, { sample: () => Math.random() < 0.1 });
+
+// Stamp a duration so downstream observers can build histograms:
+emit('cache', 'lookup', { key }, { durationMs: 4.2 });
+```
+
+`sample` returning `false` (or throwing) sheds the event without allocating the
+envelope. `durationMs` is set on the envelope only when provided, keeping the
+common envelope shape monomorphic.
+
+Source: `packages/core/src/types.ts` (`EmitOptions`), `packages/core/src/channel.ts`.
+
+### 3. Compile-time payload types via the typed ChannelRegistry
+
+By default every `(lib, event)` pair takes `payload: unknown`. A library can opt
+specific channels into compile-time payload checking by augmenting
+`ChannelRegistry` through TypeScript declaration merging — the untyped path stays
+open for every other channel:
+
+```ts
+declare module '@dudousxd/nestjs-diagnostics' {
+  interface ChannelRegistry {
+    billing: {
+      'invoice-paid': { invoiceId: string; amount: number };
+    };
+  }
+}
+
+emit('billing', 'invoice-paid', { invoiceId: 'inv_1', amount: 4200 }); // checked
+emit('anything', 'else', whatever);                                    // still unknown
+```
+
+This is a purely type-level mechanism: no runtime registry of payload shapes,
+nothing allocated.
+
+Source: `packages/core/src/types.ts` (`ChannelRegistry`, `LibOf`, `EventOf`, `PayloadOf`).
+
+### 4. Auto-correlated traceId via setContextAccessor
+
+If your app uses `@dudousxd/nestjs-context` (an optional peer — never imported by
+this package), register its accessor once and every `emit` auto-fills `traceId`
+from the current request:
+
+```ts
+import { setContextAccessor, CONTEXT_ACCESSOR } from '@dudousxd/nestjs-diagnostics';
+import { Inject, Optional, Injectable, type OnModuleInit } from '@nestjs/common';
+import type { ContextAccessor } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class DiagnosticsContextBridge implements OnModuleInit {
+  constructor(
+    @Optional() @Inject(CONTEXT_ACCESSOR) private readonly accessor?: ContextAccessor,
+  ) {}
+
+  onModuleInit() {
+    if (this.accessor) setContextAccessor(this.accessor);
+  }
+}
+```
+
+`CONTEXT_ACCESSOR` is `Symbol.for('@dudousxd/nestjs-context:accessor')` — the same
+token nestjs-context publishes under. Any object structurally matching the
+`ContextAccessor` interface works. `resolveTraceId()` reads it, never throwing.
+
+Source: `packages/core/src/context-accessor.ts`.
+
+## Common mistakes
+
+### Building the payload eagerly outside emit on a hot path
+
+```ts
+// Wrong — serialize() runs every call even when nobody is listening.
+const snapshot = serialize(hugeObject);
+emit('jobs', 'tick', snapshot);
+```
+
+```ts
+// Correct — gate expensive work behind hasSubscribers via getChannel.
+import { getChannel, emit } from '@dudousxd/nestjs-diagnostics';
+if (getChannel('jobs', 'tick').hasSubscribers) {
+  emit('jobs', 'tick', serialize(hugeObject));
+}
+```
+
+`emit` only skips allocating *its own* envelope when unsubscribed; it cannot skip
+work you did before calling it. Read `hasSubscribers` yourself for expensive
+payloads (or use `EmitOptions.sample` for cheap ones).
+Source: `packages/core/src/channel.ts` (`emit`, `getChannel`).
+
+### Expecting emit to throw or return a delivery result
+
+```ts
+// Wrong — emit never throws and returns void; there is no ack to await/catch.
+try {
+  const ok = await emit('billing', 'invoice-paid', payload);
+} catch (e) { /* never reached */ }
+```
+
+```ts
+// Correct — fire-and-forget; do not branch on its result.
+emit('billing', 'invoice-paid', payload);
+```
+
+`emit` returns `void` and swallows every internal error so a broken observer can
+never break the producer. There is no delivery guarantee, ordering, or replay.
+Source: `packages/core/src/channel.ts` (`emit` `try/catch`).
+
+### Putting the prefix or colons into lib/event yourself
+
+```ts
+// Wrong — emit already prepends 'aviary:' and joins with ':'.
+emit('aviary:billing', 'invoice:paid', payload); // channel: aviary:aviary:billing:invoice:paid
+```
+
+```ts
+// Correct — pass the bare lib and event segments.
+emit('billing', 'invoice-paid', payload);        // channel: aviary:billing:invoice-paid
+```
+
+`channelName(lib, event)` builds `aviary:<lib>:<event>`; passing pre-joined names
+produces a malformed channel that observers subscribed to `aviary:billing:*` will
+miss.
+Source: `packages/core/src/channel.ts` (`channelName`, `CHANNEL_PREFIX`).

package/skills/observe-channels/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: observe-channels
+description: Build a custom consumer of @dudousxd/nestjs-diagnostics events (OpenTelemetry span, APM, logger, test assertion) using the channel registry. Covers registeredChannels(), onChannelRegistered(cb), getChannel(lib, event), channelName(lib, event) and CHANNEL_PREFIX. Explains why node:diagnostics_channel has no wildcard, the subscribe-current-plus-future pattern, that subscribing flips hasSubscribers so producers start emitting, and resetRegistry for tests.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-diagnostics"
+  library_version: 0.6.0
+  framework: nestjs
+---
+
+# Observe channels with the registry
+
+Anyone can consume `aviary:<lib>:<event>` events — Telescope is just one consumer,
+and so is an OpenTelemetry span exporter, an APM bridge, a logger, or a test
+assertion. This skill covers the **low-level registry** you use to build your own
+generic consumer. (For NestJS provider methods, prefer `@OnDiagnostic`; for
+Telescope, use the telescope extension.)
+
+## Setup
+
+```bash
+pnpm add @dudousxd/nestjs-diagnostics
+```
+
+`node:diagnostics_channel` has **no wildcard subscription** — you can only
+subscribe by exact channel name. So this package keeps a process-global registry
+of every `aviary:<lib>:<event>` channel it has created. A generic consumer
+subscribes to the current set and any registered later:
+
+```ts
+import diagnostics_channel from 'node:diagnostics_channel';
+import {
+  registeredChannels,
+  onChannelRegistered,
+  type DiagnosticEvent,
+} from '@dudousxd/nestjs-diagnostics';
+
+function record(name: string) {
+  diagnostics_channel.channel(name).subscribe((msg) => {
+    const e = msg as DiagnosticEvent;
+    console.log(`[${e.lib}:${e.event}]`, e.traceId, e.payload);
+  });
+}
+
+// 1. subscribe to all current channels…
+for (const name of registeredChannels()) record(name);
+// 2. …and any registered in the future
+const off = onChannelRegistered(record);
+```
+
+Source: `packages/core/src/registry.ts`, `packages/core/src/channel.ts` (`channelName`, `getChannel`).
+
+## Core patterns
+
+### 1. Current + future, never replay
+
+`onChannelRegistered(cb)` fires once per channel registered **after** the call;
+it does NOT replay existing channels. Always pair it with `registeredChannels()`
+to cover both — exactly how the Telescope `DiagnosticWatcher` and the Redis relay
+auto-subscribe. The returned function unsubscribes the listener.
+
+```ts
+const off = onChannelRegistered(record);
+// later, on shutdown:
+off();
+```
+
+Source: `packages/core/src/registry.ts` (`registeredChannels`, `onChannelRegistered`).
+
+### 2. Subscribing turns producers on
+
+A channel is only registered the first time `getChannel`/`emit`/`trace` touches a
+`(lib, event)` pair. Subscribing to a channel also flips its `hasSubscribers` to
+`true`, which is precisely what makes `emit()` start building and publishing
+envelopes (zero overhead when nobody listens). So your consumer existing is what
+makes producers pay the cost.
+
+```ts
+import { getChannel } from '@dudousxd/nestjs-diagnostics';
+// channelName(lib, event) === `aviary:${lib}:${event}` (CHANNEL_PREFIX === 'aviary')
+const ch = getChannel('billing', 'invoice-paid'); // registers the name + memoizes the Channel
+```
+
+Source: `packages/core/src/channel.ts` (`getChannel`, `emit` `hasSubscribers` gate),
+`packages/core/src/registry.ts` (`registerChannel`).
+
+### 3. Resetting the registry in tests
+
+`resetRegistry()` is test-only: it forgets every registered channel and listener
+(and clears the internal channel memo caches via reset hooks) so a suite can
+assert registration in isolation. Do not call it in production code.
+
+```ts
+import { resetRegistry, registeredChannels, emit } from '@dudousxd/nestjs-diagnostics';
+
+beforeEach(() => resetRegistry());
+
+it('registers the channel on first emit', () => {
+  emit('billing', 'invoice-paid', { invoiceId: 'x', amount: 1 });
+  expect(registeredChannels()).toContain('aviary:billing:invoice-paid');
+});
+```
+
+Source: `packages/core/src/registry.ts` (`resetRegistry`, `onRegistryReset`).
+
+## Common mistakes
+
+### Using onChannelRegistered alone and missing existing channels
+
+```ts
+// Wrong — channels emitted before this line are never subscribed.
+onChannelRegistered(record);
+```
+
+```ts
+// Correct — replay the current set, then listen for future ones.
+for (const name of registeredChannels()) record(name);
+const off = onChannelRegistered(record);
+```
+
+`onChannelRegistered` only fires for registrations that happen *after* it is
+called; it deliberately does not replay history.
+Source: `packages/core/src/registry.ts` (`onChannelRegistered` doc).
+
+### Trying to subscribe with a wildcard channel name
+
+```ts
+// Wrong — node:diagnostics_channel has no wildcard; this is a literal name.
+import diagnostics_channel from 'node:diagnostics_channel';
+diagnostics_channel.channel('aviary:billing:*').subscribe(record); // never fires
+```
+
+```ts
+// Correct — enumerate names from the registry and subscribe to each.
+import { registeredChannels, onChannelRegistered } from '@dudousxd/nestjs-diagnostics';
+for (const name of registeredChannels()) record(name);
+const off = onChannelRegistered(record);
+```
+
+There is no pattern subscription in `diagnostics_channel`; the registry exists
+precisely to enumerate exact names for you.
+Source: `packages/core/src/registry.ts` (module doc), `packages/core/src/channel.ts`.
+
+### Throwing from a subscriber listener
+
+```ts
+// Wrong — publish() is synchronous; a throw lands in the producer's emit() call.
+diagnostics_channel.channel(name).subscribe((msg) => {
+  JSON.parse((msg as any).payload.raw); // may throw → breaks the emitter
+});
+```
+
+```ts
+// Correct — isolate your own consumer; never let it throw into emit().
+diagnostics_channel.channel(name).subscribe((msg) => {
+  try { handle(msg as DiagnosticEvent); } catch (err) { logger.error(err); }
+});
+```
+
+The core swallows errors in `emit`/`registerChannel`, but a listener you attach
+directly runs inside the synchronous `publish` — guard it yourself, as the
+Telescope watcher's `safeRecord` does.
+Source: `packages/telescope/src/diagnostic.watcher.ts` (`safeRecord`).

package/skills/react-with-on-diagnostic/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: react-with-on-diagnostic
+description: React to diagnostics events inside a NestJS app with @OnDiagnostic(lib, event?) from @dudousxd/nestjs-diagnostics/nestjs, wired by DiagnosticsModule.forRoot(). Decorate provider methods to handle one exact aviary:<lib>:<event> channel or every aviary:<lib>:* channel (current and future). Handlers run on the DI-resolved instance; sync throws and async rejections are logged and swallowed so a reaction can never break the synchronous emit() that triggered it.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-diagnostics"
+  library_version: 0.6.0
+  framework: nestjs
+---
+
+# React to events with @OnDiagnostic
+
+The `@dudousxd/nestjs-diagnostics/nestjs` subpath adds an ergonomic way to react
+to any `aviary:<lib>:<event>` event in a NestJS app — no extra event library.
+Register the module once, then decorate provider methods.
+
+## Setup
+
+```bash
+pnpm add @dudousxd/nestjs-diagnostics
+# requires @nestjs/common, @nestjs/core, reflect-metadata (optional peers)
+```
+
+Register the module at the app root (it is `global`, imports `DiscoveryModule`):
+
+```ts
+import { Module } from '@nestjs/common';
+import { DiagnosticsModule } from '@dudousxd/nestjs-diagnostics/nestjs';
+
+@Module({ imports: [DiagnosticsModule.forRoot()] })
+export class AppModule {}
+```
+
+Then decorate provider methods:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { OnDiagnostic } from '@dudousxd/nestjs-diagnostics/nestjs';
+import type { DiagnosticEvent } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class Reactions {
+  @OnDiagnostic('resilience', 'circuit-opened') // one exact channel
+  onCircuitOpen(e: DiagnosticEvent) { /* … */ }
+
+  @OnDiagnostic('resilience')                   // every aviary:resilience:* channel
+  onAnyResilience(e: DiagnosticEvent) { /* … */ }
+}
+```
+
+Source: `packages/core/src/nestjs/diagnostics.module.ts`,
+`packages/core/src/nestjs/on-diagnostic.decorator.ts`,
+`packages/core/src/nestjs/diagnostics.explorer.ts`.
+
+## Core patterns
+
+### 1. Exact channel vs library wildcard
+
+- `@OnDiagnostic('resilience', 'circuit-opened')` subscribes to the exact
+  `aviary:resilience:circuit-opened` channel.
+- `@OnDiagnostic('resilience')` (no `event`) subscribes to **every**
+  `aviary:resilience:*` channel — both those already registered at bootstrap and
+  any that appear later (a library's first `emit('resilience', 'newevent', …)`).
+
+The explorer scans providers on `onApplicationBootstrap`, then keeps an
+`onChannelRegistered` callback alive so future wildcard channels are subscribed
+automatically.
+
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`onApplicationBootstrap`).
+
+### 2. Handlers run on the DI-resolved instance
+
+The decorated method is invoked on the real provider instance, so injected
+dependencies are available:
+
+```ts
+@Injectable()
+export class AlertReactions {
+  constructor(private readonly notifier: Notifier) {}
+
+  @OnDiagnostic('billing', 'invoice-paid')
+  async onPaid(e: DiagnosticEvent<{ invoiceId: string; amount: number }>) {
+    await this.notifier.send(`Paid ${e.payload.invoiceId}`);
+  }
+}
+```
+
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke` calls `fn.call(instance, event)`).
+
+### 3. Never-throw isolation
+
+`diagnostics_channel.publish` is **synchronous**, so a subscriber that throws
+would propagate into the emitter's call stack. The explorer's `safeInvoke`
+catches synchronous throws and attaches a `.catch` to rejected promises, logging
+both — a reaction can never break the `emit()` that triggered it. Async handlers
+are therefore fire-and-forget (publish cannot await).
+
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke`, `logError`).
+
+## Common mistakes
+
+### Using @OnDiagnostic without importing DiagnosticsModule.forRoot()
+
+```ts
+// Wrong — decorator metadata is set, but nothing scans/subscribes it.
+@Module({})
+export class AppModule {}
+```
+
+```ts
+// Correct — forRoot() registers the explorer that wires every @OnDiagnostic.
+@Module({ imports: [DiagnosticsModule.forRoot()] })
+export class AppModule {}
+```
+
+`@OnDiagnostic` only records metadata; `DiagnosticsExplorer` (provided by
+`forRoot()`) is what discovers decorated methods and subscribes the channels at
+bootstrap.
+Source: `packages/core/src/nestjs/diagnostics.module.ts` (`forRoot` provides `DiagnosticsExplorer`).
+
+### Decorating a method on a non-provider class
+
+```ts
+// Wrong — a plain class Nest never instantiates is never scanned.
+class Reactions {
+  @OnDiagnostic('billing', 'invoice-paid') onPaid(e: DiagnosticEvent) {}
+}
+```
+
+```ts
+// Correct — @Injectable() and registered in a module's providers.
+@Injectable()
+export class Reactions {
+  @OnDiagnostic('billing', 'invoice-paid') onPaid(e: DiagnosticEvent) {}
+}
+```
+
+The explorer iterates `discovery.getProviders()`; only DI-managed provider
+instances are scanned for `@OnDiagnostic` metadata.
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`discovery.getProviders()`).
+
+### Throwing in a handler expecting the framework to retry
+
+```ts
+// Wrong — assuming a throw bubbles up or triggers a retry.
+@OnDiagnostic('billing', 'invoice-paid')
+onPaid(e: DiagnosticEvent) {
+  throw new Error('will be retried'); // it will NOT — it is logged and swallowed
+}
+```
+
+```ts
+// Correct — handle failures inside the reaction; it is fire-and-forget.
+@OnDiagnostic('billing', 'invoice-paid')
+async onPaid(e: DiagnosticEvent) {
+  try { await this.work(e); } catch (err) { this.logger.warn(err); }
+}
+```
+
+`safeInvoke` swallows throws/rejections by design, so emission stays safe — there
+is no delivery guarantee, retry, or replay.
+Source: `packages/core/src/nestjs/diagnostics.explorer.ts` (`safeInvoke`).

package/skills/trace-spans/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: trace-spans
+description: Emit span-like start/end/asyncStart/asyncEnd/error events with trace(lib, event, fn, payload, opts) and tracingChannel(lib, event) from @dudousxd/nestjs-diagnostics. Wraps sync or async operations over aviary:<lib>:<event>:<phase> sub-channels, producing SpanEvent envelopes with spanId, durationMs, result and error so observers reconstruct real spans. Zero overhead when no span sub-channel has subscribers; never throws; SPAN_SCHEMA_VERSION, traceChannelNames.
+license: MIT
+metadata:
+  type: core
+  library: "@dudousxd/nestjs-diagnostics"
+  library_version: 0.6.0
+  framework: nestjs
+---
+
+# Trace operations as spans
+
+`emit` publishes a single POINT event. `trace` wraps an operation and publishes
+span-like **start / end / asyncStart / asyncEnd / error** events with timing, so
+observers can reconstruct real start↔end↔error pairs (durable steps, authz
+decisions, cache fetches). It mirrors Node's `diagnostics_channel.tracingChannel`
+sub-channels but stays inside the `aviary:` convention.
+
+## Setup
+
+```bash
+pnpm add @dudousxd/nestjs-diagnostics
+```
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { trace } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class AuthzService {
+  evaluate(req: Request) {
+    // Sync op: publishes start then end (with result) — or error on throw.
+    return trace('authz', 'decision', () => this.run(req), { subject: req.user });
+  }
+
+  async runStep(input: StepInput) {
+    // Async op: start, end (sync portion), asyncStart, then asyncEnd (with result).
+    return await trace('durable', 'step', () => this.execute(input), { name: 'charge' });
+  }
+}
+```
+
+Span events ride `aviary:<lib>:<event>:<phase>`; the base `aviary:<lib>:<event>`
+name is what gets registered for discovery. A `SpanEvent` carries `v`, `ts`,
+`lib`, `event`, `phase`, a per-span `spanId`, optional `traceId`, and
+`payload` / `result` / `error` / `durationMs` depending on the phase.
+
+Source: `packages/core/src/trace.ts`, `packages/core/src/types.ts` (`SpanEvent`, `SpanPhase`).
+
+## Core patterns
+
+### 1. The span lifecycle
+
+- **Sync `fn`** → `start` (carries `payload`), then on return `end` (carries
+  `result` + `durationMs`); on throw `error` (carries `error` + `durationMs`).
+  The return value / throw is propagated to the caller unchanged.
+- **Async `fn`** (returns a promise) → `start` synchronously, then `end` for the
+  sync portion, `asyncStart`, and finally `asyncEnd` (with `result` + `durationMs`)
+  on fulfilment or `error` on rejection. The promise is returned to the caller.
+
+Every phase event of one `trace` call shares a `spanId`, so observers pair them
+without relying on subscription order. `durationMs` is measured with
+`performance.now()`.
+
+Source: `packages/core/src/trace.ts` (`trace`, `publishPhase`).
+
+### 2. Zero overhead when unobserved
+
+When NO span sub-channel has a subscriber, `trace` calls `fn()` and returns its
+value directly — no `spanId`, no envelope, no timing. The hot path is just five
+`hasSubscribers` reads (`anySubscribed`).
+
+```ts
+// In prod with no observer: equivalent to `return this.run(req)`.
+const decision = trace('authz', 'decision', () => this.run(req), { subject });
+```
+
+Source: `packages/core/src/trace.ts` (`anySubscribed`, the early `return fn()`).
+
+### 3. tracingChannel for a hot, fixed call site
+
+Bind `trace` to one `(lib, event)` pair when a call site always traces the same
+operation:
+
+```ts
+import { tracingChannel } from '@dudousxd/nestjs-diagnostics';
+
+const decision = tracingChannel('authz', 'decision');
+// decision.name      -> 'aviary:authz:decision'
+// decision.channels  -> the five span sub-channel names (traceChannelNames)
+
+const out = decision.trace(() => evaluate(req), { subject });
+```
+
+Source: `packages/core/src/trace.ts` (`tracingChannel`, `TracingChannel`, `traceChannelNames`).
+
+## Common mistakes
+
+### Passing an already-invoked promise instead of a thunk
+
+```ts
+// Wrong — fn() is called by you, so trace can't bracket start/end around it.
+trace('durable', 'step', this.execute(input)); // type error: not a function
+```
+
+```ts
+// Correct — pass a zero-arg function; trace invokes it between start and end.
+await trace('durable', 'step', () => this.execute(input), { name: 'charge' });
+```
+
+`trace(lib, event, fn, payload?, opts?)` takes a `fn: () => R` it calls itself;
+the promise must be created inside the thunk so `start` precedes it.
+Source: `packages/core/src/trace.ts` (`trace` signature).
+
+### Forgetting to return / await the trace result
+
+```ts
+// Wrong — the operation runs but the caller loses its value and unhandled rejections.
+async charge() {
+  trace('durable', 'step', () => this.execute());
+}
+```
+
+```ts
+// Correct — trace returns fn's value (or its promise); return/await it.
+async charge() {
+  return await trace('durable', 'step', () => this.execute());
+}
+```
+
+`trace` is transparent: it returns exactly what `fn` returns (the same promise for
+async). Drop the return and you drop the result and its error handling.
+Source: `packages/core/src/trace.ts` (`trace` returns `result` / the settled promise).
+
+### Subscribing only to the base channel and expecting span events
+
+```ts
+// Wrong — span phases are published on sub-channels, not the base name.
+import diagnostics_channel from 'node:diagnostics_channel';
+diagnostics_channel.channel('aviary:authz:decision').subscribe(onSpan); // never fires
+```
+
+```ts
+// Correct — subscribe to the phase sub-channels via traceChannelNames.
+import { traceChannelNames } from '@dudousxd/nestjs-diagnostics';
+const n = traceChannelNames('authz', 'decision');
+for (const name of [n.start, n.end, n.asyncStart, n.asyncEnd, n.error]) {
+  diagnostics_channel.channel(name).subscribe(onSpan);
+}
+```
+
+`trace` publishes on `aviary:<lib>:<event>:start|end|asyncStart|asyncEnd|error`;
+only the base name is registered for discovery, so a generic observer must derive
+the sub-channels.
+Source: `packages/core/src/trace.ts` (`traceChannelNames`, `getSpanChannels`).