@senpi/runtime 3.0.132 → 3.0.138

package/dist/telemetry/telemetry-publisher.js

@@ -1,256 +0,0 @@
-/**
- * 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, how
- * the exit engine defended an open position, and why the strategy's status changed. It excludes the
- * box-operations and agent-plane families — `auto_update.*`, `tool.*`, `tool_approval.*`, the
- * installer and the state/mcp faults — which describe the box the strategy runs on, not the
- * strategy.
- *
- * The whole `dsl.*` family is admitted, the four records of the engine acting on money included: a
- * stop that moved, a close it is waiting on, the attempt that performs the close, and a position it
- * can no longer price. None of them is poll-frequency. A `dsl.sl_updated` follows a venue write that
- * `shouldSyncExchangeSl` allowed — a stop that is missing, a sync retrying, a phase or tier change,
- * or a floor that moved further than `slSyncMinDeltaForPrice` — and a position the backend owns
- * emits none at all. `dsl.price_fetch_stale` is latched on the position state and re-armed only when
- * a price returns, so a stall costs one record rather than one per failed poll, and the close pair
- * fires once in a position's life. Against a ring holding `DEFAULT_MAX_RECORDS_PER_ADDRESS` records
- * per address over a window measured in minutes, that volume evicts nothing — and a reader watching
- * a trade has to be able to see the stop move.
- *
- * `dsl.tick_aborted` and `dsl.tick_recovered` are the widest of the family and the cheapest: a tick
- * that aborts at the clearinghouse gate evaluates NO position on the box, and the per-position
- * counters that `dsl.price_fetch_stale` is derived from sit past that gate, so without this pair the
- * largest blind spot in the engine reaches the ring as nothing at all. Both are latched on the
- * monitor and re-armed only by a completed tick, so an outage of any length costs exactly two
- * records — a floor under the pair's volume that no poll frequency can lift.
- *
- * `dsl.close_attempt` has no `logger.event` behind it: it is a span the monitor opens around the
- * venue call, so admitting the name reserves it rather than adding records.
- *
- * 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 and the stop moves it wrote to the venue, not
-    // its per-tick floor arithmetic.
-    EVENT_NAME.dslCreated,
-    EVENT_NAME.dslPhaseChanged,
-    EVENT_NAME.dslTierAdvanced,
-    EVENT_NAME.dslSlUpdated,
-    EVENT_NAME.dslClosePending,
-    EVENT_NAME.dslClosed,
-    EVENT_NAME.dslDeleted,
-    EVENT_NAME.dslCloseAttempt,
-    EVENT_NAME.dslSlSyncFailed,
-    EVENT_NAME.dslPriceFetchStale,
-    EVENT_NAME.dslHandoffFailed,
-    EVENT_NAME.dslTickAborted,
-    EVENT_NAME.dslTickRecovered,
-    // 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

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

package/dist/telemetry/tick-frame.d.ts

@@ -1,212 +0,0 @@
-/**
- * The compact `plugin.senpi.tick` frame: the wire shape, the two detail dials that gate it, and the
- * byte budget it is built under.
- *
- * Shape, and why it is compact. A frame carries the latest finished run of every scanner on the box,
- * so the same 42-character wallet, the same scanner name and the same handful of tool names repeat on
- * every entry. A per-frame dictionary interns them once and each entry references them by index; the
- * timestamps are deltas from one frame-level `t0`; and the keys are one or two characters. Two hundred
- * runtimes at full detail land under a tenth of the frame budget this way, where the long-key shape
- * would not.
- *
- * Short keys stop at this boundary. A client's store expands them once at the reducer and its
- * components keep reading `scannedCount`, never `n`.
- *
- * Two dials, not one. `mcp` gates what the MCP boundary reports (`sw`, `mms`, `c`, `cms`) and `state`
- * gates the author's own state projection (`stc`, `st`), because the two cost very different numbers
- * of bytes and an operator watching a slow venue does not also want every author key on the wire. The
- * tick's own summary facts (`q`, `lag`, `jp`, `cm`) belong to neither, so they ride whenever either
- * dial is up: with both off the frame is the always-keys only, which is the shape a box publishes when
- * it wants nothing but proof of life.
- *
- * Nothing here reaches `logger.event` or `appendDomainEvent`. A tick is a LEVEL — see
- * {@link ../utils/telemetry-required-log.js} for why these facts must not become catalogued events.
- */
-/** How much of one source a frame carries. */
-export type TickDetail = "off" | "summary" | "verbose";
-/** The plugin-config shape: one level for both sources, or a level per source. */
-export type TickTelemetryConfig = TickDetail | {
-    mcp?: TickDetail;
-    state?: TickDetail;
-};
-/** The resolved dials. `enabled` is false only for a bare `"off"`, which publishes no frame at all. */
-export interface TickTelemetrySettings {
-    readonly enabled: boolean;
-    readonly mcp: TickDetail;
-    readonly state: TickDetail;
-}
-/**
- * The level a source takes when the configuration does not name it.
- *
- * Verbose, not summary: a box is watched by exactly one client over that client's own socket, the
- * frame budget holds two hundred runtimes at this level, and an operator who has to change a setting
- * before the screen can answer why a scanner is slow will not have changed it yet when it matters.
- */
-export declare const DEFAULT_TICK_DETAIL: TickDetail;
-/**
- * Character ceiling for one scanner-authored string inside a tick — an outcome, a state value, a
- * tool argument. Matches the cap the stats payload's free text takes, for the same reason: these
- * carry a stringified throwable or an author's own value, and nothing upstream bounds either.
- */
-export declare const MAX_TICK_TEXT_CHARS = 1024;
-/**
- * Calls recorded for one tick. A scanner that calls a tool in a loop would otherwise put an unbounded
- * list on the wire; past this many the tally still counts them (`c` at summary and `cms` stay whole,
- * because they are read off the scaffold's own totals), and only the per-call detail is cut.
- */
-export declare const MAX_TICK_CALLS = 64;
-/**
- * Bounds for one list-valued argument, mirroring the producer's own per-list bounds: at most this
- * many elements, and no more characters across the whole list than a single string argument is
- * allowed. The frame is a second, independent gate on values the scaffold already bounded, so it
- * must not admit a longer list than the scaffold can send — and a list from any other producer is
- * held to the same terms here.
- *
- * The frame's byte budget is not a substitute. That budget drops a whole ENTRY that does not fit,
- * so without these one scanner's long list would cost that scanner's entire tick rather than the
- * tail of the list. The character bound is counted AFTER the scrub, for the reason `scrubText`
- * gives: a redaction can be longer than the text it replaced, so a bound taken first would bound
- * the input and not what leaves.
- */
-export declare const MAX_TICK_CALL_ARG_LIST_ITEMS = 16;
-export declare const MAX_TICK_CALL_ARG_LIST_CHARS = 1024;
-/**
- * `cm` — the state commit outcome, as a RAW STRING and not a dictionary index. Only `a` `s` `m` `o`
- * `x` are interned; these are a small closed set a client reads directly.
- *
- * A tick that committed normally sends nothing at all: the key exists to make the abnormal endings
- * visible, and the common case is not one of them.
- *
- * - `rolled_back` — the tick was not `ok`, so the scaffold discarded the tick's state mutations.
- * - `persist_failed` — the commit was attempted, the write failed, and the tick was rolled back;
- *   state did not advance, which is the stall this key exists to make visible.
- */
-export declare const COMMIT_ROLLED_BACK = "rolled_back";
-export declare const COMMIT_PERSIST_FAILED = "persist_failed";
-/** The commit endings a producer may report. `committed` is the absent case. */
-export type TickCommitOutcome = "committed" | typeof COMMIT_ROLLED_BACK | typeof COMMIT_PERSIST_FAILED;
-/** One MCP tool call a tick made, as the producer's boundary timed it. */
-export interface TickCall {
-    readonly tool: string;
-    /** Wall time the call took. Absent when the producer reported none; never zero as a stand-in. */
-    readonly ms?: number;
-    /** The call's arguments. Ride at `mcp: verbose` only, sanitised, scrubbed and capped. */
-    readonly args?: Readonly<Record<string, unknown>>;
-    /** Set only on a failed call — the leaf error's type, as the boundary classified it. */
-    readonly errorType?: string;
-}
-/**
- * One finished run waiting for the next frame, already narrowed to what a tick carries.
- *
- * Every optional field means UNKNOWN when it is absent. A `scannedCount` of `0` is a scanner that
- * looked at nothing; an absent one is a scanner that did not say. The distinction is held from the
- * producer through this frame to the screen, so nothing here may default one to the other.
- */
-export interface PendingTick {
-    readonly address: string;
-    readonly scannerId: string;
-    /** Run status as the producer reports it. Scanner-authored text: scrubbed and capped. */
-    readonly outcome: string;
-    readonly finishedAt: number;
-    readonly signalCount: number;
-    readonly scannedCount?: number;
-    readonly durationMs?: number;
-    /** MCP failures the author's own `except` swallowed this tick. */
-    readonly mcpFailures?: number;
-    readonly mcpCalls?: readonly TickCall[];
-    /** Total time inside MCP this tick, as the producer totalled it. */
-    readonly mcpMs?: number;
-    /** Consecutive ticks that produced no signal, this one included. */
-    readonly quietTicks?: number;
-    /** Actual gap since the previous tick minus the configured interval. */
-    readonly lagMs?: number;
-    /** Signals still awaiting delivery in the producer's journal. */
-    readonly journalPending?: number;
-    readonly commit?: TickCommitOutcome;
-    /** The last COMMITTED state row, scalars only — stale by one tick by construction. */
-    readonly state?: Readonly<Record<string, unknown>>;
-    /** Fields in that row before sanitising, so `stc` can report the drop. */
-    readonly stateFieldCount?: number;
-    /** Fields in that row whose value moved since the previous committed row. */
-    readonly stateChangedCount?: number;
-}
-/** `c` at `mcp: summary` — how many times each tool was called, keyed by dictionary index. */
-export type TickCallCounts = Record<number, number>;
-/** `c` at `mcp: verbose` — one element per call; the error index appears only on a failed one. */
-export type TickCallDetail = readonly [tool: number, ms: number, args: Record<string, unknown>] | readonly [tool: number, ms: number, args: Record<string, unknown>, err: number];
-/** One tick on the wire. Every key is an index into the frame dictionary or a scalar. */
-export interface TickFrameEntry {
-    a: number;
-    s: number;
-    t: number;
-    o: number;
-    n?: number;
-    g: number;
-    ms?: number;
-    mms?: number;
-    q?: number;
-    lag?: number;
-    sw?: number;
-    jp?: number;
-    cm?: string;
-    c?: TickCallCounts | TickCallDetail[];
-    cms?: number;
-    stc?: readonly [changed: number, total: number];
-    st?: Record<string, string | number | boolean>;
-}
-/** The per-frame dictionary every index in an entry refers to. */
-export interface TickFrameDictionary {
-    /** Wallet addresses, normalised. */
-    a: string[];
-    /** Scanner ids. */
-    s: string[];
-    /** MCP tool names. */
-    m: string[];
-    /** Run outcomes. */
-    o: string[];
-    /** Error types. */
-    x: string[];
-}
-/**
- * A tick frame. No `batchSeq`, and its entries carry no `seq`: this is the current state of a set of
- * scanners, and a client that misses a frame is made whole by the next one rather than by a replay.
- */
-export interface TickFramePayload {
-    v: 1;
-    e: string;
-    /** The frame's time base. Every entry's `t` is a millisecond offset from it. */
-    t0: number;
-    d: TickFrameDictionary;
-    k: TickFrameEntry[];
-}
-/** Scrub one scanner-authored string. `null` means the text could not be vouched for. */
-export type TickScrub = (text: string) => Promise<string | null>;
-export interface TickFrameBuilderOptions {
-    readonly epoch: string;
-    readonly t0: number;
-    readonly settings: TickTelemetrySettings;
-    /** Byte ceiling for the built frame. Defaults to the caller's frame budget. */
-    readonly maxBytes?: number;
-}
-export interface TickFrameBuilder {
-    /**
-     * Take one finished run into the frame. Returns false when it did not fit, or when the dial
-     * publishes nothing — the frame stays publishable either way.
-     */
-    add(tick: PendingTick, scrub: TickScrub): Promise<boolean>;
-    /** The frame, or `null` when nothing was admitted and there is nothing to publish. */
-    build(): TickFramePayload | null;
-}
-/**
- * Read the `tickTelemetry` plugin-config value.
- *
- * Never throws and never leaves the caller without settings: an unusable value falls back to the
- * default and is reported in `invalid` so the caller can warn about it once, at startup, the way an
- * unusable `logLevel` is. A configuration mistake must not be the reason a box publishes nothing.
- */
-export declare function resolveTickTelemetry(value: unknown): {
-    settings: TickTelemetrySettings;
-    invalid?: string;
-};
-export declare function createTickFrameBuilder(options: TickFrameBuilderOptions): TickFrameBuilder;
-//# sourceMappingURL=tick-frame.d.ts.map

package/dist/telemetry/tick-frame.d.ts.map

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