@malloy-publisher/server 0.0.226 → 0.0.227

package/src/pg_helpers.spec.ts

@@ -1,105 +1,5 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { ConnectionAuthError } from "./errors";
-import {
-   classifyPgError,
-   handlePgAttachError,
-   pgConnectTimeoutSeconds,
-   redactPgSecrets,
-   withPgConnectTimeout,
-} from "./pg_helpers";
-
-describe("pgConnectTimeoutSeconds", () => {
-   const ORIGINAL_TIMEOUT = process.env.PG_CONNECT_TIMEOUT_SECONDS;
-
-   afterEach(() => {
-      if (ORIGINAL_TIMEOUT === undefined) {
-         delete process.env.PG_CONNECT_TIMEOUT_SECONDS;
-      } else {
-         process.env.PG_CONNECT_TIMEOUT_SECONDS = ORIGINAL_TIMEOUT;
-      }
-   });
-
-   it("defaults to 5 when env unset", () => {
-      delete process.env.PG_CONNECT_TIMEOUT_SECONDS;
-      expect(pgConnectTimeoutSeconds()).toBe(5);
-   });
-
-   it("honors PG_CONNECT_TIMEOUT_SECONDS override", () => {
-      process.env.PG_CONNECT_TIMEOUT_SECONDS = "12";
-      expect(pgConnectTimeoutSeconds()).toBe(12);
-   });
-
-   it("falls back to 5 when env value is invalid", () => {
-      process.env.PG_CONNECT_TIMEOUT_SECONDS = "not-a-number";
-      expect(pgConnectTimeoutSeconds()).toBe(5);
-   });
-
-   it("falls back to 5 when env value is zero or negative", () => {
-      process.env.PG_CONNECT_TIMEOUT_SECONDS = "0";
-      expect(pgConnectTimeoutSeconds()).toBe(5);
-      process.env.PG_CONNECT_TIMEOUT_SECONDS = "-3";
-      expect(pgConnectTimeoutSeconds()).toBe(5);
-   });
-});
-
-describe("withPgConnectTimeout", () => {
-   it("appends to keyword form when missing", () => {
-      expect(withPgConnectTimeout("host=h dbname=d user=u password=p", 5)).toBe(
-         "host=h dbname=d user=u password=p connect_timeout=5",
-      );
-   });
-
-   it("appends to postgres: keyword form (DuckLake catalogUrl shape)", () => {
-      expect(
-         withPgConnectTimeout("postgres:host=h user=u password=p dbname=d", 5),
-      ).toBe("postgres:host=h user=u password=p dbname=d connect_timeout=5");
-   });
-
-   it("does not override a user-supplied connect_timeout in keyword form", () => {
-      expect(withPgConnectTimeout("host=h connect_timeout=30", 99)).toBe(
-         "host=h connect_timeout=30",
-      );
-   });
-
-   it("appends to URI form with no query", () => {
-      expect(withPgConnectTimeout("postgresql://u:p@h:5432/d", 5)).toBe(
-         "postgresql://u:p@h:5432/d?connect_timeout=5",
-      );
-   });
-
-   it("appends to URI form with existing query", () => {
-      expect(
-         withPgConnectTimeout("postgresql://u:p@h/d?sslmode=require", 5),
-      ).toBe("postgresql://u:p@h/d?sslmode=require&connect_timeout=5");
-   });
-
-   it("appends to URI with bare trailing ?", () => {
-      expect(withPgConnectTimeout("postgresql://h/d?", 5)).toBe(
-         "postgresql://h/d?connect_timeout=5",
-      );
-   });
-
-   it("does not double-append when URI already has connect_timeout (?-style)", () => {
-      expect(
-         withPgConnectTimeout("postgresql://h/d?connect_timeout=10", 5),
-      ).toBe("postgresql://h/d?connect_timeout=10");
-   });
-
-   it("does not double-append when URI already has connect_timeout (&-style)", () => {
-      expect(
-         withPgConnectTimeout(
-            "postgresql://h/d?sslmode=require&connect_timeout=10",
-            5,
-         ),
-      ).toBe("postgresql://h/d?sslmode=require&connect_timeout=10");
-   });
-
-   it("recognizes postgres:// (alternative scheme) as URI form", () => {
-      expect(withPgConnectTimeout("postgres://u@h/d", 5)).toBe(
-         "postgres://u@h/d?connect_timeout=5",
-      );
-   });
-});
+import { describe, expect, it } from "bun:test";
+import { redactPgSecrets } from "./pg_helpers";
 
 describe("redactPgSecrets", () => {
    it("redacts bare password values", () => {
@@ -120,107 +20,3 @@ describe("redactPgSecrets", () => {
       );
    });
 });
-
-describe("classifyPgError", () => {
-   it.each([
-      'password authentication failed for user "alice"',
-      "no pg_hba.conf entry for host",
-      'role "alice" does not exist',
-      'database "billing" does not exist',
-      "permission denied for relation foo",
-   ])("classifies '%s' as auth error", (msg) => {
-      const result = classifyPgError(new Error(msg), "PG attach");
-      expect(result).toBeInstanceOf(ConnectionAuthError);
-      expect(result?.message).toContain("PG attach:");
-   });
-
-   it("returns undefined for unrelated errors", () => {
-      expect(
-         classifyPgError(
-            new Error('relation "users" does not exist'),
-            "PG attach",
-         ),
-      ).toBeUndefined();
-      expect(
-         classifyPgError(new Error("connection reset by peer"), "PG attach"),
-      ).toBeUndefined();
-   });
-
-   it("returns undefined for non-Error values", () => {
-      expect(
-         classifyPgError("password authentication failed", "ctx"),
-      ).toBeUndefined();
-      expect(classifyPgError(undefined, "ctx")).toBeUndefined();
-   });
-
-   it("redacts embedded passwords in the wrapped message", () => {
-      const result = classifyPgError(
-         new Error(
-            "password authentication failed: tried host=h password=hunter2",
-         ),
-         "DuckLake attach",
-      );
-      expect(result?.message).toContain("password=***");
-      expect(result?.message).not.toContain("hunter2");
-   });
-});
-
-describe("handlePgAttachError", () => {
-   it("swallows 'already exists' errors", () => {
-      const outcome = handlePgAttachError(
-         new Error('database "db_x" already exists'),
-         "ctx",
-      );
-      expect(outcome.action).toBe("swallow");
-   });
-
-   it("swallows 'already attached' errors", () => {
-      const outcome = handlePgAttachError(
-         new Error("DuckLake catalog db_x is already attached"),
-         "ctx",
-      );
-      expect(outcome.action).toBe("swallow");
-   });
-
-   it("classifies libpq auth failures as ConnectionAuthError", () => {
-      const outcome = handlePgAttachError(
-         new Error('password authentication failed for user "alice"'),
-         "PG attach db_x",
-      );
-      expect(outcome.action).toBe("throw");
-      if (outcome.action === "throw") {
-         expect(outcome.error).toBeInstanceOf(ConnectionAuthError);
-         expect(outcome.error.message).toContain("PG attach db_x:");
-      }
-   });
-
-   it("passes through unrelated Error instances unchanged", () => {
-      const original = new Error("network unreachable");
-      const outcome = handlePgAttachError(original, "ctx");
-      expect(outcome.action).toBe("throw");
-      if (outcome.action === "throw") {
-         expect(outcome.error).toBe(original);
-         expect(outcome.error).not.toBeInstanceOf(ConnectionAuthError);
-      }
-   });
-
-   it("wraps non-Error throwables so callers always get an Error", () => {
-      const outcome = handlePgAttachError("a string was thrown", "ctx");
-      expect(outcome.action).toBe("throw");
-      if (outcome.action === "throw") {
-         expect(outcome.error).toBeInstanceOf(Error);
-         expect(outcome.error.message).toBe("a string was thrown");
-      }
-   });
-
-   it("prefers 'already attached' over auth classification when both keywords appear", () => {
-      // Defensive: if a future DuckDB version emits a combined message,
-      // 'already attached' wins so we don't bubble up a false auth failure
-      // on what is actually a benign idempotent re-attach.
-      const outcome = handlePgAttachError(
-         new Error("already attached; permission denied tail"),
-         "ctx",
-      );
-      expect(outcome.action).toBe("swallow");
-   });
-});

package/src/pg_helpers.ts

@@ -1,64 +1,7 @@
-// Postgres / libpq helpers shared between `service/` (user-facing
-// connections) and `storage/` (materialization-storage catalog). Lives at
-// `src/` root so neither layer takes a dependency on the other — see
-// CLAUDE.md's "Two parallel DuckLake/PG attach paths" note for why this
-// matters.
-import { ConnectionAuthError } from "./errors";
-
-// Default Postgres connect_timeout (seconds), used by the materialization
-// storage catalog ATTACH so a slow or wedged libpq handshake fails the
-// caller in seconds instead of stalling the worker until the K8s liveness
-// probe trips.
-//
-// libpq enforces a documented minimum of 2 seconds — values below 2
-// effectively round up to ~2s wall clock.
-export function pgConnectTimeoutSeconds(): number {
-   const raw = process.env.PG_CONNECT_TIMEOUT_SECONDS;
-   if (!raw) return 5;
-   const parsed = Number.parseInt(raw, 10);
-   return Number.isFinite(parsed) && parsed > 0 ? parsed : 5;
-}
-
-// libpq accepts both keyword=value form ("host=h dbname=d") and URI form
-// ("postgresql://u:p@h/d?param=v"). The materialization-storage catalogUrl
-// can also arrive as `postgres:<keyword=value>` (no `//`). We detect URI
-// form (with `//`) so we know whether to append a new parameter using
-// `?`/`&` or a leading space.
-const URI_FORM_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
-
-// Match an existing connect_timeout key in either form. URI form uses
-// `?key=` or `&key=`; keyword form uses whitespace separation or start-of-
-// string. Without the `[?&]` alternatives a URI-form user-supplied timeout
-// would be missed and we'd double-append, producing an invalid URL.
-const HAS_CONNECT_TIMEOUT_RE = /[?&\s]connect_timeout=|^connect_timeout=/;
-
-// Append `connect_timeout=N` to a libpq-compatible connection string if
-// the caller hasn't already set one. Handles keyword form ("host=h ..."),
-// URI form ("postgresql://..."), and the `postgres:host=h ...` keyword
-// form with a scheme prefix used by DuckLake catalogUrls.
-export function withPgConnectTimeout(
-   connectionString: string,
-   timeout: number,
-): string {
-   if (HAS_CONNECT_TIMEOUT_RE.test(connectionString)) {
-      return connectionString;
-   }
-   if (URI_FORM_RE.test(connectionString)) {
-      // URI form: append as query parameter. `?` if no query string yet,
-      // `&` otherwise. A bare trailing `?` (empty query) gets no extra
-      // separator. We don't try to handle URL fragments — libpq URIs don't
-      // use them.
-      if (!connectionString.includes("?")) {
-         return `${connectionString}?connect_timeout=${timeout}`;
-      }
-      if (connectionString.endsWith("?")) {
-         return `${connectionString}connect_timeout=${timeout}`;
-      }
-      return `${connectionString}&connect_timeout=${timeout}`;
-   }
-   // Keyword=value form (with or without `postgres:` scheme prefix).
-   return `${connectionString} connect_timeout=${timeout}`;
-}
+// Postgres / libpq helper shared between `service/` (user-facing connections)
+// and `storage/` (materialization-storage catalog). Lives at `src/` root so
+// neither layer takes a dependency on the other — see CLAUDE.md's "Two
+// parallel DuckLake/PG attach paths" note for why this matters.
 
 // Redact libpq `password=...` values from a string before it goes into a
 // log line or HTTP response body. Handles bare and quoted values.
@@ -68,62 +11,3 @@ export function withPgConnectTimeout(
 export function redactPgSecrets(s: string): string {
    return s.replace(/password=('[^']*'|"[^"]*"|\S+)/gi, "password=***");
 }
-
-// Substring-match libpq error patterns that indicate a non-retryable
-// auth/permission failure. Returns a ConnectionAuthError when matched so
-// callers can fast-fail with HTTP 422 (semantically "the supplied creds
-// are bad; don't retry") instead of letting the raw error fall through to
-// a generic 500 that retry loops treat as transient.
-export function classifyPgError(
-   error: unknown,
-   context: string,
-): ConnectionAuthError | undefined {
-   if (!(error instanceof Error)) return undefined;
-   const msg = error.message;
-   const patterns = [
-      /password authentication failed/i,
-      /pg_hba\.conf/i,
-      /role ".*" does not exist/i,
-      /database ".*" does not exist/i,
-      /permission denied/i,
-   ];
-   if (!patterns.some((p) => p.test(msg))) return undefined;
-   return new ConnectionAuthError(`${context}: ${redactPgSecrets(msg)}`);
-}
-
-// Outcome of inspecting an error thrown by an `ATTACH` call:
-//   - `{ action: "swallow" }`: DuckDB reported the db is already attached
-//     (idempotent re-attach); caller should log and continue.
-//   - `{ action: "throw", error: ConnectionAuthError }`: classified as a
-//     non-retryable auth failure; caller should warn-log and throw it.
-//   - `{ action: "throw", error: <original> }`: unrecognized; caller
-//     should rethrow as-is to preserve the original cause for diagnosis.
-//
-// Extracted so the decision tree gets a direct unit test without needing
-// to stub DuckDB or run a real ATTACH.
-export type PgAttachErrorOutcome =
-   | { action: "swallow" }
-   | { action: "throw"; error: Error };
-
-export function handlePgAttachError(
-   error: unknown,
-   context: string,
-): PgAttachErrorOutcome {
-   if (
-      error instanceof Error &&
-      (error.message.includes("already exists") ||
-         error.message.includes("already attached"))
-   ) {
-      return { action: "swallow" };
-   }
-   const authErr = classifyPgError(error, context);
-   if (authErr) {
-      return { action: "throw", error: authErr };
-   }
-   if (error instanceof Error) {
-      return { action: "throw", error };
-   }
-   // Non-Error thrown values get wrapped so the catch contract stays
-   // (always throws an Error).
-   return { action: "throw", error: new Error(String(error)) };
-}

package/src/server.ts

@@ -41,7 +41,6 @@ import { queryConcurrency } from "./query_concurrency";
 import { MaterializationController } from "./controller/materialization.controller";
 import { ThemeController } from "./controller/theme.controller";
 import { initializeMcpServer } from "./mcp/server";
-import { startAgentMcpServer } from "./mcp/agent_server";
 import { registerLegacyRoutes } from "./server-old";
 import { EnvironmentStore } from "./service/environment_store";
 import { MaterializationService } from "./service/materialization_service";
@@ -50,8 +49,6 @@ import { PackageMemoryGovernor } from "./service/package_memory_governor";
 import { ThemeStore } from "./service/theme_store";
 import { assertSafePackageName, safeJoinUnderRoot } from "./path_safety";
 
-export { normalizeQueryArray } from "./query_param_utils";
-
 // Parse command line arguments
 function parseArgs() {
    const args = process.argv.slice(2);
@@ -162,7 +159,6 @@ parseArgs();
 const PUBLISHER_PORT = Number(process.env.PUBLISHER_PORT || 4000);
 const PUBLISHER_HOST = process.env.PUBLISHER_HOST || "0.0.0.0";
 const MCP_PORT = Number(process.env.MCP_PORT || 4040);
-const AGENT_MCP_PORT = Number(process.env.AGENT_MCP_PORT || 4041);
 const MCP_ENDPOINT = "/mcp";
 const SHUTDOWN_DRAIN_DURATION_SECONDS = Number(
    process.env.SHUTDOWN_DRAIN_DURATION_SECONDS || 0,
@@ -1868,21 +1864,9 @@ mcpServer.timeout = 600000;
 mcpServer.keepAliveTimeout = 600000;
 mcpServer.headersTimeout = 600000;
 
-// Separate, isolated MCP server for the agent retrieval tools (get_context,
-// search_docs) on its own listener. Kept apart from the core MCP server above.
-const agentMcpServer = startAgentMcpServer(
-   environmentStore,
-   PUBLISHER_HOST,
-   AGENT_MCP_PORT,
-);
-agentMcpServer.timeout = 600000;
-agentMcpServer.keepAliveTimeout = 600000;
-agentMcpServer.headersTimeout = 600000;
-
 registerSignalHandlers(
    mainServer,
    mcpServer,
    SHUTDOWN_DRAIN_DURATION_SECONDS,
    SHUTDOWN_GRACEFUL_CLOSE_TIMEOUT_SECONDS,
-   agentMcpServer,
 );

package/src/service/environment.ts

@@ -792,7 +792,7 @@ export class Environment {
       // reloadAllModelsForPackage, ...) acquire the lock themselves.
       //
       // INVARIANT: callers that consume the returned Package on the fast
-      // path (notably MCP resource handlers and Model.getModel()) must
+      // path (notably the MCP query tools and Model.getModel()) must
       // remain in-memory only. If any code reachable from a `Package`
       // method ever grows new disk I/O against the canonical tree, that
       // path needs to be bracketed by `withPackageLock`; otherwise a

package/src/service/package.ts

@@ -29,6 +29,11 @@ import {
 } from "../errors";
 import { formatDuration, logger } from "../logger";
 import { recordBuildPlanComputeDuration } from "../materialization_metrics";
+import {
+   LOAD_DURATION_BUCKETS_MS,
+   recordPackageLoadPhases,
+   type PackageLoadStatus,
+} from "../package_load_metrics";
 import { assertSafeEnvironmentPath, safeJoinUnderRoot } from "../path_safety";
 import {
    BuildManifest,
@@ -73,6 +78,23 @@ function toTableNameManifest(
    return out;
 }
 
+/**
+ * Classify a failed package load into the `status` label shared by the
+ * `malloy_package_load_duration` histogram and the per-phase load metrics, so
+ * both slice failures identically. A real Malloy/model compile error is a 4xx
+ * `compilation_error`; a rewrapped pool-infrastructure failure is a transient
+ * `pool_unavailable`; anything else is a generic `error`.
+ */
+function packageLoadFailureStatus(error: unknown): PackageLoadStatus {
+   if (error instanceof ModelCompilationError || error instanceof MalloyError) {
+      return "compilation_error";
+   }
+   if (error instanceof ServiceUnavailableError) {
+      return "pool_unavailable";
+   }
+   return "error";
+}
+
 export class Package {
    private environmentName: string;
    private packageName: string;
@@ -127,6 +149,10 @@ export class Package {
       {
          description: "Time taken to load a Malloy package",
          unit: "ms",
+         // OTel's default buckets top out at 10s, censoring the slow-load tail.
+         // Use the shared load-duration buckets (→5min) so p95/p99 of large
+         // package loads are resolvable. See LOAD_DURATION_BUCKETS_MS.
+         advice: { explicitBucketBoundaries: LOAD_DURATION_BUCKETS_MS },
       },
    );
 
@@ -248,16 +274,9 @@ export class Package {
          console.error(error);
          const endTime = performance.now();
          const executionTime = endTime - startTime;
-         const status =
-            error instanceof ModelCompilationError ||
-            error instanceof MalloyError
-               ? "compilation_error"
-               : error instanceof ServiceUnavailableError
-                 ? "pool_unavailable"
-                 : "error";
          this.packageLoadHistogram.record(executionTime, {
             malloy_package_name: packageName,
-            status,
+            status: packageLoadFailureStatus(error),
          });
          // Clean up the package directory on failure, but NOT when packagePath
          // is an in-place mount symlink (watch mode). Removing it would unmount
@@ -361,6 +380,10 @@ export class Package {
          workerDurationMs: outcome.loadDurationMs,
          dispatchOverheadMs:
             workerDoneTime - dispatchTime - outcome.loadDurationMs,
+         // Phase split of the worker duration (remainder = setup + extraction).
+         compileDurationMs: outcome.timings.compileDurationMs,
+         schemaFetchDurationMs: outcome.timings.schemaFetchDurationMs,
+         schemaFetchCount: outcome.timings.schemaFetchCount,
          modelCount: outcome.models.length,
          databaseCount: databases.length,
       });
@@ -400,43 +423,59 @@ export class Package {
       // hydration path.)
       const models = new Map<string, Model>();
       const renderTagWarnings: ApiPackageWarning[] = [];
-      for (const sm of outcome.models) {
-         if (sm.compilationError) {
-            const err = Model.deserializeCompilationError(sm.compilationError);
-            logger.error("Model compilation failed", {
+      try {
+         for (const sm of outcome.models) {
+            if (sm.compilationError) {
+               const err = Model.deserializeCompilationError(
+                  sm.compilationError,
+               );
+               logger.error("Model compilation failed", {
+                  packageName,
+                  modelPath: sm.modelPath,
+                  error: err.message,
+               });
+               // The outer catch in Package.create records the total metric +
+               // cleans the package directory.
+               throw err;
+            }
+            const model = Model.fromSerialized(
                packageName,
-               modelPath: sm.modelPath,
-               error: err.message,
-            });
-            // The outer catch in Package.create records the metric +
-            // cleans the package directory.
-            throw err;
-         }
-         const model = Model.fromSerialized(
-            packageName,
-            packagePath,
-            malloyConfig,
-            sm,
-         );
-         // Validate renderer tags on the main thread (the renderer is too heavy
-         // to load inside the pure-CPU package-load worker). A misconfigured tag
-         // is logged as a warning naming the target; it does not fail the load.
-         // The findings also ride the package response as non-fatal `warnings`.
-         for (const w of await model.validateRenderTags()) {
-            renderTagWarnings.push({ model: sm.modelPath, ...w });
-         }
-         // Reject unquoted `#@ persist name=` annotations the same way: an
-         // unquoted name is dropped from the build plan, so the source would
-         // publish but never materialize. Scan the raw `.malloy` source (the
-         // ground truth for quoting); throws a ModelCompilationError (424).
-         if (sm.modelPath.endsWith(MODEL_FILE_SUFFIX)) {
-            const modelSource = await fs.readFile(
-               path.join(packagePath, sm.modelPath),
-               "utf-8",
+               packagePath,
+               malloyConfig,
+               sm,
             );
-            assertPersistNamesQuoted(modelSource, sm.modelPath);
+            // Validate renderer tags on the main thread (the renderer is too
+            // heavy to load inside the pure-CPU package-load worker). A
+            // misconfigured tag is logged as a warning naming the target; it
+            // does not fail the load. The findings also ride the package
+            // response as non-fatal `warnings`.
+            for (const w of await model.validateRenderTags()) {
+               renderTagWarnings.push({ model: sm.modelPath, ...w });
+            }
+            // Reject unquoted `#@ persist name=` annotations the same way: an
+            // unquoted name is dropped from the build plan, so the source would
+            // publish but never materialize. Scan the raw `.malloy` source (the
+            // ground truth for quoting); throws a ModelCompilationError (424).
+            if (sm.modelPath.endsWith(MODEL_FILE_SUFFIX)) {
+               const modelSource = await fs.readFile(
+                  path.join(packagePath, sm.modelPath),
+                  "utf-8",
+               );
+               assertPersistNamesQuoted(modelSource, sm.modelPath);
+            }
+            models.set(sm.modelPath, model);
          }
-         models.set(sm.modelPath, model);
+      } catch (err) {
+         // Record the load's phase cost tagged with the terminal status before
+         // the error propagates to the outer catch (which records the total).
+         // Only in-band compile failures reach here — the worker already
+         // produced `outcome.timings`; a pool failure throws before `outcome`
+         // exists and carries no timings, so it's simply not recorded.
+         recordPackageLoadPhases(
+            outcome.timings,
+            packageLoadFailureStatus(err),
+         );
+         throw err;
       }
 
       const endTime = performance.now();
@@ -445,6 +484,7 @@ export class Package {
          malloy_package_name: packageName,
          status: "success",
       });
+      recordPackageLoadPhases(outcome.timings, "success");
       logger.info(`Successfully loaded package ${packageName}`, {
          packageName,
          duration: formatDuration(executionTime),

package/src/test_helpers/metrics_harness.ts

@@ -62,6 +62,15 @@ export interface MetricsHarness {
     * fired for this gauge yet.
     */
    collectGauge(name: string): Promise<number | undefined>;
+   /**
+    * Force a collection cycle and return the aggregate `count`/`sum` across all
+    * data points for the named histogram (optionally scoped to one label set).
+    * `count` is 0 when the histogram has not been emitted yet.
+    */
+   collectHistogram(
+      name: string,
+      attributeFilter?: Record<string, string | number | boolean>,
+   ): Promise<{ count: number; sum: number; boundaries: number[] }>;
    shutdown(): Promise<void>;
 }
 
@@ -100,6 +109,37 @@ export async function startMetricsHarness(): Promise<MetricsHarness> {
          }
          return total;
       },
+      async collectHistogram(
+         name: string,
+         attributeFilter?: Record<string, string | number | boolean>,
+      ): Promise<{ count: number; sum: number; boundaries: number[] }> {
+         const result = await reader.collect();
+         let count = 0;
+         let sum = 0;
+         let boundaries: number[] = [];
+         for (const rm of result.resourceMetrics.scopeMetrics) {
+            for (const metric of rm.metrics) {
+               if (metric.descriptor.name !== name) continue;
+               for (const dp of metric.dataPoints) {
+                  if (attributeFilter) {
+                     const allMatch = Object.entries(attributeFilter).every(
+                        ([k, v]) => dp.attributes?.[k] === v,
+                     );
+                     if (!allMatch) continue;
+                  }
+                  const point = dp.value as {
+                     count: number;
+                     sum?: number;
+                     buckets?: { boundaries: number[] };
+                  };
+                  count += point.count;
+                  sum += point.sum ?? 0;
+                  if (point.buckets) boundaries = point.buckets.boundaries;
+               }
+            }
+         }
+         return { count, sum, boundaries };
+      },
       async collectGauge(name: string): Promise<number | undefined> {
          const result = await reader.collect();
          for (const rm of result.resourceMetrics.scopeMetrics) {

package/tests/harness/mcp_test_setup.ts

@@ -30,7 +30,7 @@ let portCounter = 0;
 
 // True mutex: the previous Promise-based lock had a TOCTOU race where two beforeAll hooks
 // could both pass the `if (initializationLock)` check and run setup concurrently, sharing
-// one publisher.db / server singleton and causing flaky listResources and port collisions.
+// one publisher.db / server singleton and causing flaky tool calls and port collisions.
 const e2eSetupMutex = new Mutex();
 
 /**