// SPEC: PJ2026-01060505 Workbench Performance draft-2026-06-17-p0
// Keeps browser-reported performance metrics low-cardinality before Prometheus export.

const DEFAULT_WEB_PERFORMANCE_BODY_LIMIT_BYTES = 64 * 1024;
const DURATION_BUCKETS_SECONDS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30];
const CLS_BUCKETS = [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5];
const WORKBENCH_JOURNEY_BUCKETS_SECONDS = [0.05, 0.1, 0.25, 0.5, 1, 2, 3, 5, 8, 13, 21, 30, 60, 120];
const WORKBENCH_EVENT_PHASE_BUCKETS_SECONDS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
const ALLOWED_KINDS = new Set(["navigation", "web_vital", "api", "long_task", "workbench_journey", "workbench_event_phase", "workbench_backend_event_visible"]);
const DURATION_METRICS = new Set([
  "navigation_ttfb",
  "navigation_dom_content_loaded",
  "navigation_load",
  "lcp",
  "inp",
  "fid",
  "api_request",
  "long_task"
]);
const WORKBENCH_SCHEMA_VERSION = "hwlab-web-performance-v2";
const WORKBENCH_JOURNEYS = new Set([
  "submit_to_first_visible",
  "submit_to_failure",
  "backend_event_to_visible",
  "session_switch_first_visible",
  "session_switch_full_load",
  "workbench_open_first_visible",
  "workbench_open_full_load"
]);
const WORKBENCH_EVENT_PHASES = new Set([
  "created_to_append",
  "append_to_sse",
  "sse_to_receive",
  "receive_to_project",
  "project_to_paint",
  "user_submit_to_api_accepted",
  "api_accepted_to_backend_event"
]);
const WORKBENCH_EVENT_TYPES = new Set(["assistant", "tool_call", "backend", "terminal", "error", "status", "request", "result", "unknown"]);
const WORKBENCH_TRANSPORTS = new Set(["sse", "rest_gap", "poll", "none", "unknown"]);
const WORKBENCH_OUTCOMES = new Set(["ok", "timeout", "error", "dropped", "stale", "partial", "empty", "network", "denied", "unknown"]);
const WORKBENCH_ENTRIES = new Set(["new", "existing", "steer", "retry", "unknown"]);
const WORKBENCH_VISIBILITY = new Set(["foreground", "background", "hidden", "unknown"]);
const WORKBENCH_CACHE_STATES = new Set(["warm", "cold", "unknown"]);
const WORKBENCH_TARGET_STATES = new Set(["running", "terminal", "empty", "unknown"]);
const WORKBENCH_SOURCES = new Set(["rail", "deeplink", "history", "direct", "hydrate", "unknown"]);
const WORKBENCH_AUTH_STATES = new Set(["warm", "login_redirect", "unknown"]);
const LOW_SAMPLE_THRESHOLD = 5;

interface WebPerformanceStoreOptions {
  env?: Record<string, unknown>;
  maxSeries?: number;
}

interface WebPerformancePayload {
  schemaVersion?: unknown;
  serviceId?: unknown;
  page?: unknown;
  events?: unknown;
}

interface WebPerformanceEvent {
  kind?: unknown;
  metric?: unknown;
  journey?: unknown;
  phase?: unknown;
  eventType?: unknown;
  backend?: unknown;
  transport?: unknown;
  entry?: unknown;
  visibility?: unknown;
  cache?: unknown;
  targetState?: unknown;
  source?: unknown;
  authState?: unknown;
  route?: unknown;
  valueMs?: unknown;
  value?: unknown;
  method?: unknown;
  status?: unknown;
  statusClass?: unknown;
  outcome?: unknown;
}

interface NormalizedPerformanceEvent {
  series: "web_duration" | "layout_shift" | "workbench_journey" | "workbench_event_phase" | "workbench_backend_event_visible";
  metric: string;
  value: number;
  labels: Record<string, string>;
  counterLabels?: Record<string, string>;
}

interface HistogramSeries {
  labels: Record<string, string>;
  buckets: number[];
  sum: number;
  count: number;
}

interface CounterSeries {
  labels: Record<string, string>;
  value: number;
}

interface PerformanceSummaryRow {
  kind: string;
  metric: string;
  route: string;
  method: string;
  statusClass: string;
  outcome: string;
  count: number;
  average: number;
  p50: number;
  p75: number;
  p95: number;
  unit: "seconds" | "score";
  tone: "ok" | "warn" | "blocked" | "source";
  problem: string;
  lowSample?: boolean;
  sampleState?: "ok" | "low-sample" | "empty";
  backend?: string;
  transport?: string;
  targetState?: string;
  cache?: string;
  source?: string;
  entry?: string;
  authState?: string;
  eventType?: string;
  phase?: string;
}

export function createWebPerformanceStore(options: WebPerformanceStoreOptions = {}) {
  const env = options.env ?? process.env;
  const maxSeries = parsePositiveInteger(env.HWLAB_WEB_PERFORMANCE_MAX_SERIES, options.maxSeries ?? 240);
  const durationSeries = new Map<string, HistogramSeries>();
  const clsSeries = new Map<string, HistogramSeries>();
  const sampleSeries = new Map<string, CounterSeries>();
  const droppedSeries = new Map<string, CounterSeries>();
  const journeyDurationSeries = new Map<string, HistogramSeries>();
  const journeyTotalSeries = new Map<string, CounterSeries>();
  const eventPhaseSeries = new Map<string, HistogramSeries>();
  const backendEventVisibleSeries = new Map<string, HistogramSeries>();
  const baseLabels = {
    service: "hwlab-cloud-web",
    namespace: sanitizeLabelValue(env.HWLAB_METRICS_NAMESPACE ?? env.POD_NAMESPACE ?? "hwlab-v02"),
    gitops_target: sanitizeLabelValue(env.HWLAB_GITOPS_TARGET ?? env.HWLAB_GITOPS_PROFILE ?? "v02")
  };

  function record(payload: WebPerformancePayload) {
    const events = Array.isArray(payload.events) ? payload.events.slice(0, 80) : [];
    let accepted = 0;
    let dropped = 0;
    for (const rawEvent of events) {
      const event = normalizeEvent(rawEvent, payload);
      if (!event) {
        incrementDropped("invalid_event");
        dropped += 1;
        continue;
      }
      if (!recordNormalizedEvent(event)) {
        incrementDropped("series_limit");
        dropped += 1;
        continue;
      }
      accepted += 1;
    }
    return { accepted, dropped, received: events.length };
  }

  function normalizeEvent(rawEvent: unknown, payload: WebPerformancePayload): NormalizedPerformanceEvent | null {
    if (!rawEvent || typeof rawEvent !== "object" || Array.isArray(rawEvent)) return null;
    const input = rawEvent as WebPerformanceEvent;
    const kind = sanitizeMetricName(input.kind, "unknown");
    if (!ALLOWED_KINDS.has(kind)) return null;
    if (kind === "workbench_journey") return normalizeWorkbenchJourneyEvent(input, payload);
    if (kind === "workbench_event_phase") return normalizeWorkbenchEventPhase(input, payload);
    if (kind === "workbench_backend_event_visible") return normalizeWorkbenchBackendEventVisible(input, payload);
    const metric = sanitizeMetricName(input.metric, "unknown");
    const isCls = metric === "cls";
    if (!isCls && !DURATION_METRICS.has(metric)) return null;
    const rawValue = isCls ? finiteNumber(input.value, NaN) : finiteNumber(input.valueMs, NaN) / 1000;
    if (!Number.isFinite(rawValue) || rawValue < 0) return null;
    const value = isCls ? Math.min(rawValue, 10) : Math.min(rawValue, 120);
    const route = webPerformanceRouteTemplate(input.route ?? payload.page ?? "/workspace");
    const pageRoute = webPerformanceRouteTemplate(payload.page ?? "/workspace");
    if (isObservabilityNoise({ kind, metric, route, pageRoute })) return null;
    const labels = {
      ...baseLabels,
      kind,
      metric,
      route,
      method: normalizeMethod(input.method),
      status_class: normalizeStatusClass(input.statusClass ?? (input.status === undefined || input.status === null ? "unknown" : statusClass(input.status))),
      outcome: sanitizeLabelValue(input.outcome ?? "ok", "ok")
    };
    return { series: isCls ? "layout_shift" : "web_duration", metric, value, labels, counterLabels: sampleLabels(labels) };
  }

  function normalizeWorkbenchJourneyEvent(input: WebPerformanceEvent, payload: WebPerformancePayload): NormalizedPerformanceEvent | null {
    if (String(payload.schemaVersion ?? "") !== WORKBENCH_SCHEMA_VERSION) return null;
    const journey = requiredEnum(input.journey ?? input.metric, WORKBENCH_JOURNEYS);
    if (!journey) return null;
    const value = durationValueSeconds(input.valueMs, 120);
    if (value === null) return null;
    const route = webPerformanceRouteTemplate(input.route ?? payload.page ?? "/workbench");
    const pageRoute = webPerformanceRouteTemplate(payload.page ?? "/workbench");
    if (isObservabilityNoise({ kind: "workbench_journey", metric: journey, route, pageRoute })) return null;
    const labels = {
      ...baseLabels,
      journey,
      route,
      entry: optionalEnum(input.entry, WORKBENCH_ENTRIES, "unknown"),
      source: optionalEnum(input.source, WORKBENCH_SOURCES, "unknown"),
      target_state: optionalEnum(input.targetState ?? field(input, "target_state"), WORKBENCH_TARGET_STATES, "unknown"),
      cache: optionalEnum(input.cache, WORKBENCH_CACHE_STATES, "unknown"),
      auth_state: optionalEnum(input.authState ?? field(input, "auth_state"), WORKBENCH_AUTH_STATES, "unknown"),
      backend: normalizeBackendLabel(input.backend),
      transport: optionalEnum(input.transport, WORKBENCH_TRANSPORTS, "unknown"),
      visibility: optionalEnum(input.visibility, WORKBENCH_VISIBILITY, "unknown"),
      outcome: optionalEnum(input.outcome, WORKBENCH_OUTCOMES, "ok")
    };
    return { series: "workbench_journey", metric: journey, value, labels, counterLabels: labels };
  }

  function normalizeWorkbenchEventPhase(input: WebPerformanceEvent, payload: WebPerformancePayload): NormalizedPerformanceEvent | null {
    if (String(payload.schemaVersion ?? "") !== WORKBENCH_SCHEMA_VERSION) return null;
    const phase = requiredEnum(input.phase ?? input.metric, WORKBENCH_EVENT_PHASES);
    if (!phase) return null;
    const value = durationValueSeconds(input.valueMs, 30);
    if (value === null) return null;
    const labels = {
      ...baseLabels,
      phase,
      event_type: normalizeEventType(input.eventType ?? field(input, "event_type")),
      backend: normalizeBackendLabel(input.backend),
      transport: optionalEnum(input.transport, WORKBENCH_TRANSPORTS, "unknown"),
      outcome: optionalEnum(input.outcome, WORKBENCH_OUTCOMES, "ok")
    };
    return { series: "workbench_event_phase", metric: phase, value, labels };
  }

  function normalizeWorkbenchBackendEventVisible(input: WebPerformanceEvent, payload: WebPerformancePayload): NormalizedPerformanceEvent | null {
    if (String(payload.schemaVersion ?? "") !== WORKBENCH_SCHEMA_VERSION) return null;
    const value = durationValueSeconds(input.valueMs, 120);
    if (value === null) return null;
    const labels = {
      ...baseLabels,
      event_type: normalizeEventType(input.eventType ?? field(input, "event_type")),
      backend: normalizeBackendLabel(input.backend),
      transport: optionalEnum(input.transport, WORKBENCH_TRANSPORTS, "unknown"),
      outcome: optionalEnum(input.outcome, WORKBENCH_OUTCOMES, "ok")
    };
    return { series: "workbench_backend_event_visible", metric: "backend_event_to_visible", value, labels };
  }

  function recordNormalizedEvent(event: NormalizedPerformanceEvent) {
    if (event.series === "layout_shift") return recordHistogramWithCounter(clsSeries, sampleSeries, event.labels, event.counterLabels ?? sampleLabels(event.labels), event.value, CLS_BUCKETS);
    if (event.series === "web_duration") return recordHistogramWithCounter(durationSeries, sampleSeries, event.labels, event.counterLabels ?? sampleLabels(event.labels), event.value, DURATION_BUCKETS_SECONDS);
    if (event.series === "workbench_journey") return recordHistogramWithCounter(journeyDurationSeries, journeyTotalSeries, event.labels, event.counterLabels ?? event.labels, event.value, WORKBENCH_JOURNEY_BUCKETS_SECONDS);
    if (event.series === "workbench_event_phase") return recordHistogram(eventPhaseSeries, event.labels, event.value, WORKBENCH_EVENT_PHASE_BUCKETS_SECONDS, maxSeries);
    return recordHistogram(backendEventVisibleSeries, event.labels, event.value, WORKBENCH_JOURNEY_BUCKETS_SECONDS, maxSeries);
  }

  function recordHistogramWithCounter(histograms: Map<string, HistogramSeries>, counters: Map<string, CounterSeries>, histogramLabels: Record<string, string>, counterLabels: Record<string, string>, value: number, buckets: number[]) {
    if (!canRecordSeries(histograms, histogramLabels, maxSeries) || !canRecordSeries(counters, counterLabels, maxSeries)) return false;
    recordHistogram(histograms, histogramLabels, value, buckets, maxSeries);
    incrementCounter(counters, counterLabels, maxSeries);
    return true;
  }

  function incrementDropped(reason: string) {
    incrementCounter(droppedSeries, { ...baseLabels, reason }, Math.max(maxSeries, 16));
  }

  function metricsText() {
    const lines = [
      "# HELP hwlab_webui_performance_sample_total Browser-observed HWLAB Cloud Web performance samples accepted by cloud-api.",
      "# TYPE hwlab_webui_performance_sample_total counter",
      ...renderCounters("hwlab_webui_performance_sample_total", sampleSeries),
      "# HELP hwlab_webui_performance_duration_seconds Browser-observed HWLAB Cloud Web duration metrics in seconds.",
      "# TYPE hwlab_webui_performance_duration_seconds histogram",
      ...renderHistogram("hwlab_webui_performance_duration_seconds", durationSeries, DURATION_BUCKETS_SECONDS),
      "# HELP hwlab_webui_layout_shift_score Browser-observed cumulative layout shift score.",
      "# TYPE hwlab_webui_layout_shift_score histogram",
      ...renderHistogram("hwlab_webui_layout_shift_score", clsSeries, CLS_BUCKETS),
      "# HELP hwlab_webui_performance_dropped_total Browser performance samples dropped before Prometheus export.",
      "# TYPE hwlab_webui_performance_dropped_total counter",
      ...renderCounters("hwlab_webui_performance_dropped_total", droppedSeries),
      "# HELP hwlab_workbench_journey_total Browser-observed HWLAB Workbench journey samples accepted by cloud-api.",
      "# TYPE hwlab_workbench_journey_total counter",
      ...renderCounters("hwlab_workbench_journey_total", journeyTotalSeries),
      "# HELP hwlab_workbench_journey_duration_seconds Browser-observed HWLAB Workbench user-visible journey durations in seconds.",
      "# TYPE hwlab_workbench_journey_duration_seconds histogram",
      ...renderHistogram("hwlab_workbench_journey_duration_seconds", journeyDurationSeries, WORKBENCH_JOURNEY_BUCKETS_SECONDS),
      "# HELP hwlab_workbench_event_phase_duration_seconds Browser/backend phase durations for HWLAB Workbench events in seconds.",
      "# TYPE hwlab_workbench_event_phase_duration_seconds histogram",
      ...renderHistogram("hwlab_workbench_event_phase_duration_seconds", eventPhaseSeries, WORKBENCH_EVENT_PHASE_BUCKETS_SECONDS),
      "# HELP hwlab_workbench_backend_event_visible_latency_seconds Agent backend event generated to browser-visible latency in seconds.",
      "# TYPE hwlab_workbench_backend_event_visible_latency_seconds histogram",
      ...renderHistogram("hwlab_workbench_backend_event_visible_latency_seconds", backendEventVisibleSeries, WORKBENCH_JOURNEY_BUCKETS_SECONDS),
      ""
    ];
    return lines.join("\n");
  }

  function summary() {
    const durationRows = histogramSummaryRows(durationSeries, DURATION_BUCKETS_SECONDS, "seconds");
    const clsRows = histogramSummaryRows(clsSeries, CLS_BUCKETS, "score");
    const rows = [...durationRows, ...clsRows];
    const workbenchJourneys = workbenchJourneySummaryRows(journeyDurationSeries, WORKBENCH_JOURNEY_BUCKETS_SECONDS)
      .sort(sortByProblemThenP95)
      .slice(0, 24);
    const workbenchEventPhases = workbenchEventPhaseSummaryRows(eventPhaseSeries, WORKBENCH_EVENT_PHASE_BUCKETS_SECONDS)
      .sort(sortByProblemThenP95)
      .slice(0, 24);
    const workbenchBackendEvents = workbenchBackendEventVisibleSummaryRows(backendEventVisibleSeries, WORKBENCH_JOURNEY_BUCKETS_SECONDS)
      .sort(sortByProblemThenP95)
      .slice(0, 24);
    const workbenchRows = [...workbenchJourneys, ...workbenchEventPhases, ...workbenchBackendEvents];
    const apiRoutes = durationRows
      .filter((row) => row.metric === "api_request")
      .sort(sortByProblemThenP95)
      .slice(0, 12);
    const webVitals = rows
      .filter((row) => row.kind === "web_vital" || row.metric.startsWith("navigation_"))
      .sort(sortByProblemThenP95)
      .slice(0, 12);
    const longTasks = durationRows
      .filter((row) => row.metric === "long_task")
      .sort(sortByProblemThenP95)
      .slice(0, 12);
    const problems = [...rows, ...workbenchRows]
      .filter((row) => row.tone === "blocked" || row.tone === "warn" || row.outcome !== "ok" || row.lowSample === true)
      .sort(sortByProblemThenP95)
      .slice(0, 16);
    const sampleCount = [...sampleSeries.values()].reduce((sum, entry) => sum + entry.value, 0);
    const workbenchSampleCount = [...journeyTotalSeries.values()].reduce((sum, entry) => sum + entry.value, 0)
      + histogramSampleCount(eventPhaseSeries)
      + histogramSampleCount(backendEventVisibleSeries);
    const totalSampleCount = sampleCount + workbenchSampleCount;
    return {
      serviceId: "hwlab-cloud-api",
      route: "/v1/web-performance/summary",
      source: "cloud-api-rum-store",
      observedAt: new Date().toISOString(),
      namespace: baseLabels.namespace,
      gitopsTarget: baseLabels.gitops_target,
      summary: {
        sampleCount: totalSampleCount,
        sampleSeries: sampleSeries.size,
        durationSeries: durationSeries.size,
        clsSeries: clsSeries.size,
        droppedSeries: droppedSeries.size,
        workbenchJourneySeries: journeyDurationSeries.size,
        workbenchEventPhaseSeries: eventPhaseSeries.size,
        workbenchBackendEventVisibleSeries: backendEventVisibleSeries.size,
        routeCount: new Set([...rows, ...workbenchRows].map((row) => row.route)).size,
        problemCount: problems.length,
        status: totalSampleCount === 0 ? "waiting" : totalSampleCount < 10 ? "warming" : problems.length > 0 ? "watch" : "ok",
        lowSampleThreshold: LOW_SAMPLE_THRESHOLD
      },
      apiRoutes,
      webVitals,
      longTasks,
      problems,
      workbenchJourneys,
      workbenchEventPhases,
      workbenchBackendEvents,
      workbenchRows: workbenchRows.sort(sortByProblemThenP95).slice(0, 40),
      rows: rows.sort(sortByProblemThenP95).slice(0, 40)
    };
  }

  function snapshot() {
    return {
      sampleSeries: sampleSeries.size,
      durationSeries: durationSeries.size,
      clsSeries: clsSeries.size,
      droppedSeries: droppedSeries.size,
      workbenchJourneySeries: journeyDurationSeries.size,
      workbenchEventPhaseSeries: eventPhaseSeries.size,
      workbenchBackendEventVisibleSeries: backendEventVisibleSeries.size,
      sampleCount: [...sampleSeries.values()].reduce((sum, entry) => sum + entry.value, 0)
        + [...journeyTotalSeries.values()].reduce((sum, entry) => sum + entry.value, 0)
        + histogramSampleCount(eventPhaseSeries)
        + histogramSampleCount(backendEventVisibleSeries)
    };
  }

  return { record, metricsText, snapshot, summary };
}

export async function handleWebPerformanceIngestHttp(request, response, options = {}) {
  const body = await readBody(request, options.bodyLimitBytes ?? DEFAULT_WEB_PERFORMANCE_BODY_LIMIT_BYTES);
  let payload;
  try {
    payload = body ? JSON.parse(body) : {};
  } catch (error) {
    sendJson(response, 400, { accepted: false, error: { code: "parse_error", message: "Invalid web performance JSON body", reason: error.message } });
    return;
  }
  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
    sendJson(response, 400, { accepted: false, error: { code: "invalid_params", message: "web performance body must be a JSON object" } });
    return;
  }
  const result = options.store.record(payload);
  sendJson(response, 202, { accepted: true, ...result });
}

export function handleWebPerformanceMetricsHttp(request, response, options = {}) {
  if (!isLoopbackMetricsRequest(request)) {
    sendJson(response, 404, { error: { code: "not_found", message: "route is not public" } });
    return;
  }
  const primary = String(options.store.metricsText() ?? "").trimEnd();
  const extra = typeof options.extraMetricsText === "function"
    ? String(options.extraMetricsText() ?? "").trimEnd()
    : String(options.extraMetricsText ?? "").trimEnd();
  const payload = [primary, extra].filter(Boolean).join("\n") + "\n";
  response.writeHead(200, {
    "content-type": "text/plain; version=0.0.4; charset=utf-8",
    "content-length": Buffer.byteLength(payload)
  });
  response.end(payload);
}

export function handleWebPerformanceSummaryHttp(_request, response, options = {}) {
  sendJson(response, 200, options.store.summary());
}

export function webPerformanceRouteTemplate(input: unknown): string {
  const raw = String(input ?? "").trim() || "/";
  const normalizedRaw = raw.startsWith("#") ? raw.slice(1) || "/" : raw;
  const pathOnly = normalizedRaw.split(/[?#]/u, 1)[0] || "/";
  let pathname = pathOnly;
  try {
    pathname = new URL(normalizedRaw, "http://hwlab.local").pathname || pathOnly;
  } catch {
    // Keep pathOnly.
  }
  const parts = pathname.split("/").filter(Boolean).map((part) => routeSegmentTemplate(safeDecode(part)));
  const path = `/${parts.join("/")}`;
  return path.length > 120 ? `${path.slice(0, 117)}...` : path;
}

function sampleLabels(labels: Record<string, string>) {
  return {
    service: labels.service,
    namespace: labels.namespace,
    gitops_target: labels.gitops_target,
    kind: labels.kind,
    metric: labels.metric,
    route: labels.route,
    method: labels.method,
    status_class: labels.status_class,
    outcome: labels.outcome
  };
}

function isObservabilityNoise(event: { kind: string; metric: string; route: string; pageRoute: string }) {
  if (event.pageRoute === "/performance") return true;
  if (event.route === "/performance" && (event.kind === "navigation" || event.kind === "web_vital" || event.kind === "long_task")) return true;
  return event.route === "/v1/web-performance" || event.route.startsWith("/v1/web-performance/");
}

function canRecordSeries(series: Map<string, HistogramSeries | CounterSeries>, labels: Record<string, string>, maxSeries: number) {
  const key = stableLabelKey(labels);
  return series.has(key) || series.size < maxSeries;
}

function recordHistogram(series: Map<string, HistogramSeries>, labels: Record<string, string>, value: number, buckets: number[], maxSeries: number) {
  const key = stableLabelKey(labels);
  let entry = series.get(key);
  if (!entry) {
    if (series.size >= maxSeries) return false;
    entry = { labels, buckets: buckets.map(() => 0), sum: 0, count: 0 };
    series.set(key, entry);
  }
  for (let index = 0; index < buckets.length; index += 1) {
    if (value <= buckets[index]) entry.buckets[index] += 1;
  }
  entry.sum += value;
  entry.count += 1;
  return true;
}

function incrementCounter(series: Map<string, CounterSeries>, labels: Record<string, string>, maxSeries: number) {
  const key = stableLabelKey(labels);
  let entry = series.get(key);
  if (!entry) {
    if (series.size >= maxSeries) return false;
    entry = { labels, value: 0 };
    series.set(key, entry);
  }
  entry.value += 1;
  return true;
}

function histogramSampleCount(series: Map<string, HistogramSeries>) {
  return [...series.values()].reduce((sum, entry) => sum + entry.count, 0);
}

function renderCounters(metricName: string, series: Map<string, CounterSeries>) {
  return [...series.values()].map((entry) => `${metricName}{${renderLabels(entry.labels)}} ${entry.value}`);
}

function renderHistogram(metricName: string, series: Map<string, HistogramSeries>, buckets: number[]) {
  const lines: string[] = [];
  for (const entry of series.values()) {
    for (let index = 0; index < buckets.length; index += 1) {
      lines.push(`${metricName}_bucket{${renderLabels({ ...entry.labels, le: String(buckets[index]) })}} ${entry.buckets[index]}`);
    }
    lines.push(`${metricName}_bucket{${renderLabels({ ...entry.labels, le: "+Inf" })}} ${entry.count}`);
    lines.push(`${metricName}_sum{${renderLabels(entry.labels)}} ${entry.sum.toFixed(6)}`);
    lines.push(`${metricName}_count{${renderLabels(entry.labels)}} ${entry.count}`);
  }
  return lines;
}

function histogramSummaryRows(series: Map<string, HistogramSeries>, buckets: number[], unit: "seconds" | "score"): PerformanceSummaryRow[] {
  return [...series.values()].map((entry) => {
    const labels = entry.labels;
    const count = entry.count;
    const average = count > 0 ? entry.sum / count : 0;
    const p50 = histogramQuantile(entry, buckets, 0.5);
    const p75 = histogramQuantile(entry, buckets, 0.75);
    const p95 = histogramQuantile(entry, buckets, 0.95);
    const tone = performanceTone(labels, p95, count, unit);
    return {
      kind: labels.kind,
      metric: labels.metric,
      route: labels.route,
      method: labels.method,
      statusClass: labels.status_class,
      outcome: labels.outcome,
      count,
      average: roundMetric(average),
      p50: roundMetric(p50),
      p75: roundMetric(p75),
      p95: roundMetric(p95),
      unit,
      tone,
      problem: performanceProblem(labels, p95, count, unit, tone),
      lowSample: count > 0 && count < LOW_SAMPLE_THRESHOLD,
      sampleState: sampleState(count)
    };
  });
}

function workbenchJourneySummaryRows(series: Map<string, HistogramSeries>, buckets: number[]): PerformanceSummaryRow[] {
  return [...series.values()].map((entry) => {
    const labels = entry.labels;
    const metric = labels.journey;
    const row = workbenchSummaryRow(entry, buckets, {
      kind: "workbench_journey",
      metric,
      route: labels.route,
      outcome: labels.outcome,
      backend: labels.backend,
      transport: labels.transport,
      targetState: labels.target_state,
      cache: labels.cache,
      source: labels.source,
      entry: labels.entry,
      authState: labels.auth_state,
      warn: workbenchJourneyThreshold(metric).warn,
      blocked: workbenchJourneyThreshold(metric).blocked
    });
    return row;
  });
}

function workbenchEventPhaseSummaryRows(series: Map<string, HistogramSeries>, buckets: number[]): PerformanceSummaryRow[] {
  return [...series.values()].map((entry) => {
    const labels = entry.labels;
    const metric = labels.phase;
    const threshold = workbenchEventPhaseThreshold(metric);
    return workbenchSummaryRow(entry, buckets, {
      kind: "workbench_event_phase",
      metric,
      route: "workbench-events",
      outcome: labels.outcome,
      backend: labels.backend,
      transport: labels.transport,
      eventType: labels.event_type,
      phase: labels.phase,
      warn: threshold.warn,
      blocked: threshold.blocked
    });
  });
}

function workbenchBackendEventVisibleSummaryRows(series: Map<string, HistogramSeries>, buckets: number[]): PerformanceSummaryRow[] {
  return [...series.values()].map((entry) => {
    const labels = entry.labels;
    const threshold = workbenchJourneyThreshold("backend_event_to_visible");
    return workbenchSummaryRow(entry, buckets, {
      kind: "workbench_backend_event_visible",
      metric: "backend_event_to_visible",
      route: "workbench-events",
      outcome: labels.outcome,
      backend: labels.backend,
      transport: labels.transport,
      eventType: labels.event_type,
      warn: threshold.warn,
      blocked: threshold.blocked
    });
  });
}

function workbenchSummaryRow(entry: HistogramSeries, buckets: number[], input: {
  kind: string;
  metric: string;
  route: string;
  outcome: string;
  warn: number;
  blocked: number;
  backend?: string;
  transport?: string;
  targetState?: string;
  cache?: string;
  source?: string;
  entry?: string;
  authState?: string;
  eventType?: string;
  phase?: string;
}): PerformanceSummaryRow {
  const count = entry.count;
  const average = count > 0 ? entry.sum / count : 0;
  const p50 = histogramQuantile(entry, buckets, 0.5);
  const p75 = histogramQuantile(entry, buckets, 0.75);
  const p95 = histogramQuantile(entry, buckets, 0.95);
  const lowSample = count > 0 && count < LOW_SAMPLE_THRESHOLD;
  const tone = workbenchTone(input.outcome, p95, count, input.warn, input.blocked);
  return {
    kind: input.kind,
    metric: input.metric,
    route: input.route,
    method: "-",
    statusClass: "-",
    outcome: input.outcome,
    count,
    average: roundMetric(average),
    p50: roundMetric(p50),
    p75: roundMetric(p75),
    p95: roundMetric(p95),
    unit: "seconds",
    tone,
    problem: workbenchProblem(input.outcome, input.metric, count, tone),
    lowSample,
    sampleState: sampleState(count),
    backend: input.backend,
    transport: input.transport,
    targetState: input.targetState,
    cache: input.cache,
    source: input.source,
    entry: input.entry,
    authState: input.authState,
    eventType: input.eventType,
    phase: input.phase
  };
}

function histogramQuantile(entry: HistogramSeries, buckets: number[], quantile: number) {
  if (entry.count <= 0) return 0;
  const rank = Math.max(1, Math.ceil(entry.count * quantile));
  for (let index = 0; index < entry.buckets.length; index += 1) {
    if (entry.buckets[index] >= rank) return buckets[index];
  }
  return buckets[buckets.length - 1] ?? 0;
}

function performanceTone(labels: Record<string, string>, p95: number, count: number, unit: "seconds" | "score") {
  if (labels.outcome !== "ok" || labels.status_class === "network" || labels.status_class === "5xx") return "blocked";
  if (labels.status_class === "4xx") return "warn";
  if (count <= 0) return "source";
  const metric = labels.metric;
  if (unit === "score") {
    if (p95 >= 0.25) return "blocked";
    if (p95 >= 0.1) return "warn";
    return "ok";
  }
  if (metric === "lcp") return thresholdTone(p95, 2.5, 4);
  if (metric === "inp" || metric === "fid") return thresholdTone(p95, 0.2, 0.5);
  if (metric === "api_request") return thresholdTone(p95, 1, 2.5);
  if (metric === "long_task") return thresholdTone(p95, 0.2, 0.5);
  if (metric === "navigation_dom_content_loaded") return thresholdTone(p95, 2, 4);
  if (metric === "navigation_load") return thresholdTone(p95, 3, 6);
  if (metric === "navigation_ttfb") return thresholdTone(p95, 0.8, 1.8);
  return p95 > 1 ? "warn" : "ok";
}

function workbenchTone(outcome: string, p95: number, count: number, warn: number, blocked: number) {
  if (outcome !== "ok") return "blocked";
  if (count <= 0 || count < LOW_SAMPLE_THRESHOLD) return "source";
  return thresholdTone(p95, warn, blocked);
}

function workbenchJourneyThreshold(metric: string) {
  if (metric === "session_switch_first_visible") return { warn: 1, blocked: 3 };
  if (metric === "session_switch_full_load") return { warn: 2.5, blocked: 8 };
  if (metric === "workbench_open_first_visible") return { warn: 2.5, blocked: 5 };
  if (metric === "workbench_open_full_load") return { warn: 5, blocked: 13 };
  if (metric === "backend_event_to_visible") return { warn: 3, blocked: 10 };
  return { warn: 5, blocked: 15 };
}

function workbenchEventPhaseThreshold(metric: string) {
  if (metric === "append_to_sse") return { warn: 0.25, blocked: 1 };
  if (metric === "created_to_append" || metric === "receive_to_project" || metric === "project_to_paint") return { warn: 0.5, blocked: 2 };
  if (metric === "sse_to_receive") return { warn: 1, blocked: 3 };
  if (metric === "user_submit_to_api_accepted") return { warn: 1, blocked: 3 };
  return { warn: 5, blocked: 15 };
}

function thresholdTone(value: number, warn: number, blocked: number) {
  if (value >= blocked) return "blocked";
  if (value >= warn) return "warn";
  return "ok";
}

function performanceProblem(labels: Record<string, string>, p95: number, count: number, unit: "seconds" | "score", tone: string) {
  if (count <= 0) return "no-sample";
  if (labels.outcome !== "ok") return labels.outcome;
  if (labels.status_class === "network") return "network";
  if (labels.status_class === "5xx") return "server-error";
  if (labels.status_class === "4xx") return "client-error";
  if (tone === "blocked" || tone === "warn") return unit === "score" ? "layout-shift" : `slow-${labels.metric}`;
  return "ok";
}

function workbenchProblem(outcome: string, metric: string, count: number, tone: string) {
  if (count <= 0) return "no-sample";
  if (count < LOW_SAMPLE_THRESHOLD) return "low-sample";
  if (outcome !== "ok") return outcome;
  if (tone === "blocked" || tone === "warn") return `slow-${metric}`;
  return "ok";
}

function sampleState(count: number): "ok" | "low-sample" | "empty" {
  if (count <= 0) return "empty";
  return count < LOW_SAMPLE_THRESHOLD ? "low-sample" : "ok";
}

function sortByProblemThenP95(left: PerformanceSummaryRow, right: PerformanceSummaryRow) {
  return toneWeight(right.tone) - toneWeight(left.tone) || right.p95 - left.p95 || right.count - left.count;
}

function toneWeight(tone: string) {
  if (tone === "blocked") return 4;
  if (tone === "warn") return 3;
  if (tone === "ok") return 2;
  return 1;
}

function roundMetric(value: number) {
  if (!Number.isFinite(value)) return 0;
  return Math.round(value * 10000) / 10000;
}

function renderLabels(labels: Record<string, string>) {
  return Object.entries(labels)
    .map(([key, value]) => `${key}="${escapeLabelValue(value)}"`)
    .join(",");
}

function stableLabelKey(labels: Record<string, string>) {
  return Object.entries(labels).map(([key, value]) => `${key}=${value}`).join("\u0001");
}

function isLoopbackMetricsRequest(request) {
  const remoteAddress = String(request.socket?.remoteAddress ?? "");
  const host = String(request.headers?.host ?? "").trim().toLowerCase();
  const loopbackRemote = remoteAddress === "127.0.0.1" || remoteAddress === "::1" || remoteAddress === "::ffff:127.0.0.1";
  const loopbackHost = /^(?:127\.0\.0\.1|localhost)(?::\d+)?$/u.test(host);
  return loopbackRemote && loopbackHost;
}

function routeSegmentTemplate(segment: string): string {
  if (/^(?:trc|trace|thread|run|cmd|job|ses|cnv|conv|gws|box|res|pod|dp|usr)[_-]/iu.test(segment)) return ":id";
  if (/^[0-9a-f]{8,}(?:-[0-9a-f]{4,}){2,}$/iu.test(segment)) return ":uuid";
  if (/^[A-Za-z0-9_-]{20,}$/u.test(segment)) return ":id";
  if (/^\d{5,}$/u.test(segment)) return ":id";
  return sanitizeLabelValue(segment, "_");
}

function sanitizeMetricName(value: unknown, fallback: string) {
  const text = String(value ?? "").trim().toLowerCase().replace(/[^a-z0-9_:-]/gu, "_").slice(0, 64);
  return text || fallback;
}

function sanitizeLabelValue(value: unknown, fallback = "unknown") {
  const text = String(value ?? "").trim();
  const sanitized = text.replace(/[^A-Za-z0-9_.:/-]/gu, "_").slice(0, 120);
  return sanitized || fallback;
}

function requiredEnum(value: unknown, allowed: Set<string>) {
  const text = sanitizeMetricName(value, "");
  return allowed.has(text) ? text : null;
}

function optionalEnum(value: unknown, allowed: Set<string>, fallback: string) {
  const text = sanitizeMetricName(value, fallback);
  return allowed.has(text) ? text : fallback;
}

function normalizeEventType(value: unknown) {
  const text = sanitizeMetricName(value, "unknown");
  const aliased = text === "assistant_message" ? "assistant" : text === "tool" ? "tool_call" : text;
  return WORKBENCH_EVENT_TYPES.has(aliased) ? aliased : "unknown";
}

function normalizeBackendLabel(value: unknown) {
  const sanitized = sanitizeLabelValue(String(value ?? "unknown").trim().toLowerCase(), "unknown").slice(0, 64);
  if (!sanitized || looksHighCardinalityLabel(sanitized)) return "unknown";
  return sanitized;
}

function looksHighCardinalityLabel(value: string) {
  return /(?:^|[^a-z0-9])(?:trc|trace|thread|run|cmd|command|job|ses|session|cnv|conv|conversation|gws|box|res|pod|dp|usr|user)[_-][a-z0-9_-]{6,}/iu.test(value)
    || /^[0-9a-f]{8,}(?:-[0-9a-f]{4,}){2,}$/iu.test(value)
    || /^[A-Za-z0-9_-]{24,}$/u.test(value);
}

function durationValueSeconds(valueMs: unknown, maxSeconds: number) {
  const seconds = finiteNumber(valueMs, NaN) / 1000;
  if (!Number.isFinite(seconds) || seconds < 0) return null;
  return Math.min(seconds, maxSeconds);
}

function field(input: unknown, key: string) {
  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
  return (input as Record<string, unknown>)[key];
}

function escapeLabelValue(value: unknown) {
  return String(value ?? "").replace(/\\/gu, "\\\\").replace(/\n/gu, "\\n").replace(/"/gu, "\\\"");
}

function normalizeMethod(value: unknown) {
  const method = String(value ?? "NONE").trim().toUpperCase();
  return /^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/u.test(method) ? method : "NONE";
}

function normalizeStatusClass(value: unknown) {
  const text = String(value ?? "unknown").trim().toLowerCase();
  if (/^[1-5]xx$/u.test(text)) return text;
  if (text === "network" || text === "unknown") return text;
  return "unknown";
}

function statusClass(value: unknown) {
  const status = finiteNumber(value, 0);
  if (status >= 100 && status < 600) return `${Math.floor(status / 100)}xx`;
  if (status === 0) return "network";
  return "unknown";
}

function finiteNumber(value: unknown, fallback: number) {
  const number = typeof value === "number" ? value : Number(value);
  return Number.isFinite(number) ? number : fallback;
}

function parsePositiveInteger(value: unknown, fallback: number) {
  const number = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
  return Number.isInteger(number) && number > 0 ? number : fallback;
}

function safeDecode(value: string) {
  try {
    return decodeURIComponent(value);
  } catch {
    return value;
  }
}

function readBody(request, limitBytes) {
  const limit = Number.isInteger(limitBytes) && limitBytes > 0 ? limitBytes : DEFAULT_WEB_PERFORMANCE_BODY_LIMIT_BYTES;
  return new Promise((resolve, reject) => {
    let body = "";
    request.setEncoding("utf8");
    request.on("data", (chunk) => {
      body += chunk;
      if (Buffer.byteLength(body, "utf8") > limit) {
        request.destroy(new Error(`request body exceeds ${limit} bytes`));
      }
    });
    request.on("end", () => resolve(body));
    request.on("error", reject);
  });
}

function sendJson(response, statusCode, body) {
  response.writeHead(statusCode, {
    "content-type": "application/json; charset=utf-8",
    "cache-control": "no-store"
  });
  response.end(`${JSON.stringify(body)}\n`);
}