@senpi/runtime 3.0.108 → 3.0.111

package/dist/telemetry/strategy-topology.js

@@ -0,0 +1,93 @@
+/**
+ * Builder for the `plugin.senpi.strategies` payload — the topology view of the live telemetry
+ * stream: which strategies exist, whether each is up, how healthy it is, and which scanners it
+ * declares.
+ *
+ * Pure. Every fact arrives as an input, nothing is read from the registry or a runtime handle here,
+ * so the shape on the wire is testable without booting a runtime.
+ *
+ * Two properties this module exists to hold:
+ * - `status` distinguishes a runtime that is down from one that is up but has no live entry
+ *   scanners. The second reads as healthy unless it is named, and it is not.
+ * - The raw scanner `config` never reaches the wire. It is an unbounded passthrough record and it
+ *   has been through `resolveEnvInObject`, so it may hold resolved secrets. Only the declared,
+ *   typed fields below are copied, each by name.
+ */
+import { createLogger } from "../utils/logger.js";
+import { normalizeStrategyAddress } from "./event-store.js";
+const logger = createLogger("[senpi-core][strategy-topology]");
+/** Payload schema version. Bump when a field changes meaning, not when one is added. */
+export const STRATEGY_TOPOLOGY_VERSION = 1;
+/**
+ * Mirrors the three-way distinction `senpi.listRuntimes` draws: no handle is stopped, a handle in
+ * the unwired set is running blind, anything else is running. The wire carries the machine token —
+ * the operator-facing string is the frontend's to choose.
+ */
+function resolveStatus(runtimeId, running, unwired) {
+    if (!running.has(runtimeId))
+        return "stopped";
+    return unwired.has(runtimeId) ? "running_no_entry_scanners" : "running";
+}
+/** Health is advisory here: a lookup that fails must degrade the row, never the payload. */
+function resolveHealth(runtimeId, readHealth) {
+    let status;
+    try {
+        status = readHealth?.(runtimeId);
+    }
+    catch (err) {
+        logger.warn("strategy topology could not read runtime health; reporting unknown", err, {
+            runtimeId,
+        });
+        return { health: "unknown", startedAt: null };
+    }
+    if (!status)
+        return { health: "unknown", startedAt: null };
+    const parsed = status.startedAt === undefined ? NaN : Date.parse(status.startedAt);
+    return {
+        health: status.health,
+        startedAt: Number.isFinite(parsed) ? parsed : null,
+    };
+}
+/**
+ * Copies the declared scanner fields one by one. Never spread `entry` and never copy `config` —
+ * see the module note.
+ */
+function buildScanner(source) {
+    const { entry, registration } = source;
+    const declaredSchema = entry.signal_data_schema;
+    return {
+        scannerId: entry.name,
+        scheduleMode: registration?.scheduleMode ?? (entry.type === "external_scanner" ? "external" : "interval"),
+        enabled: registration?.enabled ?? true,
+        intervalSeconds: registration?.intervalSeconds ?? entry.interval_seconds ?? null,
+        configVersion: registration?.configVersion ?? null,
+        signalDataSchema: declaredSchema ?? null,
+    };
+}
+/** Builds one `plugin.senpi.strategies` payload from an already-gathered set of facts. */
+export function buildStrategyTopology(input) {
+    const now = input.now ?? Date.now;
+    const strategies = input.strategies.map((source) => {
+        const { health, startedAt } = resolveHealth(source.runtimeId, input.readHealth);
+        return {
+            runtimeId: source.runtimeId,
+            // `(address, scannerId)` is the join key across all four payloads, and the other three
+            // normalize their own address input. A checksummed EIP-55 wallet reaching the wire raw would
+            // spell this strategy differently from its own scanner rows and timeline rows, and nothing
+            // downstream rejects that — the join just returns nothing.
+            address: normalizeStrategyAddress(source.address),
+            name: source.name,
+            status: resolveStatus(source.runtimeId, input.runningRuntimeIds, input.unwiredRuntimeIds),
+            health,
+            startedAt,
+            scanners: source.scanners.map(buildScanner),
+        };
+    });
+    return {
+        v: STRATEGY_TOPOLOGY_VERSION,
+        epoch: input.epoch,
+        generatedAt: now(),
+        strategies,
+    };
+}
+//# sourceMappingURL=strategy-topology.js.map

package/dist/telemetry/strategy-topology.js.map

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

package/dist/telemetry/telemetry-publisher.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The producer tap for the live telemetry stream: a second {@link EventSink} that copies selected
+ * `logger.event` records into the in-memory {@link TimelineBuffer} while the on-disk ring keeps
+ * receiving every one of them. It sits on the serial trading path, so it resolves the scanner id,
+ * picks a fixed set of fields, appends, and returns — no I/O, no await, no counting, no serialization.
+ *
+ * Two lists govern the stream, and this module owns only the first:
+ * - ADMISSION ({@link ADMITTED_EVENT_NAMES}) — what enters the buffer. Every name the timeline
+ *   displays PLUS every name a counter is derived from, because a counting source that never enters
+ *   the buffer makes the stats read zero with nothing logged anywhere.
+ * - PUBLICATION — what leaves on the timeline event. Applied at flush time, not here. Admission is
+ *   deliberately the wider of the two: filtering for display at append time is unrecoverable.
+ */
+import { type EventName } from "../utils/event-catalog.js";
+import { type EventSink } from "./event-store.js";
+import { type TimelineBuffer } from "./timeline-buffer.js";
+/**
+ * The names that may enter the buffer. Volume control for a bounded ring, so it is an allow-list of
+ * the strategy's own narrative: what its scanners did, what each signal became, what was traded, and
+ * why the strategy's status changed. It excludes the box-operations and agent-plane families —
+ * `auto_update.*`, `tool.*`, `tool_approval.*`, the installer and state/mcp faults — and the
+ * mechanical, poll-frequency records (`dsl.sl_updated`, `dsl.close_pending`, `dsl.close_attempt`,
+ * `dsl.price_fetch_stale`), which would evict a strategy's recent window without adding a line
+ * anyone reads.
+ *
+ * Typed as `EventName`, so renaming a catalog entry out from under this list is a compile error
+ * rather than a silently empty counter.
+ */
+export declare const ADMITTED_EVENT_NAMES: ReadonlySet<EventName>;
+/**
+ * What the tap cost, in nanoseconds, since the last read. Two plain numbers and a maximum — no span,
+ * no histogram, no allocation: a span per event is exactly the blocking cost the buffer exists to
+ * avoid, and this sits on the same serial trading path the records describe.
+ */
+export interface TapCounters {
+    /** Tap invocations, admitted or not: the admission check is cost the trading path already paid. */
+    calls: number;
+    nsTotal: number;
+    /** The longest single call. An average hides the one append that had to evict. */
+    nsMax: number;
+}
+/**
+ * Take the window and zero it. The reader owns the window: a counter that is never reset reports a
+ * lifetime total forever, which sizes nothing. Process-wide, like the buffer the tap feeds.
+ */
+export declare function readAndResetTapCounters(): TapCounters;
+export interface TelemetryPublisherOptions {
+    /** Buffer to feed. Defaults to the process buffer — one per process, shared by every address. */
+    buffer?: TimelineBuffer;
+}
+/**
+ * A sink that copies admitted records into the timeline buffer under `address`. One instance per
+ * registered address; every instance writes into the same process buffer, which is what makes the
+ * publisher process-wide and address-partitioned rather than per-runtime.
+ */
+export declare function createTelemetryPublisherSink(address: string, options?: TelemetryPublisherOptions): EventSink;
+/**
+ * One sink that feeds several. `registerEventSink` keys a single sink per address, so this is how
+ * the publisher rides alongside the on-disk ring instead of replacing it. Each branch already
+ * swallows its own failures; the loop keeps one branch's throw from starving the rest regardless.
+ */
+export declare function createFanOutEventSink(sinks: readonly EventSink[]): EventSink;
+//# sourceMappingURL=telemetry-publisher.d.ts.map

package/dist/telemetry/telemetry-publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-publisher.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry-publisher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEvF,OAAO,EAA4B,KAAK,SAAS,EAAoB,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAS9E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,SAAS,CAqDtD,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,WAAW,CAMrD;AASD,MAAM,WAAW,yBAAyB;IACxC,iGAAiG;IACjG,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAqCD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,SAAS,CAkDX;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAuB5E"}

package/dist/telemetry/telemetry-publisher.js

@@ -0,0 +1,229 @@
+/**
+ * The producer tap for the live telemetry stream: a second {@link EventSink} that copies selected
+ * `logger.event` records into the in-memory {@link TimelineBuffer} while the on-disk ring keeps
+ * receiving every one of them. It sits on the serial trading path, so it resolves the scanner id,
+ * picks a fixed set of fields, appends, and returns — no I/O, no await, no counting, no serialization.
+ *
+ * Two lists govern the stream, and this module owns only the first:
+ * - ADMISSION ({@link ADMITTED_EVENT_NAMES}) — what enters the buffer. Every name the timeline
+ *   displays PLUS every name a counter is derived from, because a counting source that never enters
+ *   the buffer makes the stats read zero with nothing logged anywhere.
+ * - PUBLICATION — what leaves on the timeline event. Applied at flush time, not here. Admission is
+ *   deliberately the wider of the two: filtering for display at append time is unrecoverable.
+ */
+import { EVENT_NAME } from "../utils/event-catalog.js";
+import { createLogger } from "../utils/logger.js";
+import { normalizeStrategyAddress } from "./event-store.js";
+import { getTimelineBuffer } from "./timeline-buffer.js";
+const logger = createLogger("[senpi-core][telemetry-publisher]");
+/** The scanner's STABLE id. Carried by every event whose `senpi.scanner.id` is ephemeral. */
+const SCANNER_NAME_ATTR = "senpi.scanner.name";
+/** Stable on `signal.outcome` and `scanner.summary`; the ephemeral per-launch id everywhere else. */
+const SCANNER_ID_ATTR = "senpi.scanner.id";
+/**
+ * The names that may enter the buffer. Volume control for a bounded ring, so it is an allow-list of
+ * the strategy's own narrative: what its scanners did, what each signal became, what was traded, and
+ * why the strategy's status changed. It excludes the box-operations and agent-plane families —
+ * `auto_update.*`, `tool.*`, `tool_approval.*`, the installer and state/mcp faults — and the
+ * mechanical, poll-frequency records (`dsl.sl_updated`, `dsl.close_pending`, `dsl.close_attempt`,
+ * `dsl.price_fetch_stale`), which would evict a strategy's recent window without adding a line
+ * anyone reads.
+ *
+ * Typed as `EventName`, so renaming a catalog entry out from under this list is a compile error
+ * rather than a silently empty counter.
+ */
+export const ADMITTED_EVENT_NAMES = new Set([
+    // Counting sources. `opens` and `skips` come from `signal.outcome`, `errors` from the two
+    // `scaffold.tick_*` names. These four are load-bearing, not display-driven.
+    EVENT_NAME.signalOutcome,
+    EVENT_NAME.decisionMade,
+    EVENT_NAME.scaffoldTickError,
+    EVENT_NAME.scaffoldTickTimeout,
+    // Scanner run and health: the per-run heartbeat plus every supervisor transition behind a
+    // scanner's health, degraded reason and restart count.
+    EVENT_NAME.scannerSummary,
+    EVENT_NAME.scannerSpawned,
+    EVENT_NAME.scannerExited,
+    EVENT_NAME.scannerRestarted,
+    EVENT_NAME.scannerDegraded,
+    EVENT_NAME.scannerRecovered,
+    EVENT_NAME.scannerSilenceKilled,
+    EVENT_NAME.scannerLaunchFailed,
+    // Signal intake: what arrived and what was dropped before an action ever evaluated it.
+    EVENT_NAME.signalAccepted,
+    EVENT_NAME.signalRejected,
+    EVENT_NAME.signalExpired,
+    EVENT_NAME.signalSuperseded,
+    // Execution: the order and position story behind an accepted signal.
+    EVENT_NAME.orderPlaced,
+    EVENT_NAME.orderFilled,
+    EVENT_NAME.orderFailed,
+    EVENT_NAME.positionOpened,
+    EVENT_NAME.positionClosed,
+    EVENT_NAME.positionIncreased,
+    EVENT_NAME.positionDecreased,
+    EVENT_NAME.positionFlipped,
+    EVENT_NAME.positionReconciled,
+    // Exit engine: the state changes of an armed exit, not its per-tick floor arithmetic.
+    EVENT_NAME.dslCreated,
+    EVENT_NAME.dslPhaseChanged,
+    EVENT_NAME.dslTierAdvanced,
+    EVENT_NAME.dslClosed,
+    EVENT_NAME.dslDeleted,
+    EVENT_NAME.dslSlSyncFailed,
+    EVENT_NAME.dslHandoffFailed,
+    // Strategy status, and the two faults that explain a strategy that is up but not trading.
+    EVENT_NAME.runtimeStarted,
+    EVENT_NAME.runtimeStopped,
+    EVENT_NAME.runtimePaused,
+    EVENT_NAME.runtimeResumed,
+    EVENT_NAME.runtimeError,
+    EVENT_NAME.runtimeQueueBackpressure,
+    EVENT_NAME.runtimeScannersUnwired,
+]);
+let tapCalls = 0;
+let tapNsTotal = 0;
+let tapNsMax = 0;
+/**
+ * Take the window and zero it. The reader owns the window: a counter that is never reset reports a
+ * lifetime total forever, which sizes nothing. Process-wide, like the buffer the tap feeds.
+ */
+export function readAndResetTapCounters() {
+    const window = { calls: tapCalls, nsTotal: tapNsTotal, nsMax: tapNsMax };
+    tapCalls = 0;
+    tapNsTotal = 0;
+    tapNsMax = 0;
+    return window;
+}
+function noteTapCall(startedAt) {
+    const ns = Number(process.hrtime.bigint() - startedAt);
+    tapCalls += 1;
+    tapNsTotal += ns;
+    if (ns > tapNsMax)
+        tapNsMax = ns;
+}
+/**
+ * The scanner this record belongs to. The name attribute wins: `senpi.scanner.id` carries a
+ * per-launch id on the intake, scaffold and supervisor events, so reading it unqualified files one
+ * scanner under a new key on every external-scanner restart. Absent — never empty — when the record
+ * has no scanner at all; the record is still buffered and the client buckets it as unattributed.
+ */
+function resolveScannerId(attrs) {
+    const name = attrs[SCANNER_NAME_ATTR];
+    if (typeof name === "string" && name !== "")
+        return name;
+    const id = attrs[SCANNER_ID_ATTR];
+    return typeof id === "string" && id !== "" ? id : undefined;
+}
+function isScalar(value) {
+    const t = typeof value;
+    return t === "string" || t === "number" || t === "boolean";
+}
+/**
+ * The bag minus any non-scalar value. Unlike the disk ring — which serializes and forgets — the
+ * buffer holds this reference for the whole retention window and then puts it on the wire, so a
+ * nested object would pin an arbitrary graph in memory and break the payload's scalar contract.
+ * The common case allocates nothing: a copy is made only once a bad value is actually seen.
+ */
+function scalarAttrs(attrs, onDropped) {
+    let clean = attrs;
+    for (const key of Object.keys(attrs)) {
+        if (isScalar(attrs[key]))
+            continue;
+        if (clean === attrs)
+            clean = { ...attrs };
+        delete clean[key];
+        onDropped();
+    }
+    return clean;
+}
+/**
+ * A sink that copies admitted records into the timeline buffer under `address`. One instance per
+ * registered address; every instance writes into the same process buffer, which is what makes the
+ * publisher process-wide and address-partitioned rather than per-runtime.
+ */
+export function createTelemetryPublisherSink(address, options = {}) {
+    const bufferAddress = normalizeStrategyAddress(address);
+    // Reset on a later success so a transient failure can warn again if it recurs, but a persistently
+    // wedged buffer cannot spam a per-event warn on the trading path.
+    let warnedAppendFailure = false;
+    let warnedNonScalarAttr = false;
+    function noteNonScalarAttr(name) {
+        if (warnedNonScalarAttr)
+            return;
+        warnedNonScalarAttr = true;
+        logger.warn("telemetry publisher dropped a non-scalar event attribute", {
+            "senpi.event.name": name,
+        });
+    }
+    return {
+        append(event) {
+            // Measured in a `finally` so the rejected and the failed paths count too: they are the cheapest
+            // and the most expensive calls the trading path makes, and an average of neither is honest.
+            const startedAt = process.hrtime.bigint();
+            try {
+                if (!ADMITTED_EVENT_NAMES.has(event.name))
+                    return;
+                const attrs = event.attrs ?? {};
+                // Named fields only: whatever else rides the record — a redact slot, resource attributes —
+                // is not copied because it is never read.
+                (options.buffer ?? getTimelineBuffer()).append({
+                    ts: event.ts,
+                    name: event.name,
+                    level: event.level,
+                    address: bufferAddress,
+                    scannerId: resolveScannerId(attrs),
+                    body: event.body,
+                    attrs: scalarAttrs(attrs, () => noteNonScalarAttr(event.name)),
+                });
+                warnedAppendFailure = false;
+            }
+            catch (err) {
+                // The tap must never disturb the logging caller, and a wedged tap must not be silent.
+                if (!warnedAppendFailure) {
+                    warnedAppendFailure = true;
+                    logger.warn("telemetry publisher append failed; the live stream may be incomplete", {
+                        address: bufferAddress,
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            finally {
+                noteTapCall(startedAt);
+            }
+        },
+        flush: () => Promise.resolve(),
+    };
+}
+/**
+ * One sink that feeds several. `registerEventSink` keys a single sink per address, so this is how
+ * the publisher rides alongside the on-disk ring instead of replacing it. Each branch already
+ * swallows its own failures; the loop keeps one branch's throw from starving the rest regardless.
+ */
+export function createFanOutEventSink(sinks) {
+    return {
+        append(event) {
+            for (const sink of sinks) {
+                try {
+                    sink.append(event);
+                }
+                catch {
+                    // A branch that breaks its own no-throw contract must not cost the others their record.
+                }
+            }
+        },
+        async flush() {
+            // Sequential and individually guarded: a graceful stop awaits this, so one branch's rejection
+            // must not skip another's drain or surface as a failed stop.
+            for (const sink of sinks) {
+                try {
+                    await sink.flush();
+                }
+                catch {
+                    // A branch that cannot drain has already reported it; the stop path carries on.
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=telemetry-publisher.js.map

package/dist/telemetry/telemetry-publisher.js.map

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

package/dist/telemetry/timeline-buffer.d.ts

@@ -0,0 +1,95 @@
+/**
+ * In-memory recent-window buffer for the live telemetry stream: the records a client replays on
+ * subscribe and the records the stats view is computed from. One buffer per process, partitioned by
+ * strategy address — the same shape as the disk ring's process-global sink map, because the tap that
+ * feeds it (`appendDomainEvent`) is process-global too.
+ *
+ * Three things make a client's state recoverable across a reconnect:
+ * - `epoch`, a ULID minted when the buffer is created. A change means the plugin restarted, not that
+ *   frames were lost.
+ * - `seq`, monotonic per epoch across every address, so `(epoch, seq)` is a dedupe and resume key and
+ *   a single `afterSeq` cursor is unambiguous. It never rewinds while the epoch holds — not on
+ *   teardown, not on eviction.
+ * - {@link TimelineBuffer.oldestTs}, the stamp of the oldest record still held. A client whose cursor
+ *   predates it knows it has a gap that no replay can fill.
+ *
+ * The write path is on the serial trading path: it takes one bounded slot write and returns. It does
+ * no I/O, awaits nothing, computes nothing, and never throws.
+ */
+import type { AttrValue } from "../utils/event-catalog.js";
+import { type LogLevel } from "../utils/logger.js";
+/**
+ * Records held per address before the oldest is overwritten. The bound is a record COUNT, per
+ * address: a fixed-size ring makes eviction a single slot write (no scan, no shift) and makes the
+ * oldest stamp an O(1) read, both of which a byte or age bound would cost the write path. Per address
+ * rather than process-wide so one chatty strategy cannot evict a quiet one's window.
+ *
+ * This is the number to change when the retention window is measured — see also the
+ * `maxRecordsPerAddress` option, which overrides it per buffer.
+ */
+export declare const DEFAULT_MAX_RECORDS_PER_ADDRESS = 2000;
+/** The seq of the first record of an epoch. Records start at 1, so `afterSeq: 0` means "everything". */
+export declare const FIRST_SEQ = 1;
+/** One record as the tap hands it over, before the buffer stamps a seq. */
+export interface TimelineRecordInput {
+    /** Call-time epoch ms, stamped by `logger.event`. */
+    ts: number;
+    name: string;
+    level: LogLevel;
+    address: string;
+    /** The engine scanner id. Absent — never empty — on a record that has no scanner. */
+    scannerId?: string;
+    body: string;
+    attrs: Record<string, AttrValue>;
+}
+/** A buffered record: the tap's input plus its position in the epoch. */
+export interface TimelineRecord extends TimelineRecordInput {
+    seq: number;
+}
+/** Filters for {@link TimelineBuffer.read}; all optional, all combinable. Time bounds are inclusive. */
+export interface TimelineQuery {
+    /** Exclusive lower bound on seq — the client's resume cursor. */
+    afterSeq?: number;
+    address?: string;
+    scannerId?: string;
+    sinceMs?: number;
+    untilMs?: number;
+    /** Keep the last N after filtering (newest tail). */
+    limit?: number;
+}
+export interface TimelineBufferOptions {
+    /** Overrides {@link DEFAULT_MAX_RECORDS_PER_ADDRESS}. Clamped to at least one record. */
+    maxRecordsPerAddress?: number;
+}
+export interface TimelineBuffer {
+    /** ULID minted with this buffer. Rides every published payload. */
+    readonly epoch: string;
+    /** Copy one record in and return. Never blocks, never throws. */
+    append(input: TimelineRecordInput): void;
+    /** Records matching `query`, oldest first. */
+    read(query?: TimelineQuery): TimelineRecord[];
+    /** Stamp of the oldest record still held across every address; undefined when nothing is held. */
+    oldestTs(): number | undefined;
+    /**
+     * The largest seq this buffer has thrown away, or zero when it has thrown away nothing. A client
+     * resuming from a cursor BELOW this lost at least one record; a cursor at or above it lost none.
+     *
+     * It is not the oldest seq still held. The rings are per address, so a quiet strategy keeps a low
+     * seq alive long after a chatty one has evicted everything above it, and the oldest record held
+     * then says nothing about what a resuming client is missing.
+     */
+    highestDroppedSeq(): number;
+    /** Records appended since the last drain, oldest first. Reads the publish frontier — does not evict. */
+    drain(): TimelineRecord[];
+    /** Drop every record. The seq counter is deliberately not rewound. */
+    teardown(): void;
+}
+export declare function createTimelineBuffer(options?: TimelineBufferOptions): TimelineBuffer;
+/** The process's telemetry buffer, minted (with its epoch) on first use. */
+export declare function getTimelineBuffer(): TimelineBuffer;
+/**
+ * Drop the process buffer on plugin reload or shutdown. The next {@link getTimelineBuffer} mints a
+ * fresh epoch, so the restarted seq run cannot collide with the one a client already holds.
+ */
+export declare function teardownTimelineBuffer(): void;
+//# sourceMappingURL=timeline-buffer.d.ts.map

package/dist/telemetry/timeline-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-buffer.d.ts","sourceRoot":"","sources":["../../src/telemetry/timeline-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAKjE;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,wGAAwG;AACxG,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClC;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wGAAwG;AACxG,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,yFAAyF;IACzF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzC,8CAA8C;IAC9C,IAAI,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,cAAc,EAAE,CAAC;IAC9C,kGAAkG;IAClG,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;;;;OAOG;IACH,iBAAiB,IAAI,MAAM,CAAC;IAC5B,wGAAwG;IACxG,KAAK,IAAI,cAAc,EAAE,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,IAAI,IAAI,CAAC;CAClB;AAkDD,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CA8IxF;AAMD,4EAA4E;AAC5E,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}