@adonis-agora/telescope 0.2.0 → 0.3.0

package/dist/src/query/n_plus_one.d.ts

@@ -0,0 +1,60 @@
+import { type Entry } from '../entry.js';
+/** A flat family-count N+1 insight — "query template X ran N times". */
+export interface NPlusOneInsight {
+    familyHash: string;
+    count: number;
+    sql: string;
+}
+/**
+ * Flat N+1 detection — ported from `nestjs-telescope`'s `query/n-plus-one.ts`.
+ * Group query entries by `familyHash`; report templates that ran `>= threshold`
+ * times. Pure; order follows insertion (first-seen family first).
+ */
+export declare function detectNPlusOne(entries: Entry[], threshold: number): NPlusOneInsight[];
+/**
+ * A detected N+1 LOOP pattern within a single request/trace: one driving "parent"
+ * query (the SELECT that produced the rows being iterated) followed by N
+ * similarly-shaped "child" queries (the per-row lookups). Richer than the flat
+ * {@link detectNPlusOne} family-count: it attributes a likely parent and weights
+ * by the total time WASTED in the loop, so the worst offenders rank first.
+ */
+export interface NPlusOnePattern {
+    /** The repeated child query's family hash. */
+    childFamilyHash: string;
+    /** A representative child SQL (template/text). */
+    childSql: string;
+    /** How many times the child query ran in the trace (>= threshold). */
+    count: number;
+    /** Sum of the child queries' durations (ms) — the "wasted" time, the rank key. */
+    totalDurationMs: number;
+    /**
+     * The family hash of the query that most likely drove the loop — the distinct
+     * query immediately preceding the loop in record order — or `null` when the
+     * loop is the first thing in the trace (no identifiable parent).
+     */
+    parentFamilyHash: string | null;
+    /** The likely-parent SQL, or `null` when there is no identifiable parent. */
+    parentSql: string | null;
+    /** A representative child entry id (deep-link / hydration seam). */
+    representativeId: string;
+    /** The trace the pattern was found in. */
+    traceId: string;
+}
+export interface NPlusOnePatternOptions {
+    /** Minimum repetitions of one child template to flag a loop. */
+    threshold: number;
+}
+/**
+ * Detect N+1 loop patterns in a request/trace's query entries. Ported from
+ * `nestjs-telescope`'s `query/n-plus-one-pattern.ts` (NestJS `batchId` becomes
+ * Adonis `traceId`). For each query family that repeats `>= threshold` times we
+ * emit a pattern weighted by the loop's total duration and attribute the likely
+ * driving parent (the distinct query that ran just before the loop began). Pure;
+ * ordered by total wasted duration desc.
+ *
+ * NOTE: callers pass entries in OLDEST-FIRST record order (ascending sequence) so
+ * "the query immediately preceding the loop" is meaningful. The store returns
+ * newest-first, so the service reverses before calling.
+ */
+export declare function detectNPlusOnePatterns(entries: Entry[], options: NPlusOnePatternOptions): NPlusOnePattern[];
+//# sourceMappingURL=n_plus_one.d.ts.map

package/dist/src/query/n_plus_one.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"n_plus_one.d.ts","sourceRoot":"","sources":["../../../src/query/n_plus_one.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,aAAa,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAkBrF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,KAAK,EAAE,EAChB,OAAO,EAAE,sBAAsB,GAC9B,eAAe,EAAE,CA8CnB"}

package/dist/src/query/n_plus_one.js

@@ -0,0 +1,102 @@
+import { EntryType } from '../entry.js';
+/** Extract the `sql` string from a query entry's content, or `''`. */
+function sqlOf(entry) {
+    const record = typeof entry.content === 'object' && entry.content !== null
+        ? entry.content
+        : null;
+    return record !== null && typeof record.sql === 'string' ? record.sql : '';
+}
+/**
+ * Flat N+1 detection — ported from `nestjs-telescope`'s `query/n-plus-one.ts`.
+ * Group query entries by `familyHash`; report templates that ran `>= threshold`
+ * times. Pure; order follows insertion (first-seen family first).
+ */
+export function detectNPlusOne(entries, threshold) {
+    const groups = new Map();
+    for (const entry of entries) {
+        if (entry.type !== EntryType.Query || entry.familyHash === null)
+            continue;
+        const existing = groups.get(entry.familyHash);
+        if (existing) {
+            existing.count += 1;
+        }
+        else {
+            groups.set(entry.familyHash, { count: 1, sql: sqlOf(entry) });
+        }
+    }
+    const insights = [];
+    for (const [familyHash, group] of groups) {
+        if (group.count >= threshold) {
+            insights.push({ familyHash, count: group.count, sql: group.sql });
+        }
+    }
+    return insights;
+}
+/**
+ * Detect N+1 loop patterns in a request/trace's query entries. Ported from
+ * `nestjs-telescope`'s `query/n-plus-one-pattern.ts` (NestJS `batchId` becomes
+ * Adonis `traceId`). For each query family that repeats `>= threshold` times we
+ * emit a pattern weighted by the loop's total duration and attribute the likely
+ * driving parent (the distinct query that ran just before the loop began). Pure;
+ * ordered by total wasted duration desc.
+ *
+ * NOTE: callers pass entries in OLDEST-FIRST record order (ascending sequence) so
+ * "the query immediately preceding the loop" is meaningful. The store returns
+ * newest-first, so the service reverses before calling.
+ */
+export function detectNPlusOnePatterns(entries, options) {
+    const queries = entries.filter((entry) => entry.type === EntryType.Query && entry.familyHash !== null);
+    const groups = new Map();
+    queries.forEach((entry, index) => {
+        const familyHash = entry.familyHash;
+        const duration = typeof entry.durationMs === 'number' ? entry.durationMs : 0;
+        const existing = groups.get(familyHash);
+        if (existing) {
+            existing.count += 1;
+            existing.totalDurationMs += duration;
+        }
+        else {
+            groups.set(familyHash, {
+                count: 1,
+                totalDurationMs: duration,
+                representativeId: entry.id,
+                sql: sqlOf(entry),
+                firstIndex: index,
+            });
+        }
+    });
+    const patterns = [];
+    for (const [childFamilyHash, group] of groups) {
+        if (group.count < options.threshold)
+            continue;
+        const parent = findParent(queries, group.firstIndex, childFamilyHash);
+        patterns.push({
+            childFamilyHash,
+            childSql: group.sql,
+            count: group.count,
+            totalDurationMs: group.totalDurationMs,
+            parentFamilyHash: parent?.familyHash ?? null,
+            parentSql: parent === null ? null : sqlOf(parent),
+            representativeId: group.representativeId,
+            traceId: queries[group.firstIndex]?.traceId ?? '',
+        });
+    }
+    return patterns.sort((a, b) => b.totalDurationMs - a.totalDurationMs ||
+        b.count - a.count ||
+        a.childFamilyHash.localeCompare(b.childFamilyHash));
+}
+/**
+ * The likely driving parent for a loop whose first child is at `firstIndex`:
+ * walking BACKWARDS from just before the loop, the first query of a DIFFERENT
+ * family. Returns `null` when none precedes it (the loop is the trace's start).
+ */
+function findParent(queries, firstIndex, childFamilyHash) {
+    for (let i = firstIndex - 1; i >= 0; i--) {
+        const candidate = queries[i];
+        if (candidate !== undefined && candidate.familyHash !== childFamilyHash) {
+            return candidate;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=n_plus_one.js.map

package/dist/src/query/n_plus_one.js.map

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

package/dist/src/registry.d.ts

@@ -1,5 +1,6 @@
 import type { ExtensionRegistry } from './extension/registry.js';
 import type { TelescopeStore } from './store.js';
+import type { EntryEvents } from './stream/entry_events.js';
 /**
  * The live runtime telescope handles, published on a cross-copy-stable global slot
  * so the request middleware can reach the active store WITHOUT constructor wiring
@@ -14,6 +15,12 @@ export interface TelescopeRuntime {
     requestWatcherEnabled: boolean;
     /** The booted extension registry (entry types / dashboards / data providers), or `null`. */
     registry: ExtensionRegistry | null;
+    /**
+     * The live SSE entry-events bus the store's write path publishes persisted
+     * entries to and the UI stream route subscribes to, or `null` when live
+     * streaming is disabled / not booted.
+     */
+    entryEvents: EntryEvents | null;
 }
 /** The shared runtime handle. */
 export declare function getTelescopeRuntime(): TelescopeRuntime;
@@ -21,6 +28,8 @@ export declare function getTelescopeRuntime(): TelescopeRuntime;
 export declare function setTelescopeRuntime(store: TelescopeStore, requestWatcherEnabled: boolean): void;
 /** Publish the booted extension registry so the UI can serve its dashboards + providers. */
 export declare function setTelescopeExtensionRegistry(registry: ExtensionRegistry | null): void;
+/** Publish the SSE entry-events bus so the UI stream route can subscribe to it. */
+export declare function setTelescopeEntryEvents(entryEvents: EntryEvents | null): void;
 /** Tear down the runtime (called by the provider at shutdown). */
 export declare function resetTelescopeRuntime(): void;
 //# sourceMappingURL=registry.d.ts.map

package/dist/src/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,iDAAiD;IACjD,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4FAA4F;IAC5F,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACpC;AAYD,iCAAiC;AACjC,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,OAAO,GAAG,IAAI,CAG/F;AAED,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAEtF;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,iDAAiD;IACjD,qBAAqB,EAAE,OAAO,CAAC;IAC/B,4FAA4F;IAC5F,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAaD,iCAAiC;AACjC,wBAAgB,mBAAmB,IAAI,gBAAgB,CAEtD;AAED,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,OAAO,GAAG,IAAI,CAG/F;AAED,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAEtF;AAED,mFAAmF;AACnF,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAE7E;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}

package/dist/src/registry.js

@@ -4,6 +4,7 @@ const runtime = globalStore[RUNTIME_KEY] ?? {
     store: null,
     requestWatcherEnabled: false,
     registry: null,
+    entryEvents: null,
 };
 globalStore[RUNTIME_KEY] = runtime;
 /** The shared runtime handle. */
@@ -19,10 +20,15 @@ export function setTelescopeRuntime(store, requestWatcherEnabled) {
 export function setTelescopeExtensionRegistry(registry) {
     runtime.registry = registry;
 }
+/** Publish the SSE entry-events bus so the UI stream route can subscribe to it. */
+export function setTelescopeEntryEvents(entryEvents) {
+    runtime.entryEvents = entryEvents;
+}
 /** Tear down the runtime (called by the provider at shutdown). */
 export function resetTelescopeRuntime() {
     runtime.store = null;
     runtime.requestWatcherEnabled = false;
     runtime.registry = null;
+    runtime.entryEvents = null;
 }
 //# sourceMappingURL=registry.js.map

package/dist/src/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAC3D,MAAM,WAAW,GAAG,UAAsE,CAAC;AAE3F,MAAM,OAAO,GAAqB,WAAW,CAAC,WAAW,CAAC,IAAI;IAC5D,KAAK,EAAE,IAAI;IACX,qBAAqB,EAAE,KAAK;IAC5B,QAAQ,EAAE,IAAI;CACf,CAAC;AACF,WAAW,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;AAEnC,iCAAiC;AACjC,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,KAAqB,EAAE,qBAA8B;IACvF,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IACtB,OAAO,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;AACxD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,6BAA6B,CAAC,QAAkC;IAC9E,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,qBAAqB;IACnC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,qBAAqB,GAAG,KAAK,CAAC;IACtC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAC3D,MAAM,WAAW,GAAG,UAAsE,CAAC;AAE3F,MAAM,OAAO,GAAqB,WAAW,CAAC,WAAW,CAAC,IAAI;IAC5D,KAAK,EAAE,IAAI;IACX,qBAAqB,EAAE,KAAK;IAC5B,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,IAAI;CAClB,CAAC;AACF,WAAW,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;AAEnC,iCAAiC;AACjC,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,KAAqB,EAAE,qBAA8B;IACvF,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;IACtB,OAAO,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;AACxD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,6BAA6B,CAAC,QAAkC;IAC9E,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,uBAAuB,CAAC,WAA+B;IACrE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;AACpC,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,qBAAqB;IACnC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,qBAAqB,GAAG,KAAK,CAAC;IACtC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;AAC7B,CAAC"}

package/dist/src/sampling/sampling.d.ts

@@ -0,0 +1,52 @@
+import type { RecordInput } from '../entry.js';
+/**
+ * Tail-sampling rule for a single entry type. Keeps `rate` of the noise but
+ * always retains the entries that matter — errors and slow ones.
+ */
+export interface SamplingRule {
+    /** Base keep-rate 0–1 applied to ordinary entries of this type. */
+    rate: number;
+    /** When true, always keep entries that look like errors (see {@link isErrorEntry}). */
+    keepErrors?: boolean;
+    /** When set, always keep entries whose `durationMs` is at least this value. */
+    keepSlowMs?: number;
+}
+/**
+ * Per-type sampling configuration. Each type maps to either a bare keep-rate
+ * (uniform down-sampling) or a {@link SamplingRule} object (tail-sampling: keep a
+ * fraction but always retain errors / slow entries). The reserved `default` key
+ * applies to every entry type that lacks a specific rate override.
+ */
+export type SamplingConfig = Record<string, number | SamplingRule>;
+/**
+ * Pragmatic, cheap structural error check used by tail-sampling's `keepErrors`.
+ * Reads only shallow, already-present fields — no deep walk — so it stays on the
+ * hot path. An entry "looks like an error" when:
+ *  - its `tags` include `'failed'`, OR
+ *  - `content.failed === true`, OR
+ *  - `content.statusCode >= 500`, OR
+ *  - `content.level` is `'warn'`, `'error'`, or `'fatal'` (a Log entry).
+ */
+export declare function isErrorEntry(input: RecordInput): boolean;
+/**
+ * Projects a {@link SamplingConfig} down to bare per-type keep-rates for the
+ * meta/dashboard contract, which only surfaces the headline rate.
+ */
+export declare function samplingRates(sampling: SamplingConfig): Record<string, number>;
+/**
+ * Tail-sampling decision for one input. Plain-number per-type config behaves
+ * exactly as a uniform keep-rate. A {@link SamplingRule} additionally always
+ * keeps errors (`keepErrors`) and slow entries (`durationMs >= keepSlowMs`)
+ * before falling back to the base rate. `random` is the injected 0–1 source.
+ *
+ * Default-neutral: a type with no rule (and no `default`) is always kept, so an
+ * unset `sampling` config records everything exactly as before.
+ */
+export declare function passesSampling(sampling: SamplingConfig, input: RecordInput, random: () => number): boolean;
+/**
+ * Normalize the author-facing `sampling` option (a bare number → `{ default }`,
+ * or a {@link SamplingConfig} as-is, or `undefined` → `{}` meaning record
+ * everything) into a {@link SamplingConfig}.
+ */
+export declare function resolveSampling(sampling?: number | SamplingConfig): SamplingConfig;
+//# sourceMappingURL=sampling.d.ts.map

package/dist/src/sampling/sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","sourceRoot":"","sources":["../../../src/sampling/sampling.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAgB/C;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAwBxD;AAUD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,MAAM,GACnB,OAAO,CA4BT;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,cAAc,CAIlF"}

package/dist/src/sampling/sampling.js

@@ -0,0 +1,111 @@
+/**
+ * Tail-sampling for the WRITE path. Ported from `nestjs-telescope`'s
+ * `config/sampling.ts`: a per-entry-type keep `rate` plus `keepErrors` /
+ * `keepSlowMs` overrides so a host can sample noisy types aggressively while
+ * never dropping the entries that matter (errors, slow operations).
+ *
+ * Everything here is a PURE function with an injected RNG, so the sampling
+ * decision is deterministic in tests (no flaky `Math.random()` on the hot path).
+ */
+/** Log levels that count as an error for `keepErrors` — a `warn` / `error` /
+ *  `fatal` line is exactly what you never want sampled away. */
+const ERROR_LOG_LEVELS = new Set(['warn', 'error', 'fatal']);
+/**
+ * Pragmatic, cheap structural error check used by tail-sampling's `keepErrors`.
+ * Reads only shallow, already-present fields — no deep walk — so it stays on the
+ * hot path. An entry "looks like an error" when:
+ *  - its `tags` include `'failed'`, OR
+ *  - `content.failed === true`, OR
+ *  - `content.statusCode >= 500`, OR
+ *  - `content.level` is `'warn'`, `'error'`, or `'fatal'` (a Log entry).
+ */
+export function isErrorEntry(input) {
+    if (input.tags?.includes('failed')) {
+        return true;
+    }
+    const { content } = input;
+    if (content === null || typeof content !== 'object') {
+        return false;
+    }
+    if ('failed' in content && content.failed === true) {
+        return true;
+    }
+    if ('statusCode' in content) {
+        const statusCode = content.statusCode;
+        if (typeof statusCode === 'number' && statusCode >= 500) {
+            return true;
+        }
+    }
+    if ('level' in content) {
+        const level = content.level;
+        if (typeof level === 'string' && ERROR_LOG_LEVELS.has(level)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolves the keep-rate for a sampling entry. Discriminated purely by `typeof`
+ * — a number is a bare rate, an object is a {@link SamplingRule}.
+ */
+function ruleRate(rule) {
+    return typeof rule === 'number' ? rule : rule.rate;
+}
+/**
+ * Projects a {@link SamplingConfig} down to bare per-type keep-rates for the
+ * meta/dashboard contract, which only surfaces the headline rate.
+ */
+export function samplingRates(sampling) {
+    const rates = {};
+    for (const [type, rule] of Object.entries(sampling)) {
+        rates[type] = ruleRate(rule);
+    }
+    return rates;
+}
+/**
+ * Tail-sampling decision for one input. Plain-number per-type config behaves
+ * exactly as a uniform keep-rate. A {@link SamplingRule} additionally always
+ * keeps errors (`keepErrors`) and slow entries (`durationMs >= keepSlowMs`)
+ * before falling back to the base rate. `random` is the injected 0–1 source.
+ *
+ * Default-neutral: a type with no rule (and no `default`) is always kept, so an
+ * unset `sampling` config records everything exactly as before.
+ */
+export function passesSampling(sampling, input, random) {
+    const rule = sampling[input.type] ?? sampling.default;
+    if (rule === undefined) {
+        return true;
+    }
+    if (typeof rule === 'object') {
+        if (rule.keepErrors === true && isErrorEntry(input)) {
+            return true;
+        }
+        if (rule.keepSlowMs !== undefined &&
+            input.durationMs !== undefined &&
+            input.durationMs !== null &&
+            input.durationMs >= rule.keepSlowMs) {
+            return true;
+        }
+    }
+    const rate = ruleRate(rule);
+    if (rate >= 1) {
+        return true;
+    }
+    if (rate <= 0) {
+        return false;
+    }
+    return random() < rate;
+}
+/**
+ * Normalize the author-facing `sampling` option (a bare number → `{ default }`,
+ * or a {@link SamplingConfig} as-is, or `undefined` → `{}` meaning record
+ * everything) into a {@link SamplingConfig}.
+ */
+export function resolveSampling(sampling) {
+    if (sampling === undefined)
+        return {};
+    if (typeof sampling === 'number')
+        return { default: sampling };
+    return sampling;
+}
+//# sourceMappingURL=sampling.js.map

package/dist/src/sampling/sampling.js.map

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

package/dist/src/sampling/sampling_store.d.ts

@@ -0,0 +1,33 @@
+import type { Entry, RecordInput } from '../entry.js';
+import type { EntryQuery, TelescopeStore } from '../store.js';
+import { type SamplingConfig } from './sampling.js';
+/**
+ * A {@link TelescopeStore} decorator that applies tail-sampling on the WRITE
+ * path: a dropped entry is NEVER persisted (its `record()` short-circuits before
+ * delegating to the inner store). Wiring sampling at the store boundary — the one
+ * place every watcher records through — guarantees no watcher can bypass it.
+ *
+ * The decision is made by the pure {@link passesSampling} using only the shallow
+ * fields already on the {@link RecordInput} (no deep walk), so the hot path stays
+ * cheap. The RNG is injected so the decision is deterministic in tests.
+ *
+ * Default-neutral: with an empty {@link SamplingConfig} (the default when the
+ * host sets no `sampling` option) every entry passes, so behavior is unchanged.
+ *
+ * A DROPPED entry still resolves to a synthetic {@link Entry} (never persisted,
+ * `sequence: -1`) so the fire-and-forget `record()` contract — callers `void` the
+ * promise — is honoured without surfacing the drop as an error.
+ */
+export declare class SamplingTelescopeStore implements TelescopeStore {
+    private readonly inner;
+    private readonly sampling;
+    private readonly random;
+    constructor(inner: TelescopeStore, sampling: SamplingConfig, random?: () => number);
+    record<TContent>(input: RecordInput<TContent>): Promise<Entry<TContent>>;
+    get(id: string): Promise<Entry | null>;
+    list(query?: EntryQuery): Promise<Entry[]>;
+    count(): Promise<number>;
+    prune(olderThan: Date, keepLast?: number): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=sampling_store.d.ts.map

package/dist/src/sampling/sampling_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling_store.d.ts","sourceRoot":"","sources":["../../../src/sampling/sampling_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,KAAK,cAAc,EAAkB,MAAM,eAAe,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAEzD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,cAAc,EACxB,MAAM,GAAE,MAAM,MAAoB;IAG/C,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAO9E,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAItC,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAI1C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxB,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}

package/dist/src/sampling/sampling_store.js

@@ -0,0 +1,65 @@
+import { passesSampling } from './sampling.js';
+/**
+ * A {@link TelescopeStore} decorator that applies tail-sampling on the WRITE
+ * path: a dropped entry is NEVER persisted (its `record()` short-circuits before
+ * delegating to the inner store). Wiring sampling at the store boundary — the one
+ * place every watcher records through — guarantees no watcher can bypass it.
+ *
+ * The decision is made by the pure {@link passesSampling} using only the shallow
+ * fields already on the {@link RecordInput} (no deep walk), so the hot path stays
+ * cheap. The RNG is injected so the decision is deterministic in tests.
+ *
+ * Default-neutral: with an empty {@link SamplingConfig} (the default when the
+ * host sets no `sampling` option) every entry passes, so behavior is unchanged.
+ *
+ * A DROPPED entry still resolves to a synthetic {@link Entry} (never persisted,
+ * `sequence: -1`) so the fire-and-forget `record()` contract — callers `void` the
+ * promise — is honoured without surfacing the drop as an error.
+ */
+export class SamplingTelescopeStore {
+    inner;
+    sampling;
+    random;
+    constructor(inner, sampling, random = Math.random) {
+        this.inner = inner;
+        this.sampling = sampling;
+        this.random = random;
+    }
+    async record(input) {
+        if (!passesSampling(this.sampling, input, this.random)) {
+            return droppedEntry(input);
+        }
+        return this.inner.record(input);
+    }
+    get(id) {
+        return this.inner.get(id);
+    }
+    list(query) {
+        return this.inner.list(query);
+    }
+    count() {
+        return this.inner.count();
+    }
+    prune(olderThan, keepLast) {
+        return this.inner.prune(olderThan, keepLast);
+    }
+    clear() {
+        return this.inner.clear();
+    }
+}
+/** A non-persisted placeholder for a sampled-away entry (`sequence: -1`). */
+function droppedEntry(input) {
+    return {
+        id: '',
+        type: input.type,
+        familyHash: input.familyHash ?? null,
+        content: input.content,
+        tags: input.tags ?? [],
+        sequence: -1,
+        durationMs: input.durationMs ?? null,
+        origin: input.origin ?? 'manual',
+        traceId: input.traceId ?? null,
+        createdAt: new Date(),
+    };
+}
+//# sourceMappingURL=sampling_store.js.map

package/dist/src/sampling/sampling_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling_store.js","sourceRoot":"","sources":["../../../src/sampling/sampling_store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAuB,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAsB;IAEd;IACA;IACA;IAHnB,YACmB,KAAqB,EACrB,QAAwB,EACxB,SAAuB,IAAI,CAAC,MAAM;QAFlC,UAAK,GAAL,KAAK,CAAgB;QACrB,aAAQ,GAAR,QAAQ,CAAgB;QACxB,WAAM,GAAN,MAAM,CAA4B;IAClD,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAW,KAA4B;QACjD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,KAAkB;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAe,EAAE,QAAiB;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAW,KAA4B;IAC1D,OAAO;QACL,EAAE,EAAE,EAAE;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,QAAQ,EAAE,CAAC,CAAC;QACZ,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,QAAQ;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,SAAS,EAAE,IAAI,IAAI,EAAE;KACtB,CAAC;AACJ,CAAC"}

package/dist/src/stream/entry_events.d.ts

@@ -0,0 +1,45 @@
+import type { Entry } from '../entry.js';
+/**
+ * A subscriber notified of each newly-persisted {@link Entry}. Run synchronously
+ * from {@link EntryEvents.publish}; it must not throw (the emitter swallows it
+ * regardless) and should not block — the SSE route's subscriber just enqueues a
+ * frame.
+ */
+export type EntrySubscriber = (entry: Entry) => void;
+/**
+ * Unsubscribe handle returned by {@link EntryEvents.subscribe}. Idempotent: calling
+ * it twice is a no-op.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Process-local pub/sub of "an entry was just persisted". Fed from the store's
+ * write path (the {@link import('./streaming_store.js').StreamingTelescopeStore}
+ * decorator) AFTER redaction + sampling, so only entries that actually got stored
+ * — already scrubbed, never raw — are published. Consumed by the SSE stream route
+ * to push live entries to the dashboard.
+ *
+ * Port of the NestJS `EntryEvents` (an RxJS `Subject`), reshaped to a dependency-free
+ * synchronous emitter matching the Agora idiom (no RxJS). Stateless and best-effort:
+ * `publish` never throws into the flush path, and is a cheap no-op when there are no
+ * subscribers (`subscriberCount === 0`), so the hot write path pays nothing while the
+ * dashboard is closed.
+ */
+export declare class EntryEvents {
+    private readonly subscribers;
+    /**
+     * Register a subscriber and get back an idempotent unsubscribe handle. The SSE
+     * route subscribes on connect and unsubscribes on client disconnect.
+     */
+    subscribe(subscriber: EntrySubscriber): Unsubscribe;
+    /**
+     * Publish a freshly-persisted entry to every subscriber. Best-effort: a throwing
+     * subscriber is isolated (logged-free swallow) so observability can never break
+     * the flush path. A no-op when there are no subscribers.
+     */
+    publish(entry: Entry): void;
+    /** Number of active subscribers — `0` means `publish` is a cheap no-op. */
+    get subscriberCount(): number;
+    /** Drop every subscriber (called by the provider at shutdown). */
+    clear(): void;
+}
+//# sourceMappingURL=entry_events.d.ts.map

package/dist/src/stream/entry_events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry_events.d.ts","sourceRoot":"","sources":["../../../src/stream/entry_events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAE1D;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,eAAe,GAAG,WAAW;IAUnD;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAW3B,2EAA2E;IAC3E,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,kEAAkE;IAClE,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/stream/entry_events.js

@@ -0,0 +1,56 @@
+/**
+ * Process-local pub/sub of "an entry was just persisted". Fed from the store's
+ * write path (the {@link import('./streaming_store.js').StreamingTelescopeStore}
+ * decorator) AFTER redaction + sampling, so only entries that actually got stored
+ * — already scrubbed, never raw — are published. Consumed by the SSE stream route
+ * to push live entries to the dashboard.
+ *
+ * Port of the NestJS `EntryEvents` (an RxJS `Subject`), reshaped to a dependency-free
+ * synchronous emitter matching the Agora idiom (no RxJS). Stateless and best-effort:
+ * `publish` never throws into the flush path, and is a cheap no-op when there are no
+ * subscribers (`subscriberCount === 0`), so the hot write path pays nothing while the
+ * dashboard is closed.
+ */
+export class EntryEvents {
+    subscribers = new Set();
+    /**
+     * Register a subscriber and get back an idempotent unsubscribe handle. The SSE
+     * route subscribes on connect and unsubscribes on client disconnect.
+     */
+    subscribe(subscriber) {
+        this.subscribers.add(subscriber);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.subscribers.delete(subscriber);
+        };
+    }
+    /**
+     * Publish a freshly-persisted entry to every subscriber. Best-effort: a throwing
+     * subscriber is isolated (logged-free swallow) so observability can never break
+     * the flush path. A no-op when there are no subscribers.
+     */
+    publish(entry) {
+        if (this.subscribers.size === 0)
+            return;
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber(entry);
+            }
+            catch {
+                // observability must never break the flush
+            }
+        }
+    }
+    /** Number of active subscribers — `0` means `publish` is a cheap no-op. */
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+    /** Drop every subscriber (called by the provider at shutdown). */
+    clear() {
+        this.subscribers.clear();
+    }
+}
+//# sourceMappingURL=entry_events.js.map

package/dist/src/stream/entry_events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry_events.js","sourceRoot":"","sources":["../../../src/stream/entry_events.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,WAAW;IACL,WAAW,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE1D;;;OAGG;IACH,SAAS,CAAC,UAA2B;QACnC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,MAAM,GAAG,IAAI,CAAC;QAClB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,GAAG,KAAK,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAY;QAClB,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACxC,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,UAAU,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED,kEAAkE;IAClE,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/src/stream/index.d.ts

@@ -0,0 +1,6 @@
+export { EntryEvents } from './entry_events.js';
+export type { EntrySubscriber, Unsubscribe } from './entry_events.js';
+export { StreamingTelescopeStore } from './streaming_store.js';
+export { DEFAULT_HEARTBEAT_MS, streamEntries, } from './stream_handler.js';
+export type { StreamOptions, StreamSession } from './stream_handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/stream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stream/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACL,oBAAoB,EACpB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}