@senpi/runtime 1.1.0-dev.runtime-phase-2.20260609132603 → 1.1.0-dev.runtime-phase-2.20260610130051

package/dist/recording/records.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Recording contract — the record types the runtime hands to a {@link RecordingEmitter}, covering
+ * domain events and runtime errors.
+ *
+ * Each record is one atomic "work unit": plain, immutable, serializable data with no methods or
+ * builder dance; variants are modelled with a discriminator field plus optionals. The types are
+ * transport-agnostic — nothing here knows about spans, attributes, or any wire format.
+ *
+ * Identity (service, recipe, runtime, strategy address, boot id) is stamped by the emitter and is
+ * never on a record — see {@link IdentityEnvelope}. Timestamps are epoch milliseconds; ISO strings
+ * from the bus are converted before they reach a record, so consumers never parse dates.
+ */
+/**
+ * Trade direction as the bus reports it. The alias itself is non-null; sites that admit a
+ * non-directional signal widen it to `TradeDirection | null` (e.g. {@link SignalSummary}).
+ */
+export type TradeDirection = "LONG" | "SHORT";
+/**
+ * Lightweight projection of a scanner signal as it appears on the bus, including the explainable
+ * `factors`/`meta` bags so the audit trail keeps the "why". Redacting sensitive `meta` is the
+ * adapter's job, not this contract's.
+ */
+export interface SignalSummary {
+    readonly signalType: string;
+    readonly asset: string;
+    readonly direction: TradeDirection | null;
+    readonly score: number;
+    /** Signal time, epoch ms. */
+    readonly timestamp: number;
+    readonly factors?: Record<string, boolean>;
+    readonly meta?: Record<string, unknown>;
+}
+/** Coarse terminal classification of a scanner execution. */
+export type ScannerRunOutcome = "complete" | "skipped" | "error";
+/**
+ * One scanner execution attempt (the work unit). Folds the bus's `scanner:run:start` +
+ * terminal `scanner:run:{complete,skip,error}` events into a single atomic record so a
+ * duration is always derivable (`endedAt - startedAt`). Skip/error early-exit paths can
+ * terminate without a paired `scanner:run:start` event; in that case Task 4 fills `startedAt`
+ * with the run's attempt timestamp (which equals `endedAt`), so duration is 0 rather than absent.
+ * The skipped/disabled distinction lives on `outcome`/`statusDetail`, not on a missing start.
+ */
+export interface ScannerRunRecord {
+    readonly type: "scanner_run";
+    readonly scannerId: string;
+    readonly outcome: ScannerRunOutcome;
+    /** Raw engine status: `ok`|`heartbeat`|`skipped`|`halted`|`disabled`|`error`. */
+    readonly statusDetail?: string;
+    /**
+     * Run start, epoch ms (from `scanner:run:start`). Required: on a no-start early-exit path Task 4
+     * sets it to the attempt timestamp (= `endedAt`), so a `Duration` is always derivable.
+     */
+    readonly startedAt: number;
+    /** Run completion, epoch ms (terminal event timestamp). */
+    readonly endedAt: number;
+    readonly scannedCount?: number;
+    readonly actionableCount?: number;
+    readonly signalCount?: number;
+    readonly signals?: readonly SignalSummary[];
+    /** Per-scanner aggregated run metrics/details (`ScanResult.summary`). */
+    readonly summary?: Record<string, unknown>;
+    /** Explanation for a non-OK status (skip/error). */
+    readonly reason?: string;
+    /** Error message when `outcome === "error"`. */
+    readonly error?: string;
+    /** Error class name (`Error.name`) when `outcome === "error"` — the error-grouping key. */
+    readonly errorName?: string;
+}
+/** How the decision was produced (`emitTrackingDecision` reports this). */
+export type DecisionMode = "llm" | "script" | "agent" | "rule" | "none";
+/** Decision produced by the decision layer for an evaluation pass. */
+export interface SignalDecision {
+    readonly execute: boolean;
+    /** Action type, e.g. `"open_position"`. */
+    readonly actionType: string;
+    /** Concrete action instance name. */
+    readonly actionName?: string;
+    /** Distinguishes a vestigial rule "decision" from a real LLM judgment. */
+    readonly mode?: DecisionMode;
+    readonly confidence: number;
+    /** Bar `confidence` was compared against (`min_confidence`); makes the below_confidence boundary reconstructable. */
+    readonly confidenceThreshold?: number;
+    readonly reasoning: string;
+    /** LLM-path auditing (from `ActionDecision.decisionTelemetry`). */
+    readonly model?: string;
+    readonly tokensUsed?: number | null;
+    readonly durationMs?: number;
+    /** Proposed per-asset overrides (leverage/margin/etc.) the decision emitted. */
+    readonly payload?: Record<string, unknown>;
+}
+/** Coarse result of acting on an evaluated signal. */
+export type SignalOutcomeResult = "executed" | "rejected" | "skipped" | "below_confidence" | "error";
+/**
+ * Outcome of acting on a **single** signal within an evaluation pass. Outcomes are per-signal: the
+ * action loops over the batch producing one result each and decrements margin as it goes, so a
+ * later signal's outcome only makes sense alongside the earlier ones.
+ *
+ * `result` is the coarse classification. `reasonCode` is an open string for the granular per-signal
+ * reasons (e.g. `risk_gate_COOLDOWN`, `insufficient_margin`, `below_min_notional`,
+ * `position_open_failed`, `no_slots`, `invalid_direction`); keeping it an open string means new
+ * reasons can be carried without changing this type.
+ */
+export interface SignalOutcome {
+    readonly result: SignalOutcomeResult;
+    readonly summary?: string;
+    readonly reasonCode?: string;
+    readonly reason?: string;
+    readonly error?: string;
+    /** Error class name (`Error.name`, e.g. `"ZodError"`) — the natural error-grouping key. */
+    readonly errorName?: string;
+    readonly leverage?: number;
+    readonly marginAmount?: number;
+    readonly notionalValue?: number;
+    readonly orderId?: string;
+    readonly entryPrice?: number;
+    readonly size?: number;
+    /** Order-fill success flag from `CreatePositionOrderResult.filled` (boolean, not a quantity). */
+    readonly filled?: boolean | null;
+    /** Maker vs taker fill (`CreatePositionOrderResult.executionAsMaker`); `null` when unfilled. */
+    readonly executionAsMaker?: boolean | null;
+    readonly requiredMarginAmount?: number;
+    readonly availableMarginAmount?: number;
+}
+/**
+ * One evaluated signal paired with its outcome. Pairing (rather than two index-aligned arrays)
+ * keeps signal and outcome structurally bound, so no filter/sort/map can silently misalign them.
+ */
+export interface SignalEvaluation {
+    readonly signal: SignalSummary;
+    readonly outcome: SignalOutcome;
+}
+/**
+ * One signal-evaluation work unit: the runtime hands a scan pass's batch to the action, which
+ * decides once, then acts on each signal serially. The whole pass is one record — a 3-signal batch
+ * is ONE record with three `evaluations`, not three records. Nesting the decision and per-signal
+ * outcomes keeps them bound together without a separate join key.
+ */
+export interface SignalEvaluatedRecord {
+    readonly type: "signal_evaluated";
+    readonly scannerId?: string;
+    /** Evaluation start, epoch ms. Required (see {@link ScannerRunRecord.startedAt}) so a `Duration` is always derivable. */
+    readonly startedAt: number;
+    /** Evaluation end, epoch ms. */
+    readonly endedAt: number;
+    /**
+     * Pass-level decision (the single `ActionDecision` the engine/LLM produces for this pass).
+     * Absent when the pass was filtered before a decision was produced.
+     */
+    readonly decision?: SignalDecision;
+    /** One entry per signal in the evaluated batch; outcomes are per-signal. */
+    readonly evaluations: readonly SignalEvaluation[];
+}
+export type PositionLifecycleEvent = "opened" | "closed" | "flipped" | "increased" | "decreased" | "open_order_submitted";
+/**
+ * A position lifecycle domain event observed on the bus. These are first-class events — they
+ * fire both as the outcome of acting on a signal *and* when the position-tracker scanner
+ * detects on-chain changes opened manually or by other tools — so they are recorded
+ * independently of {@link SignalEvaluatedRecord}.
+ *
+ * Variant-specific fields are optional; `event` discriminates which apply.
+ */
+export interface PositionLifecycleRecord {
+    readonly type: "position_lifecycle";
+    readonly event: PositionLifecycleEvent;
+    readonly occurredAt: number;
+    readonly asset: string;
+    /** Empty string / undefined for the main book. */
+    readonly dex?: string;
+    readonly direction?: TradeDirection | null;
+    readonly entryPrice?: number;
+    readonly size?: number;
+    readonly leverage?: number;
+    readonly leverageType?: string;
+    readonly margin?: number;
+    readonly unrealizedPnl?: number;
+    readonly roe?: number;
+    /** `null` when the venue reports no liquidation price. */
+    readonly liquidationPrice?: number | null;
+    readonly reason?: string;
+    readonly closeReason?: string;
+    readonly closedPrice?: number;
+    readonly closedSize?: number;
+    /** Maker vs taker on the close (`null` when unfilled). */
+    readonly executionAsMaker?: boolean | null;
+    readonly previousEntryPrice?: number;
+    readonly previousSize?: number;
+    readonly sizeDelta?: number;
+    readonly newAsset?: string;
+    readonly orderId?: string;
+    readonly orderType?: string;
+    readonly marginAmount?: number;
+    /** Order-fill success flag from `CreatePositionOrderResult.filled` (boolean, not a quantity). */
+    readonly filled?: boolean | null;
+    readonly reasoning?: string;
+}
+export type DslTransitionKind = "created" | "phase_changed" | "tier_advanced" | "sl_updated" | "closed" | "close_pending" | "settings_updated" | "deleted";
+/** A tier in the exit ladder, as carried on `dsl.created`. */
+export interface DslTierSummary {
+    readonly triggerPct: number;
+    readonly lockHwPct: number;
+}
+/**
+ * A DSL exit-engine transition. One record per transition; `transition` discriminates which of the
+ * optional fields are populated. Periodic `dsl.heartbeat` is intentionally not modelled — it is a
+ * notification cadence, not a state transition.
+ */
+export interface DslTransitionRecord {
+    readonly type: "dsl_transition";
+    readonly transition: DslTransitionKind;
+    readonly occurredAt: number;
+    readonly asset: string;
+    readonly dex?: string;
+    /** Lifecycle event that produced the DSL row (`position_opened`|`..._increased`|`flipped`). */
+    readonly triggerReason?: string;
+    readonly preset?: string;
+    /** Exit ladder the position was created with (`dsl.created`). */
+    readonly tiers?: readonly DslTierSummary[];
+    readonly direction?: TradeDirection;
+    readonly entryPrice?: number;
+    readonly leverage?: number;
+    readonly margin?: number;
+    readonly size?: number;
+    readonly floorPrice?: number;
+    readonly newFloorPrice?: number;
+    readonly phase?: 1 | 2;
+    /**
+     * Current tier index. Normalizes the three bus spellings into one field — `tierIndex`
+     * (`dsl.phase_changed`), `tier` (`dsl.tier_advanced`), `currentTierIndex` (`dsl.closed`) — so
+     * downstream never has to know which event produced the record. `null` when no tier is active.
+     */
+    readonly tierIndex?: number | null;
+    readonly lockHwPct?: number;
+    readonly triggerPct?: number;
+    readonly lockedProfitPct?: number;
+    readonly newSLPrice?: number;
+    readonly slOrderId?: number;
+    readonly reason?: string;
+    readonly closeReason?: string;
+    /** Position open time, epoch ms (on `closed`). */
+    readonly createdAt?: number;
+    readonly currentROE?: number;
+    readonly highWaterRoe?: number;
+    /** High-water *price* the trailing floor is relative to (`DslState.highWaterPrice`). */
+    readonly highWaterPrice?: number;
+    readonly peakROE?: number;
+    readonly lastPrice?: number;
+    readonly attempt?: number;
+    readonly updated?: readonly string[];
+    /**
+     * Senpi/MCP-side position id (`DslState.backendDslPositionId`). Captured opportunistically for
+     * exchange-side correlation — but **DSL-only**: the runtime must not treat this as a position
+     * identity, since DSL need not be active for a position to exist. `null` when not yet assigned.
+     */
+    readonly backendDslPositionId?: string | null;
+}
+/**
+ * A bucket-2 error that does not belong to a specific domain record (e.g. the bus's
+ * `signal_processing_error`). Errors that *do* have a home — scanner failures, action
+ * failures, DSL close failures — are carried on {@link ScannerRunRecord}, {@link SignalOutcome}
+ * and {@link DslTransitionRecord} respectively.
+ */
+export interface RuntimeErrorRecord {
+    readonly type: "runtime_error";
+    readonly occurredAt: number;
+    /** Where the error originated, e.g. `"signal_processing"`. */
+    readonly phase: string;
+    readonly message: string;
+    /** Error class name (`Error.name`, e.g. `"ZodError"`) — the natural error-grouping key. */
+    readonly errorName?: string;
+    readonly asset?: string;
+    readonly scannerId?: string;
+    readonly stack?: string;
+}
+export type RuntimeLifecyclePhase = "started" | "stopped";
+/**
+ * Runtime session boundary. Marks process start/stop and carries session shape; `strategyAddress`
+ * is omitted because it lives on the identity envelope.
+ */
+export interface RuntimeLifecycleRecord {
+    readonly type: "runtime_lifecycle";
+    readonly phase: RuntimeLifecyclePhase;
+    readonly occurredAt: number;
+    readonly runtimeVersion?: string;
+    readonly hasDsl?: boolean;
+    readonly scannerCount?: number;
+    readonly actionCount?: number;
+    /**
+     * The **unresolved** runtime config at boot (raw YAML/config, `${VAR}` placeholders intact) — the
+     * retrospection snapshot of what this session ran. Deliberately NOT the resolved config: resolving
+     * `${VAR}` inlines secrets (e.g. `SENPI_API_KEY`), which `env-resolve.ts` forbids exporting. Keeping
+     * it unresolved needs no redaction and is the stabler artifact — it is also the input `configHash`
+     * is computed over, so blob and hash agree. See {@link IdentityEnvelope.configHash}.
+     */
+    readonly config?: Record<string, unknown>;
+    readonly uptimeMs?: number;
+}
+export type RuntimeStatePhase = "paused" | "resumed";
+/**
+ * A runtime trading-state transition — the runtime pausing or resuming its *own* trading on a
+ * cap/halt. Sibling to {@link RuntimeLifecycleRecord} on a different axis: lifecycle records the
+ * process (started/stopped); this records whether trading is active or self-paused.
+ *
+ * `paused` corresponds to the bus's `on_strategy_self_paused` / `on_daily_limit_hit` /
+ * `on_drawdown_cap_hit`, which fire on a `running → paused` edge carrying the breached `metrics`.
+ * `resumed` is the symmetric `paused → running` re-arm; modelling it here lets the emit be added
+ * later without changing this type. `strategyAddress` is omitted — it lives on the identity envelope.
+ *
+ * This is the "why did the runtime stop trading" signal — for observability and for an agent
+ * reasoning about self-imposed halts (raise a cap, wait for daily reset, investigate drawdown).
+ */
+export interface RuntimeStateRecord {
+    readonly type: "runtime_state";
+    readonly phase: RuntimeStatePhase;
+    readonly occurredAt: number;
+    /** Stable gate identifier (e.g. the cap/halt rule id). */
+    readonly gateId: string;
+    readonly gateName?: string;
+    /** Which hook produced the pause (`self_paused`|`daily_limit`|`drawdown_cap`). */
+    readonly source?: string;
+    /** Human-readable explanation with live numbers (the gate's `reason`). */
+    readonly reason?: string;
+    /** Breached-gate metrics bag (`pnlDelta`, `dailyLossLimitUsd`, `drawdownFromPeakPct`, …). */
+    readonly metrics?: Record<string, unknown> | null;
+}
+/** Discriminated union of every record type. */
+export type RecordingRecord = ScannerRunRecord | SignalEvaluatedRecord | PositionLifecycleRecord | DslTransitionRecord | RuntimeErrorRecord | RuntimeLifecycleRecord | RuntimeStateRecord;
+//# sourceMappingURL=records.d.ts.map

package/dist/recording/records.d.ts.map

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

package/dist/recording/records.js

@@ -0,0 +1,14 @@
+/**
+ * Recording contract — the record types the runtime hands to a {@link RecordingEmitter}, covering
+ * domain events and runtime errors.
+ *
+ * Each record is one atomic "work unit": plain, immutable, serializable data with no methods or
+ * builder dance; variants are modelled with a discriminator field plus optionals. The types are
+ * transport-agnostic — nothing here knows about spans, attributes, or any wire format.
+ *
+ * Identity (service, recipe, runtime, strategy address, boot id) is stamped by the emitter and is
+ * never on a record — see {@link IdentityEnvelope}. Timestamps are epoch milliseconds; ISO strings
+ * from the bus are converted before they reach a record, so consumers never parse dates.
+ */
+export {};
+//# sourceMappingURL=records.js.map

package/dist/recording/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/recording/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/recording/transport/batcher.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Micro-batcher — two independent buffers (traces, logs). `enqueueTrace` /
+ * `enqueueLog` are cheap and non-blocking; rows ship on a timer interval, with
+ * an early flush when a buffer nears the byte cap.
+ *
+ * Reliability policy (lean, by design):
+ * - **Drop over block, always.** A full buffer or a failed flush NEVER blocks
+ *   or throws into the caller. On any error: log, count the drop, move on.
+ *   **No retry** — the seam is left for a later dedicated stage.
+ * - Two distinct signals are counted: *client-dropped* (never sent — overflow,
+ *   oversized row, an oversized batch (413), or a transport/auth/5xx flush
+ *   failure) vs *server-rejected* (a `200` that accepted fewer rows than were
+ *   sent, or a `400` — a malformed row that got through the mapper; a mapper
+ *   bug to surface, not a transport failure). The 200 shortfall is derived from
+ *   `accepted`, not the response's `rejected` field: the service reports
+ *   schema-validation drops only in `errors[]`, so trusting `rejected` alone
+ *   would let mapper bugs go uncounted.
+ * - Flush-on-interval is primary; byte-cap early-flush is the only added
+ *   trigger. Remaining buffers flush best-effort on shutdown (time-boxed by the
+ *   client's per-request timeout).
+ *
+ * Each row is serialized exactly once (at enqueue, for byte accounting); the
+ * cached JSON is reused both to size the buffer and to frame the HTTP body, so
+ * the cap bounds the ACTUAL serialized body (envelope + separators included).
+ */
+import { type TelemetryClient } from "./client.js";
+import type { TransportConfig } from "./config.js";
+import type { LogRow, TraceRow } from "./rows.js";
+/** Per-signal counters. */
+export interface SignalStats {
+    /** Rows handed to `enqueue`. */
+    enqueued: number;
+    /** Rows the server accepted (sum of `accepted` across 2xx flushes). */
+    sent: number;
+    /** Rows never sent — overflow, oversized, or a transport/auth/5xx failure. */
+    clientDropped: number;
+    /** Rows the server refused — a 200's accepted-shortfall, or a whole 400 batch. */
+    serverRejected: number;
+}
+export interface BatcherStats {
+    traces: SignalStats;
+    logs: SignalStats;
+}
+export interface TelemetryBatcher {
+    enqueueTrace(row: TraceRow): void;
+    enqueueLog(row: LogRow): void;
+    /** Flush both buffers now (best-effort). */
+    flush(): Promise<void>;
+    /** Stop the timer and flush remaining rows (best-effort, time-boxed). */
+    shutdown(): Promise<void>;
+    /** Snapshot of per-signal counters. */
+    getStats(): BatcherStats;
+}
+/**
+ * Build a batcher. `client` is injectable for testing; by default it is built
+ * from `config`.
+ */
+export declare function createBatcher(config: TransportConfig, client?: TelemetryClient): TelemetryBatcher;
+//# sourceMappingURL=batcher.d.ts.map

package/dist/recording/transport/batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../../../src/recording/transport/batcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAA0C,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAKlD,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;CACnB;AA2LD,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAClC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,yEAAyE;IACzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,IAAI,YAAY,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,eAA+C,GACtD,gBAAgB,CAkClB"}

package/dist/recording/transport/batcher.js

@@ -0,0 +1,234 @@
+/**
+ * Micro-batcher — two independent buffers (traces, logs). `enqueueTrace` /
+ * `enqueueLog` are cheap and non-blocking; rows ship on a timer interval, with
+ * an early flush when a buffer nears the byte cap.
+ *
+ * Reliability policy (lean, by design):
+ * - **Drop over block, always.** A full buffer or a failed flush NEVER blocks
+ *   or throws into the caller. On any error: log, count the drop, move on.
+ *   **No retry** — the seam is left for a later dedicated stage.
+ * - Two distinct signals are counted: *client-dropped* (never sent — overflow,
+ *   oversized row, an oversized batch (413), or a transport/auth/5xx flush
+ *   failure) vs *server-rejected* (a `200` that accepted fewer rows than were
+ *   sent, or a `400` — a malformed row that got through the mapper; a mapper
+ *   bug to surface, not a transport failure). The 200 shortfall is derived from
+ *   `accepted`, not the response's `rejected` field: the service reports
+ *   schema-validation drops only in `errors[]`, so trusting `rejected` alone
+ *   would let mapper bugs go uncounted.
+ * - Flush-on-interval is primary; byte-cap early-flush is the only added
+ *   trigger. Remaining buffers flush best-effort on shutdown (time-boxed by the
+ *   client's per-request timeout).
+ *
+ * Each row is serialized exactly once (at enqueue, for byte accounting); the
+ * cached JSON is reused both to size the buffer and to frame the HTTP body, so
+ * the cap bounds the ACTUAL serialized body (envelope + separators included).
+ */
+import { createTelemetryClient } from "./client.js";
+import { createLogger } from "../../utils/logger.js";
+const logger = createLogger("[recording][transport][batcher]");
+function newStats() {
+    return { enqueued: 0, sent: 0, clientDropped: 0, serverRejected: 0 };
+}
+/**
+ * One signal's buffer: holds pre-serialized rows, tracks the exact serialized
+ * body size, and owns its own in-flight guard so traces and logs flush
+ * independently.
+ */
+class SignalBuffer {
+    name;
+    maxBatchBytes;
+    sendFn;
+    /** Pre-serialized rows (JSON), reused to frame the HTTP body. */
+    rows = [];
+    /** Σ byte length of the serialized rows (excludes envelope + separators). */
+    contentBytes = 0;
+    flushing = false;
+    /** The promise of the flush currently in flight, or null when idle. */
+    inFlight = null;
+    /** Fixed `{"<key>":[]}` envelope overhead, counted toward the byte cap. */
+    envelopeBytes;
+    stats = newStats();
+    constructor(name, maxBatchBytes, sendFn) {
+        this.name = name;
+        this.maxBatchBytes = maxBatchBytes;
+        this.sendFn = sendFn;
+        const bodyKey = name === "traces" ? "spans" : "logs";
+        this.envelopeBytes = Buffer.byteLength(`{"${bodyKey}":[]}`, "utf8");
+    }
+    /** Exact serialized body size for the rows currently buffered. */
+    bodyBytes() {
+        const commas = this.rows.length > 0 ? this.rows.length - 1 : 0;
+        return this.envelopeBytes + this.contentBytes + commas;
+    }
+    /** Would appending a `size`-byte row (plus its separator) cross the cap? */
+    wouldExceed(size) {
+        const separator = this.rows.length > 0 ? 1 : 0;
+        return this.bodyBytes() + separator + size > this.maxBatchBytes;
+    }
+    enqueue(row) {
+        this.stats.enqueued++;
+        const json = JSON.stringify(row);
+        const size = Buffer.byteLength(json, "utf8");
+        // A single row whose own framed body would exceed the cap can never ship.
+        if (this.envelopeBytes + size > this.maxBatchBytes) {
+            this.stats.clientDropped++;
+            logger.warn("dropping oversized telemetry row", {
+                signal: this.name,
+                rowBytes: size,
+                maxBatchBytes: this.maxBatchBytes,
+            });
+            return;
+        }
+        // Byte-cap early flush: appending this row (plus a comma separator when the
+        // buffer is non-empty) would cross the cap. flush() swaps the buffer out
+        // synchronously (before its first await), so when no flush is already in
+        // flight this clears room for the new row.
+        if (this.wouldExceed(size)) {
+            void this.flush();
+            if (this.wouldExceed(size)) {
+                // A flush is already in flight and the buffer is still full — drop.
+                this.stats.clientDropped++;
+                logger.warn("dropping telemetry row on buffer overflow", {
+                    signal: this.name,
+                    bufferBytes: this.bodyBytes(),
+                    maxBatchBytes: this.maxBatchBytes,
+                });
+                return;
+            }
+        }
+        this.rows.push(json);
+        this.contentBytes += size;
+    }
+    flush() {
+        if (this.flushing || this.rows.length === 0)
+            return Promise.resolve();
+        this.flushing = true;
+        // Swap synchronously so enqueue sees an empty buffer immediately.
+        const batch = this.rows;
+        this.rows = [];
+        this.contentBytes = 0;
+        // Publish the in-flight promise so `drain()` (shutdown) can await it.
+        this.inFlight = this.send(batch).finally(() => {
+            this.flushing = false;
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    /** Ship one batch and account the result. Never throws. */
+    async send(batch) {
+        try {
+            const result = await this.sendFn(batch);
+            this.account(batch.length, result);
+        }
+        catch (err) {
+            // The client is contracted never to throw, but the batcher is the last
+            // line of defense: swallow anything and count it as dropped.
+            this.stats.clientDropped += batch.length;
+            logger.warn("telemetry flush threw unexpectedly", {
+                signal: this.name,
+                batch: batch.length,
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Best-effort shutdown drain: wait for any in-flight send to settle, then
+     * flush whatever accumulated while it was in flight. One extra pass suffices
+     * — no new rows arrive once shutdown has begun. Without this, a flush already
+     * in flight makes the plain `flush()` return early (the `flushing` guard),
+     * silently stranding the just-buffered rows.
+     */
+    async drain() {
+        if (this.inFlight)
+            await this.inFlight;
+        await this.flush();
+    }
+    account(batchSize, result) {
+        switch (result.outcome) {
+            case "transport":
+                this.stats.clientDropped += batchSize;
+                logger.warn("telemetry flush failed; batch dropped (no retry)", {
+                    signal: this.name,
+                    batch: batchSize,
+                    status: result.status,
+                });
+                return;
+            case "oversized":
+                // 413: the body exceeded the server's limit. A client batching defect,
+                // not transient transport and not a per-row mapper bug — surface it
+                // distinctly so it isn't mistaken for a network outage.
+                this.stats.clientDropped += batchSize;
+                logger.warn("telemetry batch exceeded server size limit; dropped — lower maxBatchBytes or split", {
+                    signal: this.name,
+                    batch: batchSize,
+                    status: result.status,
+                });
+                return;
+            case "rejected":
+                // 400: whole batch invalid — a mapper bug.
+                this.stats.serverRejected += batchSize;
+                logger.warn("telemetry batch server-rejected (400, all rows invalid)", {
+                    signal: this.name,
+                    batch: batchSize,
+                    errors: result.errors.slice(0, 5),
+                });
+                return;
+            case "accepted": {
+                // 200: partial acceptance. Any row the server did not accept was refused
+                // — ownership rejections (counted in `rejected`) AND schema-validation
+                // drops (which the service reports only in `errors[]`, never in
+                // `rejected`). Derive the shortfall from `accepted` so no refused row
+                // goes uncounted.
+                this.stats.sent += result.accepted;
+                const refused = batchSize - result.accepted;
+                if (refused > 0) {
+                    this.stats.serverRejected += refused;
+                    // Distinguish ownership rejections (reported in `rejected`, possibly
+                    // an ownership-service issue) from schema drops (a likely mapper bug).
+                    const schemaDropped = Math.max(0, refused - result.rejected);
+                    logger.warn("telemetry rows not accepted by server", {
+                        signal: this.name,
+                        refused,
+                        ownershipRejected: result.rejected,
+                        schemaDropped,
+                        errors: result.errors.slice(0, 5),
+                    });
+                }
+                return;
+            }
+        }
+    }
+}
+/**
+ * Build a batcher. `client` is injectable for testing; by default it is built
+ * from `config`.
+ */
+export function createBatcher(config, client = createTelemetryClient(config)) {
+    const traces = new SignalBuffer("traces", config.maxBatchBytes, (rowsJson) => client.sendTraces(rowsJson));
+    const logs = new SignalBuffer("logs", config.maxBatchBytes, (rowsJson) => client.sendLogs(rowsJson));
+    const flush = async () => {
+        await Promise.all([traces.flush(), logs.flush()]);
+    };
+    const timer = setInterval(() => {
+        void flush();
+    }, config.flushIntervalMs);
+    // Telemetry flushes must not keep the process alive (Node >=22).
+    timer.unref();
+    let stopped = false;
+    return {
+        enqueueTrace: (row) => traces.enqueue(row),
+        enqueueLog: (row) => logs.enqueue(row),
+        flush,
+        async shutdown() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(timer);
+            // Drain (not plain flush): wait for any in-flight send, then ship rows
+            // buffered during it — otherwise the `flushing` guard strands them.
+            await Promise.all([traces.drain(), logs.drain()]);
+        },
+        getStats: () => ({ traces: { ...traces.stats }, logs: { ...logs.stats } }),
+    };
+}
+//# sourceMappingURL=batcher.js.map