@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/dist/clients/bounded-telemetry.js

@@ -0,0 +1,206 @@
+/**
+ * Typed bounded telemetry emission (#1743).
+ *
+ * Four PRs in two days hand-built the same machinery: a failure path that
+ * needs a detailed `latency.log` record, an exact per-identity tally, and a
+ * bound so a storming subsystem cannot flood the log. #1705 (orphan
+ * forensics), #1717 (pull timeouts and late answers), #1726 (navRequest
+ * timeouts, rising edge per method and file), and #1733 (loop-block floor
+ * with a per-turn bound) each rebuilt it, and each needed a review round to
+ * get the bounding right. This module is the intersection of those four, not
+ * a speculative framework. Three of its four options come straight from those
+ * sites. The fourth, `capPerTurn`, expresses #1733's per-turn bound
+ * structurally but has no caller yet: that site's bound is its call cadence,
+ * and pinning a cap there would red its own wiring tests. It ships tested and
+ * mutation-proofed, awaiting its first site.
+ *
+ * Three rules the helper makes structural instead of prose:
+ *
+ * 1. **The rising edge comes from the ledger's own tally.** #1705 established
+ *    that `incrementDegradationCount` already knows whether a
+ *    (kind, subject) pair is being seen for the first time, and returns it.
+ *    A caller that wants "log the detail once, count the rest" reads that
+ *    return value. It never keeps a second `Set` — a parallel latch is state
+ *    that must re-arm at `session_start` and will eventually be forgotten
+ *    (the #1266–#1625 defect class).
+ * 2. **A per-turn cap names its turn.** `capPerTurn` carries the caller's
+ *    `turnIndex` in the same object as the limit, so there is no separate
+ *    reset to wire and forget: the counters clear when the observed turn
+ *    changes. This is the same lazy clear-on-transition shape as
+ *    `noteImportResolutionMemoTurn` (`clients/blocker-freshness.ts`).
+ * 3. **Identity always survives.** Every emitted record carries the
+ *    discriminating identity in `filePath` and in `metadata.identity`, so
+ *    aggregation can still answer "which file, which method, which record is
+ *    stuck" (the rule AGENTS.md states, now enforced by the signature).
+ *
+ * `BOUNDED_TELEMETRY_PHASES` is the registry.
+ * `tests/clients/bounded-telemetry-sweep.test.ts` sweeps it registered-or-
+ * fail: a failure-path phase must either route through this helper or carry a
+ * stated reason for staying raw.
+ *
+ * Nothing here ever throws. Telemetry must not perturb the path it observes —
+ * every one of the four migrated sites had already decided its outcome before
+ * calling in.
+ */
+import { incrementDegradationCount } from "./degradation-ledger.js";
+import { logLatency } from "./latency-logger.js";
+/**
+ * Phases that emit through this helper. The `phase` parameter is typed to
+ * this list, so a new bounded phase cannot be emitted without joining the
+ * registry, and the sweep proves the reverse direction: a registered phase
+ * must not also be written by a raw `logLatency` call somewhere else.
+ */
+export const BOUNDED_TELEMETRY_PHASES = [
+    /** #1705: a deferred-format record whose origin worktree never claimed it. */
+    "agent_end_deferred_format_orphan_origin_mismatch",
+    /** #1713: a `textDocument`/`workspace` diagnostic pull abandoned at budget. */
+    "lsp_pull_diagnostic_timeout",
+    /** #1713: that abandoned pull answered anyway, too late to serve anyone. */
+    "lsp_pull_late_answer_discarded",
+    /** #1773: a pull skipped outright because the caller's budget was already
+     *  exhausted — never dispatched, so it must not be confused with a genuine
+     *  timeout. */
+    "lsp_pull_skipped_budget_exhausted",
+    /** #1774: an abandoned pull's request eventually REJECTED (e.g. a server
+     *  `ContentModified`) rather than answering or staying silent forever —
+     *  the third outcome late-answer telemetry previously could not see. */
+    "lsp_pull_late_rejection",
+    /** #1716: a hover/definition/references/etc. request abandoned at budget. */
+    "lsp_nav_request_timeout",
+    /** #1716: that abandoned nav request answered anyway, after the caller left. */
+    "lsp_nav_late_answer_discarded",
+    /**
+     * #1743 review: a per-file touch skipped a server in breaker cooldown or
+     * latched permanently broken. Fires once per file per touch during an
+     * outage, so it is rising-edge per (server, file).
+     */
+    "lsp_client_skipped_broken",
+    /** #1743 review: the same skip, for a temporarily unavailable command. */
+    "lsp_client_skipped_unavailable_command",
+    /**
+     * #1934: `getWarmClientForFile` found no live client for a file that has at
+     * least one language server with a resolvable root. Its callers run per
+     * file (the cascade quiet window, read expansion, `hasWarmLSP`), so it is
+     * rising-edge per candidate (server, root) set, with the ledger holding the
+     * exact count.
+     */
+    "lsp_warm_client_missing",
+    /**
+     * #1723: an event-loop block at or above the floor. Not a degradation, so
+     * no ledger kind; bounded by call cadence (one `turn_end` runs it once per
+     * turn) rather than by an option here.
+     */
+    "loop_block",
+    /**
+     * #1925: a session event skipped because its ctx was invalidated by a
+     * session replacement or reload. A replaced session can drain a whole
+     * queue of them, so it is rising-edge per event name.
+     */
+    "session_event_stale_ctx_skip",
+];
+const REGISTERED_PHASES = new Set(BOUNDED_TELEMETRY_PHASES);
+/** Report whether a phase name is in the registry (used by the sweep). */
+export function isBoundedTelemetryPhase(phase) {
+    return REGISTERED_PHASES.has(phase);
+}
+/**
+ * Per-turn admission counters, keyed by phase. Cleared lazily when a call
+ * observes a turn index different from the one the counters were built for,
+ * and eagerly by `resetBoundedTelemetry` at `session_start` (a new session
+ * restarts turn numbering at 0, so the lazy check alone could carry a stale
+ * count across a session boundary that happened to land on the same index).
+ */
+let turnCounts = new Map();
+let countedTurnIndex;
+/**
+ * Decide whether this occurrence earns a detailed record, and count it in the
+ * ledger either way. Returns `true` when the caller should write the record.
+ *
+ * Split out from `emitBounded` for the #1705 shape: that site loops over N
+ * abandoned records, admits each one, and then writes ONE batched
+ * `logLatency` naming only the admitted ones. A helper that could only emit
+ * per-call would have turned one record into N.
+ */
+export function admitBounded(phase, identity, options = {}) {
+    try {
+        let isRisingEdge = true;
+        if (options.ledgerKind !== undefined) {
+            // `subject` is the identity, unmodified: the ledger's per-subject
+            // entry is what tells a reader WHICH file or method is stuck after
+            // the detailed records stop.
+            isRisingEdge = incrementDegradationCount({
+                kind: options.ledgerKind,
+                subject: identity,
+                reason: options.reason ?? phase,
+            });
+        }
+        if (options.risingEdgePer !== undefined && !isRisingEdge)
+            return false;
+        return admitAgainstTurnCap(phase, options.capPerTurn);
+    }
+    catch {
+        // Telemetry must never break the observed path. Emitting is the safer
+        // failure: an extra record is noise, a swallowed one is a blind spot.
+        return true;
+    }
+}
+/**
+ * Count every occurrence in the ledger, then write ONE bounded `latency.log`
+ * record if this occurrence is admitted. Returns whether the record was
+ * written, so a caller can branch on it (all four migrated sites either
+ * ignore it or, in #1705's case, use `admitBounded` directly).
+ */
+export function emitBounded(phase, identity, payload, options = {}) {
+    try {
+        if (!admitBounded(phase, identity, options))
+            return false;
+        logLatency({
+            ...payload,
+            type: payload.type ?? "phase",
+            phase,
+            // `filePath` is what existing latency.log queries filter on, so a site
+            // may keep a coarser one; `metadata.identity` below always carries the
+            // full discriminating identity. Aggregation that loses WHICH subject
+            // is stuck is the failure AGENTS.md names.
+            filePath: payload.filePath ?? identity,
+            metadata: { ...payload.metadata, identity },
+        });
+        return true;
+    }
+    catch {
+        // Telemetry must never break the observed path.
+        return false;
+    }
+}
+/**
+ * Apply the per-turn ceiling. Separated so the turn-rollover clear happens in
+ * exactly one place: a cap and its reset drifting apart is how #1733's
+ * compensating-pair guards got past review.
+ */
+function admitAgainstTurnCap(phase, cap) {
+    if (cap === undefined)
+        return true;
+    if (countedTurnIndex !== cap.turnIndex) {
+        turnCounts = new Map();
+        countedTurnIndex = cap.turnIndex;
+    }
+    const used = turnCounts.get(phase) ?? 0;
+    if (used >= cap.limit)
+        return false;
+    turnCounts.set(phase, used + 1);
+    return true;
+}
+/**
+ * Session-boundary/test reset. The rising-edge state is NOT here — it lives
+ * in the degradation ledger, which `handleSessionStart` already re-arms via
+ * `resetDegradationLedger`. Only the per-turn counters are this module's own,
+ * and they need this because turn numbering restarts at 0 each session.
+ */
+export function resetBoundedTelemetry() {
+    turnCounts = new Map();
+    countedTurnIndex = undefined;
+}
+/** Test-only: the live per-turn admission count for a phase. */
+export function _boundedTurnCountForTest(phase) {
+    return turnCounts.get(phase) ?? 0;
+}