@senpi/runtime 3.0.103 → 3.0.107

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

@@ -1,158 +0,0 @@
-/**
- * The publisher: the piece that turns the buffer and the three builders into frames on the gateway
- * websocket, plus the snapshot a client reads when it connects.
- *
- * Two things about the transport shape the whole module:
- * - The only route to the websocket is a captured `context.broadcast`, and `context` exists only
- *   inside a gateway RPC handler — the plugin api object has no push surface at all. So the handle is
- *   captured from the FIRST request of ANY kind, not only from the subscribe method: a box whose
- *   client never calls subscribe would otherwise hold nothing to publish through, silently.
- * - The gateway drops any event name that does not start with `plugin.`, and closes the socket with
- *   1008 for a slow client unless the call passes `dropIfSlow`. Both are enforced here rather than at
- *   each call site, because either mistake is invisible until a client is missing frames.
- *
- * Three cadences, because the three payloads cost different things to build:
- * - timeline, on the flush tick — a drain plus a filter, cheap, and the one a live screen feels.
- * - stats, on the sample tick — a scan of the whole held window and an async read of every runtime's
- *   health and system state, so it runs an order of magnitude less often.
- * - topology, on the sample tick but published only when it changes — it rides the same gather as
- *   stats, and nothing in the plugin signals a topology change, so "on change" means polled and
- *   diffed rather than pushed.
- *
- * The snapshot is what stops a client that joins mid-life from seeing an empty screen: it is read
- * from the buffer's held window, which the flush drain never evicts.
- *
- * Everything that leaves the box is scrubbed here. `logger.event` redacts its `redact` slot and not
- * its `attributes`, which is sound for the disk ring — that never leaves — but not for a stream a
- * browser reads. Both outbound paths funnel through {@link toWireRecord}, so that is where the
- * scrub sits; it is what makes the flush tick asynchronous and gives it an in-flight guard.
- */
-import type { EventName } from "../utils/event-catalog.js";
-import { type TimelineBuffer } from "./timeline-buffer.js";
-import { type ScannerStateSnapshot, type ScannerStatsPayload } from "./scanner-stats.js";
-import { type IdMembership, type RuntimeHealthLike, type StrategyTopologyPayload, type TopologyStrategySource } from "./strategy-topology.js";
-/** The gateway drops any broadcast whose name does not carry this prefix, with no error. */
-export declare const EVENT_TIMELINE = "plugin.senpi.timeline";
-export declare const EVENT_STATS = "plugin.senpi.scanner.stats";
-export declare const EVENT_TOPOLOGY = "plugin.senpi.strategies";
-/**
- * Byte ceiling for one frame. The bridge's north read limit is 256 KiB and a breach closes the
- * client socket with 1009, so the budget is set at half of it: the payload envelope the gateway wraps
- * around ours, and the growth of a single record's attribute bag, both have to fit inside the margin.
- */
-export declare const MAX_FRAME_BYTES: number;
-/** Flush cadence for the timeline. A live screen feels this number. */
-export declare const DEFAULT_FLUSH_INTERVAL_MS = 1000;
-/**
- * Sample cadence for stats and topology. Both are built from one async read of every runtime's health
- * and system state, so they share a tick. Five seconds is roughly a third of the default bucket width
- * — fast enough that a counter visibly moves and a hung scan is seen while it is still running, slow
- * enough that the per-scanner store read behind the system state is not a poll loop.
- */
-export declare const DEFAULT_SAMPLE_INTERVAL_MS = 5000;
-/**
- * The PUBLICATION list: what leaves on the timeline event. A name being on this list AND on the
- * admission list is the normal case, not a duplication — `signal.outcome` is the decision row the feed
- * is built around and the source of `opens`/`closes`/`skips`, and the two `scaffold.tick_*` names are
- * the source of `errors` and the rows behind the Errors filter. A failing external scanner has to
- * leave a visible line, not only a number that silently goes up.
- *
- * The two lists are separate so admission can be widened for a counter the feed does not display,
- * which is the direction that has to stay open: the display filter belongs here at publish time,
- * where it is still recoverable, never at append time, where it is not. Today nothing is admitted for
- * counting alone, so the sets are equal — the seam is what matters, not the difference.
- */
-export declare const PUBLISHED_EVENT_NAMES: ReadonlySet<EventName>;
-/**
- * The share of its own interval a tick may take before it is warned about. A fraction rather than a
- * constant, so a deployment that changes a cadence gets a proportional threshold: 250ms on the
- * one-second timeline flush, 1.25s on the five-second sample.
- *
- * A quarter, not a whole interval. Both ticks share an event loop with the serial trading path, so a
- * tick holding it for a quarter of its own period is already adding latency to trading; and a tick
- * that fills its interval has already started stacking on the next one, which is too late to be told.
- */
-export declare const SLOW_TICK_FRACTION = 0.25;
-/**
- * How often the timing summary is logged, and the floor between two slow-tick warns of the same kind.
- * The flush tick runs every second, so a line per tick would be tens of thousands a day for numbers
- * that only mean anything aggregated — and a repeating tick that is slow is slow every time.
- */
-export declare const TIMING_REPORT_INTERVAL_MS = 60000;
-export interface GatewayBroadcastOpts {
-    dropIfSlow?: boolean;
-    stateVersion?: number;
-}
-export type GatewayBroadcastFn = (event: string, payload: unknown, opts?: GatewayBroadcastOpts) => void;
-/** One record as it goes on the wire. */
-export interface TimelineWireRecord {
-    seq: number;
-    ts: number;
-    name: string;
-    level: string;
-    address: string;
-    scannerId?: string;
-    body: string;
-    attrs: Record<string, string | number | boolean>;
-}
-export interface TimelinePayload {
-    v: 1;
-    epoch: string;
-    batchSeq: number;
-    records: TimelineWireRecord[];
-}
-export interface TelemetrySnapshot {
-    epoch: string;
-    topology: StrategyTopologyPayload;
-    stats: ScannerStatsPayload;
-    recent: TimelinePayload;
-    /**
-     * The client asked to resume from a cursor inside THIS epoch whose successor is no longer held, or
-     * the window it is owed did not fit one frame. Either way there is a gap this response cannot fill,
-     * and only the box knows it: `recent.records` alone looks like a normal short window.
-     *
-     * A cursor from another epoch is not truncation. It buys nothing, so the whole retained window is
-     * served — which is the most this box could ever serve, and so nothing was withheld.
-     */
-    truncated: boolean;
-}
-/** Everything the two builders need that the buffer cannot supply, gathered once per tick. */
-export interface TelemetryFacts {
-    strategies: TopologyStrategySource[];
-    runningRuntimeIds: IdMembership;
-    unwiredRuntimeIds: IdMembership;
-    readHealth?: (runtimeId: string) => RuntimeHealthLike | undefined;
-    scannerState: ScannerStateSnapshot[];
-}
-export interface LiveTelemetryOptions {
-    /** Defaults to the process buffer — one per process, shared by every address. */
-    buffer?: TimelineBuffer;
-    collectFacts: () => Promise<TelemetryFacts>;
-    flushIntervalMs?: number;
-    sampleIntervalMs?: number;
-    now?: () => number;
-    /**
-     * Monotonic millisecond reader for tick durations. Defaults to `performance.now`; `now` is wall
-     * clock and can step backwards under NTP, which would report a negative tick.
-     */
-    monotonicMs?: () => number;
-}
-export interface LiveTelemetry {
-    readonly epoch: string;
-    /** Take the broadcast handle off a gateway request context if we do not hold one yet. */
-    captureBroadcast(ctx: unknown, methodName: string): void;
-    /** `afterSeq` counts only when `afterEpoch` is the epoch this box is running. */
-    snapshot(params?: {
-        afterEpoch?: unknown;
-        afterSeq?: unknown;
-    }): Promise<TelemetrySnapshot>;
-    /** One flush tick: drain, filter to the publication list, scrub, frame, broadcast. */
-    flushTimeline(): Promise<void>;
-    /** One sample tick: stats always, topology when it changed. */
-    sample(): Promise<void>;
-    start(): void;
-    /** Clear both timers, drop the captured handle, and empty the buffer. */
-    stop(): void;
-}
-export declare function createLiveTelemetry(options: LiveTelemetryOptions): LiveTelemetry;
-//# sourceMappingURL=live-telemetry.d.ts.map

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

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