@senpi/runtime 3.0.125 → 3.0.126

package/dist/telemetry/live-telemetry.js

@@ -1,853 +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.
- *
- * A fourth broadcast sits outside all of that. The tick frame is a LEVEL — the latest finished run of
- * each scanner, most of which produce nothing and so leave no record anywhere — and it is published
- * on a window of its own, driven by the runs themselves rather than by a timer that is always
- * running. It carries no seq, is never buffered, is not in the snapshot and is not replayed, because
- * a client that misses one is made whole by the next one. Keeping it off the buffer is the point: the
- * buffer is where decision records live, and per-tick facts would evict them.
- *
- * 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. There are four ways out — the timeline frame, the stats frame, the tick frame and
- * the snapshot that carries one of the first three — and two kinds of free text between them, so the
- * scrub sits in two places:
- * - {@link toWireRecord} for a timeline record's attributes. It is what makes the flush tick
- *   asynchronous and gives it an in-flight guard.
- * - {@link scrubScannerText} for text a scanner process authored: the scanner state's three
- *   free-text fields, via {@link scrubStatsPayload}, which reach both the stats frame and the
- *   snapshot; and a tick's `outcome`. Their content is a stringified throwable or status from a
- *   scanner process, so they are the strings on the wire with no bound of their own and they are
- *   capped as well as scrubbed.
- *
- * The topology payload carries no captured text: its `name` and `scannerId` are operator-authored
- * config keys the client joins on, and the scanner `config` that could hold a resolved secret is
- * never copied onto it.
- */
-import { createLogger } from "../utils/logger.js";
-import { withSpan } from "./tracing.js";
-import { getDefaultPiiRedactor } from "./spans/redact-pii.js";
-import { ADMITTED_EVENT_NAMES, readAndResetTapCounters } from "./telemetry-publisher.js";
-import { getTimelineBuffer, teardownTimelineBuffer, } from "./timeline-buffer.js";
-import { capValue } from "./attributes.js";
-import { setScannerTickSink } from "./scanner-tick-feed.js";
-import { createTickFrameBuilder, resolveTickTelemetry, } from "./tick-frame.js";
-import { normalizeStrategyAddress } from "./event-store.js";
-import { buildScannerStats, } from "./scanner-stats.js";
-import { buildStrategyTopology, } from "./strategy-topology.js";
-const logger = createLogger("[senpi-core][live-telemetry]");
-/** The gateway drops any broadcast whose name does not carry this prefix, with no error. */
-export const EVENT_TIMELINE = "plugin.senpi.timeline";
-export const EVENT_STATS = "plugin.senpi.scanner.stats";
-export const EVENT_TOPOLOGY = "plugin.senpi.strategies";
-export const EVENT_TICK = "plugin.senpi.tick";
-/**
- * Byte ceiling for one frame. A frame published here travels southbound — gateway to bridge — and
- * meets the bridge's southbound read limit, 1 MiB unless a deployment sets its own; a frame past it
- * takes the whole connection down rather than costing the one frame. The budget is set far inside
- * that: the payload envelope the gateway wraps around ours, and the growth of a single record's
- * attribute bag, both have to fit in the margin, and neither is measured here.
- */
-export const MAX_FRAME_BYTES = 128 * 1024;
-/**
- * Character ceiling for one of the scanner state's free-text fields on the wire — `lastRunReason`,
- * `lastRunStatus` and `degradedReason`.
- *
- * These carry a stringified throwable from a scanner process, which nothing upstream bounds: an HTTP
- * client's error message alone runs to a few hundred characters and a stack-bearing one to
- * kilobytes, once per scanner per sample. 1024 holds the sentence that says what failed — the error
- * type, the operation and the endpoint. It is also what keeps the payload bounded at all: this frame
- * is published whole, with no splitting of the kind the timeline does, so two hundred scanners each
- * reporting a 4 KiB error in every one of the three fields serialise to about 1.7 MB — past the read
- * limit that ends the connection — and at this cap the same box lands under half of it.
- */
-export const MAX_SCANNER_TEXT_CHARS = 1_024;
-/**
- * What one of those fields reads as when its text could not be scrubbed — no redactor registered, or
- * a redactor that threw.
- *
- * Not `null` and not an absent key: the producer reporting no reason and this box withholding one it
- * cannot vouch for are different facts, and a summary screen is read as if they were the same.
- */
-export const SCANNER_TEXT_WITHHELD = "[withheld: not scrubbed]";
-/** Flush cadence for the timeline. A live screen feels this number. */
-export const DEFAULT_FLUSH_INTERVAL_MS = 1_000;
-/**
- * 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 const DEFAULT_SAMPLE_INTERVAL_MS = 5_000;
-/**
- * How long the first tick of a frame waits for the ticks that land beside it.
- *
- * Scanners on a box share cadences — a recipe gives several of them the same interval, and every
- * runtime starts them within the same boot — so their terminal callbacks arrive in clumps. A frame per
- * callback would put one websocket write per scanner per cadence on the wire for a payload of seven
- * scalars; one window collapses a clump into a single write. It is short enough that the level a
- * dashboard shows is still the current one, and it is not the timeline's flush tick because a tick
- * frame must not wait behind a scrub of hundreds of records.
- */
-export const TICK_COALESCE_MS = 250;
-/** The comma JSON puts between two array entries. Counted, so the budget is the frame's real size. */
-const SEPARATOR_BYTES = 1;
-/**
- * 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 const PUBLISHED_EVENT_NAMES = new Set(ADMITTED_EVENT_NAMES);
-/**
- * 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 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 const TIMING_REPORT_INTERVAL_MS = 60_000;
-/** What the builders see when the facts could not be read: nothing, rather than a stale guess. */
-const NO_FACTS = {
-    strategies: [],
-    runningRuntimeIds: { has: () => false },
-    unwiredRuntimeIds: { has: () => false },
-    scannerState: [],
-};
-/**
- * Every string value in `attrs`, scrubbed. Numbers and booleans cannot carry PII and are copied as
- * they are, so a record whose attributes are all scalars allocates nothing and awaits nothing.
- *
- * A value the redactor could not produce is DROPPED, never passed through — `redactStringsDeep`
- * keeps the original on a throw because a span attribute is still inside the box, and this is not.
- * With no redactor at all every string value is dropped for the same reason.
- */
-async function scrubAttrs(attrs, redactor, onScrubFailure) {
-    let out;
-    for (const [key, value] of Object.entries(attrs)) {
-        // An empty string carries nothing, and the redactor charges for it like any other.
-        if (typeof value !== "string" || value === "")
-            continue;
-        out ??= { ...attrs };
-        if (redactor === null) {
-            delete out[key];
-            continue;
-        }
-        try {
-            out[key] = await redactor.redact(value);
-        }
-        catch (err) {
-            delete out[key];
-            onScrubFailure(err);
-        }
-    }
-    return out ?? attrs;
-}
-/**
- * The single point where a buffered record becomes something that goes outside, and so the only
- * place the scrub has to be.
- *
- * `body` is not scrubbed: it is built from the catalogued template and bounded by it, which is the
- * same reason `logger.event` never redacts it. Neither are the record's own string fields — `name`
- * is a closed-catalog entry, `address` is a normalised wallet address, `scannerId` is the engine's
- * id, `level` is a severity. They are machine identifiers the client groups and joins on, not free
- * text, and scrubbing one would break the join for no gain.
- */
-async function toWireRecord(record, redactor, onScrubFailure) {
-    return {
-        seq: record.seq,
-        ts: record.ts,
-        name: record.name,
-        level: record.level,
-        address: record.address,
-        ...(record.scannerId !== undefined ? { scannerId: record.scannerId } : {}),
-        body: record.body,
-        attrs: await scrubAttrs(record.attrs, redactor, onScrubFailure),
-    };
-}
-/**
- * One of the scanner state's free-text fields as it goes outside: scrubbed, then capped to
- * {@link MAX_SCANNER_TEXT_CHARS} with the marker `capValue` puts on every other capped value, so the
- * cut is visible to whoever reads it.
- *
- * The cap is taken AFTER the scrub and never before. A redaction can be longer than the text it
- * replaces — a placeholder carries a kind and a counter where the original carried a number — so a
- * cut taken first bounds the input and not what leaves.
- *
- * `null` passes through: a field the provider never filled is a different fact from one this box
- * withheld, and {@link SCANNER_TEXT_WITHHELD} is what says which of the two happened.
- */
-async function scrubScannerText(value, redactor, onScrubFailure) {
-    if (value === null || value === "")
-        return value;
-    if (redactor === null)
-        return SCANNER_TEXT_WITHHELD;
-    try {
-        return capValue(await redactor.redact(value), MAX_SCANNER_TEXT_CHARS);
-    }
-    catch (err) {
-        onScrubFailure(err);
-        return SCANNER_TEXT_WITHHELD;
-    }
-}
-/**
- * The stats payload as it goes outside, and so the only place the stats scrub has to be: both the
- * sample tick and the snapshot publish what this returns.
- *
- * Three fields per entry are touched. Everything else on one is a wallet address, a scanner id, a
- * health token, a timestamp or a counter — machine values the client joins and sums on, none of
- * which can carry what a scanner's error string carries. An entry holding none of the three is
- * passed through as it is, so a box of healthy scanners awaits nothing.
- */
-async function scrubStatsPayload(payload, redactor, onScrubFailure) {
-    let scrubbedAny = false;
-    const scanners = [];
-    for (const entry of payload.scanners) {
-        if (entry.degradedReason === null &&
-            entry.lastRunStatus === null &&
-            entry.lastRunReason === null) {
-            scanners.push(entry);
-            continue;
-        }
-        scrubbedAny = true;
-        scanners.push({
-            ...entry,
-            degradedReason: await scrubScannerText(entry.degradedReason, redactor, onScrubFailure),
-            lastRunStatus: await scrubScannerText(entry.lastRunStatus, redactor, onScrubFailure),
-            lastRunReason: await scrubScannerText(entry.lastRunReason, redactor, onScrubFailure),
-        });
-    }
-    return scrubbedAny ? { ...payload, scanners } : payload;
-}
-/** A cursor is a resume point, so anything that is not a whole non-negative number means "from the start". */
-function normalizeAfterSeq(raw) {
-    if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0)
-        return 0;
-    return Math.floor(raw);
-}
-/** Everything but `generatedAt`, which changes on every build and would make every topology "changed". */
-function topologySignature(payload) {
-    return JSON.stringify({ v: payload.v, strategies: payload.strategies });
-}
-/** Microsecond precision. A sub-millisecond tick is the interesting case; its 17th digit is not. */
-function roundMs(ms) {
-    return Math.round(ms * 1_000) / 1_000;
-}
-export function createLiveTelemetry(options) {
-    const ownsProcessBuffer = options.buffer === undefined;
-    // Resolved at every use, never captured. The event sink resolves it the same way on every
-    // append, and a plugin reload drops the process singleton — capturing it here once would leave
-    // the publisher draining a buffer nothing writes to any more, with no symptom but an empty feed.
-    const timelineBuffer = () => options.buffer ?? getTimelineBuffer();
-    const now = options.now ?? Date.now;
-    const monotonicMs = options.monotonicMs ?? (() => performance.now());
-    const flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
-    const sampleIntervalMs = options.sampleIntervalMs ?? DEFAULT_SAMPLE_INTERVAL_MS;
-    // When this epoch began watching: `since` falls back to it while the buffer holds nothing, so an
-    // empty window reads as "watching since X, nothing happened" rather than "no data".
-    const bufferStartedAt = now();
-    let broadcast;
-    let flushTimer;
-    let sampleTimer;
-    let sampleInFlight = false;
-    let flushInFlight = false;
-    let batchSeq = 0;
-    let lastTopologySignature;
-    // These guards sit on per-second paths, so each warns once until the condition clears.
-    let warnedNoBroadcast = false;
-    let warnedBroadcastFailure = false;
-    let warnedOversizedRecord = false;
-    let warnedNoRedactor = false;
-    let warnedScrubFailure = false;
-    let warnedFlushFailure = false;
-    let warnedTickFrameFull = false;
-    let warnedTickFlushFailure = false;
-    // The two detail dials, read once. `invalid` is warned about here rather than thrown, and once
-    // rather than per frame: the value is read at register time and does not change under us.
-    const { settings: tickSettings, invalid: invalidTickTelemetry } = resolveTickTelemetry(options.tickTelemetry);
-    if (invalidTickTelemetry !== undefined) {
-        logger.warn("live telemetry ignored an invalid tick telemetry setting and kept the default", {
-            "senpi.telemetry.tick_telemetry_invalid": invalidTickTelemetry,
-            "senpi.telemetry.tick_telemetry_mcp": tickSettings.mcp,
-            "senpi.telemetry.tick_telemetry_state": tickSettings.state,
-        });
-    }
-    // What a tick frame costs before it holds a single tick, used to admit into the OPEN window. The
-    // frame that goes out is measured again, on the scrubbed frame, by the builder — a redaction can
-    // be longer than the text it replaced, so this figure bounds memory and the builder bounds bytes.
-    const tickEnvelopeBytes = Buffer.byteLength(JSON.stringify({ v: 1, e: timelineBuffer().epoch, t0: 0, d: { a: [], s: [], m: [], o: [], x: [] }, k: [] }));
-    // The open coalescing window: the runs it holds, roughly what they would cost, and the timer that
-    // closes it. Nothing accumulates here on a box no client has ever reached.
-    let pendingTicks = [];
-    let pendingTickBytes = tickEnvelopeBytes;
-    let tickTimer;
-    // What the ticks cost over one report window. Bucket width and buffer retention are deliberately
-    // unfixed by the design, and these are the numbers they get sized from.
-    const timelineWindow = { ticks: 0, msMax: 0, records: 0, payloadBytes: 0 };
-    const statsWindow = { ticks: 0, msMax: 0, recordsScanned: 0, payloadBytesMax: 0 };
-    const tapWindow = { calls: 0, nsTotal: 0, nsMax: 0 };
-    let lastReportAt = bufferStartedAt;
-    const lastSlowWarnAt = { timeline: 0, stats: 0 };
-    /** True when the frame reached the gateway, so a caller counts bytes only for what went out. */
-    function publish(event, payload) {
-        if (broadcast === undefined) {
-            if (!warnedNoBroadcast) {
-                warnedNoBroadcast = true;
-                logger.warn("live telemetry has no gateway broadcast handle yet; nothing is published until a client calls any senpi gateway method", { "senpi.telemetry.event": event });
-            }
-            return false;
-        }
-        try {
-            // `dropIfSlow` is not optional: without it the gateway closes the socket with 1008 for a slow
-            // client instead of skipping the one frame it could not fit.
-            broadcast(event, payload, { dropIfSlow: true });
-            warnedBroadcastFailure = false;
-            return true;
-        }
-        catch (err) {
-            if (!warnedBroadcastFailure) {
-                warnedBroadcastFailure = true;
-                logger.warn("live telemetry broadcast failed; frames are being lost", {
-                    "senpi.telemetry.event": event,
-                    err: err instanceof Error ? err.message : String(err),
-                });
-            }
-            return false;
-        }
-    }
-    /** Record what a tick cost, and warn when it is eating its own interval. */
-    function noteTick(kind, elapsedMs, intervalMs) {
-        const window = kind === "timeline" ? timelineWindow : statsWindow;
-        window.ticks += 1;
-        if (elapsedMs > window.msMax)
-            window.msMax = elapsedMs;
-        const thresholdMs = intervalMs * SLOW_TICK_FRACTION;
-        if (elapsedMs <= thresholdMs)
-            return;
-        const at = now();
-        // A tick that is slow is slow every time, and these repeat on the order of seconds.
-        if (at - lastSlowWarnAt[kind] < TIMING_REPORT_INTERVAL_MS)
-            return;
-        lastSlowWarnAt[kind] = at;
-        logger.warn("live telemetry tick is slow relative to its own interval", {
-            "senpi.telemetry.tick": kind,
-            "senpi.telemetry.tick_ms": roundMs(elapsedMs),
-            "senpi.telemetry.tick_threshold_ms": thresholdMs,
-            "senpi.telemetry.tick_interval_ms": intervalMs,
-        });
-    }
-    /**
-     * One aggregated line per window, off the flush tick. Logged and not only traced: the OTel SDK
-     * stands up only when an OTLP endpoint is configured, so on a box with no collector there are no
-     * spans and nothing that says there are none.
-     */
-    function reportTiming() {
-        const at = now();
-        const windowMs = at - lastReportAt;
-        if (windowMs < TIMING_REPORT_INTERVAL_MS)
-            return;
-        lastReportAt = at;
-        logger.info("live telemetry tick timing", {
-            "senpi.telemetry.window_ms": windowMs,
-            "senpi.telemetry.timeline_ticks": timelineWindow.ticks,
-            "senpi.telemetry.timeline_ms_max": roundMs(timelineWindow.msMax),
-            "senpi.telemetry.records_flushed": timelineWindow.records,
-            "senpi.telemetry.timeline_payload_bytes": timelineWindow.payloadBytes,
-            "senpi.telemetry.stats_ticks": statsWindow.ticks,
-            "senpi.telemetry.stats_ms_max": roundMs(statsWindow.msMax),
-            "senpi.telemetry.records_scanned": statsWindow.recordsScanned,
-            "senpi.telemetry.stats_payload_bytes_max": statsWindow.payloadBytesMax,
-            "senpi.telemetry.tap_calls": tapWindow.calls,
-            "senpi.telemetry.tap_ns_total": tapWindow.nsTotal,
-            // No tap call is an idle box, not a division: the average of nothing is nothing.
-            "senpi.telemetry.tap_ns_avg": tapWindow.calls === 0 ? 0 : Math.round(tapWindow.nsTotal / tapWindow.calls),
-            "senpi.telemetry.tap_ns_p_max": tapWindow.nsMax,
-        });
-        timelineWindow.ticks = 0;
-        timelineWindow.msMax = 0;
-        timelineWindow.records = 0;
-        timelineWindow.payloadBytes = 0;
-        statsWindow.ticks = 0;
-        statsWindow.msMax = 0;
-        statsWindow.recordsScanned = 0;
-        statsWindow.payloadBytesMax = 0;
-        tapWindow.calls = 0;
-        tapWindow.nsTotal = 0;
-        tapWindow.nsMax = 0;
-    }
-    function noteOversizedRecord(record, bytes) {
-        if (warnedOversizedRecord)
-            return;
-        warnedOversizedRecord = true;
-        logger.warn("live telemetry dropped a record too large for one frame", {
-            "senpi.event.name": record.name,
-            "senpi.telemetry.record_bytes": bytes,
-            "senpi.telemetry.frame_limit_bytes": MAX_FRAME_BYTES,
-        });
-    }
-    function noteScrubFailure(err) {
-        if (warnedScrubFailure)
-            return;
-        warnedScrubFailure = true;
-        logger.warn("live telemetry redactor threw; the attribute it could not scrub was dropped", {
-            err: err instanceof Error ? err.message : String(err),
-        });
-    }
-    /**
-     * The process redactor, or `null` when none is registered yet — the boot window before
-     * `initDefaultPiiRedactor` resolves, an openredaction install that failed, or a test.
-     *
-     * Read once per outbound batch rather than per record, so one batch is scrubbed one way. The warn
-     * clears once a redactor appears, so a later regression is reported again rather than swallowed by
-     * a one-shot that already fired during boot.
-     */
-    function currentRedactor() {
-        const redactor = getDefaultPiiRedactor();
-        if (redactor !== null) {
-            warnedNoRedactor = false;
-            return redactor;
-        }
-        if (!warnedNoRedactor) {
-            warnedNoRedactor = true;
-            logger.warn("live telemetry has no PII redactor registered; string event attributes are dropped from the wire until one is");
-        }
-        return null;
-    }
-    /**
-     * Split records into frames that each serialise under the byte budget, scrubbing each one on the
-     * way. A record that cannot fit a frame by itself is dropped rather than sent: an oversized frame
-     * does not lose one line, it closes the client's socket with 1009 and loses the stream. The size is
-     * measured on the scrubbed record, because that is the one that goes out.
-     *
-     * `redactMs` is the scrub's share of the work, reported on the publish span: redaction is regex
-     * over every string attribute of every record, and a batch is hundreds of records at a one-second
-     * tick, so it is the number that says whether this fits its own interval.
-     */
-    async function toFrames(records) {
-        const redactor = currentRedactor();
-        const frames = [];
-        let current = [];
-        let bytes = 0;
-        let redactMs = 0;
-        for (const record of records) {
-            const scrubStartedAt = monotonicMs();
-            const wire = await toWireRecord(record, redactor, noteScrubFailure);
-            redactMs += monotonicMs() - scrubStartedAt;
-            // Bytes, not string length: the read limit is counted on the wire, and one non-ASCII
-            // character costs up to three of them.
-            const size = Buffer.byteLength(JSON.stringify(wire));
-            if (size > MAX_FRAME_BYTES) {
-                noteOversizedRecord(wire, size);
-                continue;
-            }
-            if (current.length > 0 && bytes + size > MAX_FRAME_BYTES) {
-                frames.push(current);
-                current = [];
-                bytes = 0;
-            }
-            current.push(wire);
-            bytes += size;
-        }
-        if (current.length > 0)
-            frames.push(current);
-        return { frames, redactMs };
-    }
-    function published(records) {
-        return records.filter((record) => PUBLISHED_EVENT_NAMES.has(record.name));
-    }
-    /** `null` when the facts could not be read — the caller decides whether to publish without them. */
-    async function readFacts() {
-        try {
-            return await options.collectFacts();
-        }
-        catch (err) {
-            // Health and state come from live runtime handles, which can be mid-teardown. A tick that
-            // cannot read them reports nothing rather than taking the stream down.
-            logger.warn("live telemetry could not read runtime facts", {
-                err: err instanceof Error ? err.message : String(err),
-            });
-            return null;
-        }
-    }
-    function buildStats(facts, sampledAt, 
-    // The whole held window, not the drained batch: buckets are computed on demand from the same
-    // records the snapshot replays.
-    records) {
-        return buildScannerStats({
-            epoch: timelineBuffer().epoch,
-            records,
-            scannerState: facts.scannerState,
-            bufferStartedAt,
-            sampledAt,
-        });
-    }
-    function buildTopology(facts) {
-        return buildStrategyTopology({
-            epoch: timelineBuffer().epoch,
-            strategies: facts.strategies,
-            runningRuntimeIds: facts.runningRuntimeIds,
-            unwiredRuntimeIds: facts.unwiredRuntimeIds,
-            readHealth: facts.readHealth,
-            now,
-        });
-    }
-    async function flushTimeline() {
-        // The scrub made this tick asynchronous, so two of them can be inside one interval. Same guard as
-        // `sample`: a tick still scrubbing keeps the drain, the batchSeq run and the frame order to
-        // itself, and the skipped tick's records come back on the next drain rather than being lost.
-        if (flushInFlight)
-            return;
-        flushInFlight = true;
-        const startedAt = monotonicMs();
-        try {
-            // The drain advances the publish cursor whether or not a handle exists, so a box nobody is
-            // watching does not build a backlog that lands as one flood on the first connect. The snapshot
-            // covers that client instead — `drain` evicts nothing.
-            const batch = published(timelineBuffer().drain());
-            if (batch.length > 0) {
-                await withSpan("telemetry.publish", {}, async (span) => {
-                    const { frames, redactMs } = await toFrames(batch);
-                    const sendStartedAt = monotonicMs();
-                    let payloadBytes = 0;
-                    let recordsFlushed = 0;
-                    for (const records of frames) {
-                        const payload = {
-                            v: 1,
-                            epoch: timelineBuffer().epoch,
-                            batchSeq: ++batchSeq,
-                            records,
-                        };
-                        // Measured on the frame handed to broadcast. A sum of record sizes is an intermediate
-                        // that omits the envelope and the separators, and those are real bytes against the read
-                        // limit.
-                        const bytes = Buffer.byteLength(JSON.stringify(payload));
-                        if (!publish(EVENT_TIMELINE, payload))
-                            continue;
-                        payloadBytes += bytes;
-                        recordsFlushed += records.length;
-                    }
-                    span.setAttributes({
-                        records_flushed: recordsFlushed,
-                        payload_bytes: payloadBytes,
-                        broadcast_ms: monotonicMs() - sendStartedAt,
-                        redact_ms: redactMs,
-                    });
-                    timelineWindow.records += recordsFlushed;
-                    timelineWindow.payloadBytes += payloadBytes;
-                });
-            }
-        }
-        catch (err) {
-            // A `setInterval` callback has nowhere to put a rejection, and a tick that dies takes the whole
-            // feed with it. Every step inside already guards itself, so reaching here is a bug worth a line.
-            if (!warnedFlushFailure) {
-                warnedFlushFailure = true;
-                logger.warn("live telemetry flush tick failed; this batch was lost", {
-                    err: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
-        finally {
-            flushInFlight = false;
-            noteTick("timeline", monotonicMs() - startedAt, flushIntervalMs);
-            reportTiming();
-        }
-    }
-    function noteTickFrameFull() {
-        if (warnedTickFrameFull)
-            return;
-        warnedTickFrameFull = true;
-        logger.warn("live telemetry dropped a scanner tick because the tick frame was full", {
-            "senpi.telemetry.event": EVENT_TICK,
-            "senpi.telemetry.frame_limit_bytes": MAX_FRAME_BYTES,
-        });
-    }
-    /**
-     * Take one finished run into the open window.
-     *
-     * The first line is what makes this free on an unwatched box: with no broadcast handle there is
-     * nothing to publish through, so nothing is built, nothing is held and no timer is armed. A tick
-     * that lands then is gone — it is a level, and the next one replaces it anyway.
-     *
-     * The window is capped by the frame budget rather than by a count, so the cap is the same number
-     * the timeline splits on and there is no second budget to keep in step. A tick that does not fit is
-     * dropped and the window stays publishable: an oversized frame does not cost one tick, it closes the
-     * client's socket and costs the stream.
-     */
-    function recordTick(run, startedAt, finishedAt) {
-        try {
-            if (broadcast === undefined || !tickSettings.enabled)
-                return;
-            const scannedCount = run.scannedCount;
-            const extras = run.tick ?? {};
-            const tick = {
-                // Normalised here for the same reason the buffer and the stats builder normalise: a client
-                // joins a tick to a stats row on `(address, scannerId)`, and a runtime's configured wallet
-                // may be checksummed where the record's is not.
-                address: normalizeStrategyAddress(run.address),
-                scannerId: run.scannerId,
-                finishedAt,
-                outcome: run.status,
-                ...(typeof scannedCount === "number" && Number.isFinite(scannedCount)
-                    ? { scannedCount }
-                    : {}),
-                signalCount: run.signalCount ?? run.signals?.length ?? 0,
-                ...(startedAt === undefined ? {} : { durationMs: Math.max(0, finishedAt - startedAt) }),
-                ...extras,
-            };
-            // Bytes, not entry count: one non-ASCII character in a scanner-authored outcome costs up to
-            // three of them, and the read limit at the far end counts bytes. The separator is counted with
-            // the tick it precedes, so the running total is the window's own size and not a sum under it.
-            const size = Buffer.byteLength(JSON.stringify(tick)) + (pendingTicks.length > 0 ? SEPARATOR_BYTES : 0);
-            if (pendingTickBytes + size > MAX_FRAME_BYTES) {
-                noteTickFrameFull();
-                return;
-            }
-            pendingTicks.push(tick);
-            pendingTickBytes += size;
-            if (tickTimer !== undefined)
-                return;
-            tickTimer = setTimeout(() => {
-                tickTimer = undefined;
-                void flushTicks();
-            }, TICK_COALESCE_MS);
-            // Telemetry must never be the reason a process stays alive.
-            tickTimer.unref?.();
-        }
-        catch {
-            // This runs inside the scanner's terminal callback. Nothing here may reach it.
-        }
-    }
-    /**
-     * Close the window and publish it as one compact frame.
-     *
-     * Every scanner-authored string in the window — the run outcome, the author's own state values,
-     * the arguments a tool call carried — goes through the same scrub the stats payload's free text
-     * takes. The budget is met HERE and not when the run was admitted, because a redaction can be
-     * longer than the text it replaced and it is the scrubbed frame that goes out.
-     *
-     * `t0` is the first run's finish time, so every `t` in the frame is a small offset rather than a
-     * repeated 13-digit stamp.
-     */
-    async function flushTicks() {
-        const batch = pendingTicks;
-        pendingTicks = [];
-        pendingTickBytes = tickEnvelopeBytes;
-        if (batch.length === 0 || broadcast === undefined)
-            return;
-        try {
-            const redactor = currentRedactor();
-            const scrub = (text) => scrubScannerText(text, redactor, noteScrubFailure);
-            const builder = createTickFrameBuilder({
-                epoch: timelineBuffer().epoch,
-                t0: batch[0].finishedAt,
-                settings: tickSettings,
-                maxBytes: MAX_FRAME_BYTES,
-            });
-            for (const tick of batch) {
-                // A run that does not fit is dropped on its own; the window stays publishable, because an
-                // oversized frame does not cost one tick — it closes the client's socket.
-                if (!(await builder.add(tick, scrub)))
-                    noteTickFrameFull();
-            }
-            const frame = builder.build();
-            if (frame === null)
-                return;
-            publish(EVENT_TICK, frame);
-        }
-        catch (err) {
-            // A `setTimeout` callback has nowhere to put a rejection. Every step inside guards itself, so
-            // reaching here is a bug worth a line rather than an unhandled rejection.
-            if (!warnedTickFlushFailure) {
-                warnedTickFlushFailure = true;
-                logger.warn("live telemetry tick flush failed; this frame was lost", {
-                    err: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
-    }
-    async function sample() {
-        // A gather slower than the tick would otherwise stack ticks on top of each other.
-        if (sampleInFlight)
-            return;
-        sampleInFlight = true;
-        const startedAt = monotonicMs();
-        try {
-            const facts = await readFacts();
-            if (facts === null)
-                return;
-            const stats = await withSpan("telemetry.stats.compute", {}, async (span) => {
-                // The tap counters are read here because this is the span that carries them: reading them on
-                // the faster tick would put a one-second window on a five-second measurement.
-                const tap = readAndResetTapCounters();
-                const records = timelineBuffer().read();
-                const built = buildStats(facts, now(), records);
-                const scrubStartedAt = monotonicMs();
-                const payload = await scrubStatsPayload(built, currentRedactor(), noteScrubFailure);
-                const redactMs = monotonicMs() - scrubStartedAt;
-                // Measured on the scrubbed payload: capping the free text is what decides the size, and the
-                // pre-scrub number is not the one that meets the read limit.
-                const payloadBytes = Buffer.byteLength(JSON.stringify(payload));
-                const bucketsEmitted = payload.scanners.reduce((n, entry) => n + entry.buckets.length, 0);
-                span.setAttributes({
-                    records_scanned: records.length,
-                    scanners: payload.scanners.length,
-                    buckets_emitted: bucketsEmitted,
-                    payload_bytes: payloadBytes,
-                    tap_ns_total: tap.nsTotal,
-                    tap_calls: tap.calls,
-                    tap_ns_p_max: tap.nsMax,
-                    redact_ms: redactMs,
-                });
-                statsWindow.recordsScanned += records.length;
-                if (payloadBytes > statsWindow.payloadBytesMax)
-                    statsWindow.payloadBytesMax = payloadBytes;
-                tapWindow.calls += tap.calls;
-                tapWindow.nsTotal += tap.nsTotal;
-                if (tap.nsMax > tapWindow.nsMax)
-                    tapWindow.nsMax = tap.nsMax;
-                return payload;
-            });
-            publish(EVENT_STATS, stats);
-            const topology = buildTopology(facts);
-            const signature = topologySignature(topology);
-            if (signature === lastTopologySignature)
-                return;
-            // Remembered only once the frame actually left. The ticks start before any client connects, so
-            // the first topology is built with no handle to send it through — recording that as delivered
-            // would suppress every later publish of a topology that then never changes again.
-            if (publish(EVENT_TOPOLOGY, topology))
-                lastTopologySignature = signature;
-        }
-        finally {
-            sampleInFlight = false;
-            // The whole tick, including the runtime read: that is what has to fit the interval, and it is
-            // the half the compute span cannot see.
-            noteTick("stats", monotonicMs() - startedAt, sampleIntervalMs);
-        }
-    }
-    return {
-        // A getter for the same reason the drain resolves the buffer per append: a reload replaces
-        // the singleton, and a value frozen at construction would name an epoch whose seq run ended.
-        get epoch() {
-            return timelineBuffer().epoch;
-        },
-        captureBroadcast(ctx, methodName) {
-            if (broadcast !== undefined)
-                return;
-            const candidate = ctx?.context
-                ?.broadcast;
-            if (typeof candidate !== "function")
-                return;
-            broadcast = candidate;
-            warnedNoBroadcast = false;
-            logger.info("live telemetry captured the gateway broadcast handle", {
-                "senpi.gateway.method": methodName,
-            });
-        },
-        async snapshot(params) {
-            // A seq only means something inside its epoch. A cursor minted by a previous run names records
-            // this one never had — most sharply after a restart, where the client's seq sits far above a
-            // counter that began again at 1 and "nothing after it" would hide the whole window. So unless
-            // the cursor names this epoch it is dropped entirely and everything held is served.
-            const afterSeq = params?.afterEpoch === timelineBuffer().epoch ? normalizeAfterSeq(params?.afterSeq) : 0;
-            const held = timelineBuffer().read();
-            // A cursor below the eviction frontier lost a record. The oldest record still held cannot
-            // answer this: the rings are per address, so one strategy's untouched low seqs sit under
-            // another's evictions. `afterSeq: 0` is a fresh client asking for whatever is held, not a
-            // resume, so it is never a gap.
-            let truncated = afterSeq > 0 && timelineBuffer().highestDroppedSeq() > afterSeq;
-            const owed = published(held.filter((record) => record.seq > afterSeq));
-            const { frames } = await toFrames(owed);
-            // A response is one frame, so an over-budget window sends the newest slice and says so.
-            const records = frames.length === 0 ? [] : frames[frames.length - 1];
-            if (frames.length > 1)
-                truncated = true;
-            // A snapshot still answers when the facts are unreadable: the recent window is the part a
-            // joining client cannot reconstruct, and it comes from the buffer alone.
-            const facts = (await readFacts()) ?? NO_FACTS;
-            const sampledAt = now();
-            return {
-                epoch: timelineBuffer().epoch,
-                topology: buildTopology(facts),
-                stats: await scrubStatsPayload(buildStats(facts, sampledAt, held), currentRedactor(), noteScrubFailure),
-                recent: { v: 1, epoch: timelineBuffer().epoch, batchSeq: ++batchSeq, records },
-                truncated,
-            };
-        },
-        flushTimeline,
-        sample,
-        recordTick,
-        flushTicks,
-        start() {
-            // Armed here rather than at construction: the sink is process-global, so a publisher that was
-            // built but never started must not be the one the scanners feed.
-            setScannerTickSink(recordTick);
-            if (flushTimer !== undefined)
-                return;
-            flushTimer = setInterval(() => void flushTimeline(), flushIntervalMs);
-            sampleTimer = setInterval(() => void sample(), sampleIntervalMs);
-            // Telemetry must never be the reason a process stays alive.
-            flushTimer.unref?.();
-            sampleTimer.unref?.();
-        },
-        stop() {
-            setScannerTickSink(null);
-            if (flushTimer !== undefined)
-                clearInterval(flushTimer);
-            if (sampleTimer !== undefined)
-                clearInterval(sampleTimer);
-            if (tickTimer !== undefined)
-                clearTimeout(tickTimer);
-            flushTimer = undefined;
-            sampleTimer = undefined;
-            tickTimer = undefined;
-            pendingTicks = [];
-            pendingTickBytes = tickEnvelopeBytes;
-            broadcast = undefined;
-            lastTopologySignature = undefined;
-            timelineBuffer().teardown();
-            // The next reader mints a fresh epoch, so a restarted seq run cannot collide with the one a
-            // client already holds.
-            if (ownsProcessBuffer)
-                teardownTimelineBuffer();
-        },
-    };
-}
-//# sourceMappingURL=live-telemetry.js.map