@dudousxd/nestjs-diagnostics 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.7.0
+
+### Minor Changes
+
+- [`1568de4`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/1568de44f05770ad2559f7d6d4ea38d9d213d7e5) - Cross-lib dedup, no consumer config: lib-specific telescope watchers (nestjs-agent's,
+  nestjs-media's) record their `aviary:<lib>:<event>` channels as first-class typed entries — and
+  the generic bridge recorded them AGAIN as `diagnostic` entries unless the consumer hand-maintained
+  an exclude list. Now the libs resolve it themselves:
+
+  - core: `claimDiagnostics(lib, events)` registers `lib:event` keys in a process-global,
+    refcounted claim registry (`Symbol.for('aviary:diagnostics:claims')` — the raw convention is
+    documented so packages without this dependency can participate); returns a release fn.
+    `isDiagnosticClaimed(lib, event)` reads it.
+  - telescope: the generic watcher checks claims AT RECORD TIME (order-independent) and skips
+    claimed keys by default. `recordClaimed: true` opts back in; `exclude` still exists — its job
+    is muting noisy events (e.g. `media:upload.progress`), not dedup.
+
+  Lib watchers claim in their own upcoming releases; until then behavior is unchanged (nothing
+  claims → everything records, exactly as today).
+
+## 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

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/claims.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A process-wide registry of which `aviary:<lib>:<event>` channels are already
+ * recorded as a first-class, typed Telescope entry by a lib-specific watcher
+ * (e.g. nestjs-agent's own watcher for `aviary:agent:*`, nestjs-media's for
+ * `aviary:media:*`). The generic `DiagnosticWatcher` in
+ * `@dudousxd/nestjs-diagnostics-telescope` auto-subscribes to EVERY registered
+ * channel (see {@link registerChannel}), so without this registry every event a
+ * claiming lib emits would be recorded TWICE: once as its own typed entry, once
+ * as a generic `diagnostic` entry. Claiming a key tells the generic watcher "I
+ * already record this — skip it by default."
+ *
+ * ## RAW convention (no dependency on this package required)
+ * The registry is a plain `Map<string, number>` behind a well-known
+ * `Symbol.for` key, so a package that does NOT want to depend on
+ * `@dudousxd/nestjs-diagnostics` can still participate by replicating this
+ * structure exactly, without importing anything from here:
+ *
+ * - `Symbol.for('aviary:diagnostics:claims')` resolves to a
+ *   `Map<string, number>` stored on `globalThis`.
+ * - Each key is `` `${lib}:${event}` `` — the same label the "Busiest events"
+ *   dashboard panel and `DiagnosticWatcherOptions.exclude` use.
+ * - The value is a reference count, always `>= 1` while the key is claimed by
+ *   at least one caller. Claiming an already-claimed key increments the count;
+ *   releasing decrements it; the key is deleted (unclaimed again) only once the
+ *   count reaches `0`. This is what lets two independent watchers claim the
+ *   same key without one's release un-claiming it for the other.
+ * - A key is "claimed" iff the map has it; "unclaimed" iff absent (or its count
+ *   reached `0` and was deleted).
+ *
+ * ## Record-time-check contract
+ * A generic observer (like `DiagnosticWatcher`) MUST call
+ * {@link isDiagnosticClaimed} at RECORD time — when an event is actually
+ * published — not at subscribe time. This makes claiming order-independent: a
+ * lib-specific watcher may call {@link claimDiagnostics} before or after the
+ * generic watcher's `register()` runs, and every event recorded after the claim
+ * exists is skipped either way. Checking once at subscribe time would miss
+ * claims registered later and could not un-skip a released claim either.
+ */
+/**
+ * Claim `lib:event` for every event in `events`, so a generic observer skips
+ * them by default (see the record-time-check contract above). Call this once
+ * when a lib-specific watcher registers, passing every event it records as a
+ * typed entry.
+ *
+ * Reference-counted: claiming a key already claimed by a different call (e.g.
+ * two Telescope instances, or overlapping event lists) increments its count
+ * instead of overwriting it, so releasing one caller's claim never un-claims a
+ * key another caller still holds.
+ *
+ * Returns a release function that removes EXACTLY the keys this call added —
+ * decrementing each of `events`' counts by one, deleting the key only once its
+ * count reaches `0`. Idempotent: calling the release function more than once
+ * has no additional effect.
+ *
+ * ```ts
+ * const release = claimDiagnostics('agent', ['chat-request', 'tool-call']);
+ * // ... later, e.g. on watcher cleanup:
+ * release();
+ * ```
+ */
+export declare function claimDiagnostics(lib: string, events: readonly string[]): () => void;
+/**
+ * Whether `lib:event` is currently claimed by at least one
+ * {@link claimDiagnostics} call. Intended to be checked at record time by a
+ * generic observer, per the contract above.
+ */
+export declare function isDiagnosticClaimed(lib: string, event: string): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/dist/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAeH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,IAAI,CAgBnF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/claims.js

@@ -0,0 +1,98 @@
+/**
+ * A process-wide registry of which `aviary:<lib>:<event>` channels are already
+ * recorded as a first-class, typed Telescope entry by a lib-specific watcher
+ * (e.g. nestjs-agent's own watcher for `aviary:agent:*`, nestjs-media's for
+ * `aviary:media:*`). The generic `DiagnosticWatcher` in
+ * `@dudousxd/nestjs-diagnostics-telescope` auto-subscribes to EVERY registered
+ * channel (see {@link registerChannel}), so without this registry every event a
+ * claiming lib emits would be recorded TWICE: once as its own typed entry, once
+ * as a generic `diagnostic` entry. Claiming a key tells the generic watcher "I
+ * already record this — skip it by default."
+ *
+ * ## RAW convention (no dependency on this package required)
+ * The registry is a plain `Map<string, number>` behind a well-known
+ * `Symbol.for` key, so a package that does NOT want to depend on
+ * `@dudousxd/nestjs-diagnostics` can still participate by replicating this
+ * structure exactly, without importing anything from here:
+ *
+ * - `Symbol.for('aviary:diagnostics:claims')` resolves to a
+ *   `Map<string, number>` stored on `globalThis`.
+ * - Each key is `` `${lib}:${event}` `` — the same label the "Busiest events"
+ *   dashboard panel and `DiagnosticWatcherOptions.exclude` use.
+ * - The value is a reference count, always `>= 1` while the key is claimed by
+ *   at least one caller. Claiming an already-claimed key increments the count;
+ *   releasing decrements it; the key is deleted (unclaimed again) only once the
+ *   count reaches `0`. This is what lets two independent watchers claim the
+ *   same key without one's release un-claiming it for the other.
+ * - A key is "claimed" iff the map has it; "unclaimed" iff absent (or its count
+ *   reached `0` and was deleted).
+ *
+ * ## Record-time-check contract
+ * A generic observer (like `DiagnosticWatcher`) MUST call
+ * {@link isDiagnosticClaimed} at RECORD time — when an event is actually
+ * published — not at subscribe time. This makes claiming order-independent: a
+ * lib-specific watcher may call {@link claimDiagnostics} before or after the
+ * generic watcher's `register()` runs, and every event recorded after the claim
+ * exists is skipped either way. Checking once at subscribe time would miss
+ * claims registered later and could not un-skip a released claim either.
+ */
+const CLAIMS_KEY = Symbol.for('aviary:diagnostics:claims');
+const claimsGlobal = globalThis;
+const claims = claimsGlobal[CLAIMS_KEY] ?? new Map();
+claimsGlobal[CLAIMS_KEY] = claims;
+/** The `lib:event` label used as the claim-store key, same shape as `exclude` entries. */
+function claimKey(lib, event) {
+    return `${lib}:${event}`;
+}
+/**
+ * Claim `lib:event` for every event in `events`, so a generic observer skips
+ * them by default (see the record-time-check contract above). Call this once
+ * when a lib-specific watcher registers, passing every event it records as a
+ * typed entry.
+ *
+ * Reference-counted: claiming a key already claimed by a different call (e.g.
+ * two Telescope instances, or overlapping event lists) increments its count
+ * instead of overwriting it, so releasing one caller's claim never un-claims a
+ * key another caller still holds.
+ *
+ * Returns a release function that removes EXACTLY the keys this call added —
+ * decrementing each of `events`' counts by one, deleting the key only once its
+ * count reaches `0`. Idempotent: calling the release function more than once
+ * has no additional effect.
+ *
+ * ```ts
+ * const release = claimDiagnostics('agent', ['chat-request', 'tool-call']);
+ * // ... later, e.g. on watcher cleanup:
+ * release();
+ * ```
+ */
+export function claimDiagnostics(lib, events) {
+    const keys = events.map((event) => claimKey(lib, event));
+    for (const key of keys) {
+        claims.set(key, (claims.get(key) ?? 0) + 1);
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        for (const key of keys) {
+            const count = claims.get(key);
+            if (count === undefined)
+                continue;
+            if (count <= 1)
+                claims.delete(key);
+            else
+                claims.set(key, count - 1);
+        }
+    };
+}
+/**
+ * Whether `lib:event` is currently claimed by at least one
+ * {@link claimDiagnostics} call. Intended to be checked at record time by a
+ * generic observer, per the contract above.
+ */
+export function isDiagnosticClaimed(lib, event) {
+    return claims.has(claimKey(lib, event));
+}
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAC3D,MAAM,YAAY,GAAG,UAA+D,CAAC;AACrF,MAAM,MAAM,GAAe,YAAY,CAAC,UAAU,CAAC,IAAI,IAAI,GAAG,EAAkB,CAAC;AACjF,YAAY,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;AAElC,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,GAAW,EAAE,KAAa;IAC1C,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAyB;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACzD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,IAAI,KAAK,IAAI,CAAC;gBAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,KAAa;IAC5D,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { capability } from './capability.js';
 export type { CapabilityOf, CapabilityRegistry } from './capability.js';
-export { assertCapabilityNaming } from './conformance.js';
 export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
+export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
+export { assertCapabilityNaming } from './conformance.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 { SPAN_SCHEMA_VERSION, trace, type TraceChannelNames, traceChannelNames, type TracingChannel, tracingChannel, } from './trace.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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,6 +1,7 @@
 export { capability } from './capability.js';
-export { assertCapabilityNaming } from './conformance.js';
 export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
+export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
+export { assertCapabilityNaming } from './conformance.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';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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`).