@malloy-publisher/server 0.0.226 → 0.0.228

package/src/package_load/rpc_wait_accountant.ts

@@ -0,0 +1,76 @@
+/**
+ * Per-load "wait" accounting for the package-load worker.
+ *
+ * A package load spends its time in two very different ways: CPU-bound Malloy
+ * compilation, and I/O waiting on connection schema fetches that are proxied
+ * back to the main thread. Today only the *total* load time is observable, so
+ * an operator seeing slow loads can't tell which half dominates. This tracks
+ * the wall-clock during which at least one proxied schema fetch is outstanding,
+ * so the load handler can report `compile = compileRegion - schemaFetchWait`
+ * alongside the fetch time itself.
+ *
+ * Why wall-minus-wait and not a CPU counter: worker threads share the host
+ * process, so `process.cpuUsage()` is process-wide and would fold in every
+ * other worker's CPU — useless for a per-load number. Wall-minus-wait is the
+ * honest per-load proxy. Treat the compute figure as a conservative *ceiling*
+ * on compile CPU: only proxied waits are subtracted, so any non-fetch stall
+ * (GC, scheduler preemption) also lands in "compute".
+ *
+ * Overlapping fetches are counted as their union (the wall-time with >=1
+ * outstanding), never the sum, so concurrent fetches during one compile don't
+ * over-subtract.
+ *
+ * Scoped by `jobId`: the pool runs one load per worker at a time, but reuses a
+ * worker across loads, and a load that fails can leave a proxied fetch in
+ * flight. Gating every start/settle on the active job makes such a straggler's
+ * late response a no-op instead of corrupting the next load's numbers. (If the
+ * one-load-per-worker rule ever changes, this stays correct per job but the
+ * compute ceiling would then also fold in a sibling load's CPU.)
+ */
+export class RpcWaitAccountant {
+   private inFlight = 0;
+   private waitStartMs = 0;
+   private accumMs = 0;
+   private startedCount = 0;
+   private activeJobId: string | undefined;
+
+   constructor(private readonly now: () => number = () => performance.now()) {}
+
+   /** Begin accounting for `jobId`, discarding any prior-load state. */
+   begin(jobId: string): void {
+      this.activeJobId = jobId;
+      this.inFlight = 0;
+      this.waitStartMs = 0;
+      this.accumMs = 0;
+      this.startedCount = 0;
+   }
+
+   /** A proxied fetch for `jobId` was issued. Ignored if `jobId` isn't active. */
+   noteStart(jobId: string): void {
+      if (jobId !== this.activeJobId) return;
+      if (this.inFlight === 0) this.waitStartMs = this.now();
+      this.inFlight += 1;
+      this.startedCount += 1;
+   }
+
+   /**
+    * A proxied fetch for `jobId` settled (resolved or rejected). Ignored if
+    * `jobId` isn't active, so a straggler from a prior reused-worker load
+    * can't drive the counter negative or close the active load's bracket.
+    */
+   noteSettle(jobId: string): void {
+      if (jobId !== this.activeJobId) return;
+      this.inFlight -= 1;
+      if (this.inFlight === 0) this.accumMs += this.now() - this.waitStartMs;
+   }
+
+   /** Accumulated wall-time with >=1 active-load fetch outstanding (union). */
+   get waitMs(): number {
+      return this.accumMs;
+   }
+
+   /** Number of proxied fetches started for the active load. */
+   get fetches(): number {
+      return this.startedCount;
+   }
+}

package/src/package_load_metrics.spec.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import {
+   recordPackageLoadPhases,
+   resetPackageLoadMetricsForTesting,
+} from "./package_load_metrics";
+import {
+   startMetricsHarness,
+   type MetricsHarness,
+} from "./test_helpers/metrics_harness";
+
+describe("package_load_metrics", () => {
+   let harness: MetricsHarness;
+
+   beforeEach(async () => {
+      harness = await startMetricsHarness();
+      resetPackageLoadMetricsForTesting();
+   });
+
+   afterEach(async () => {
+      resetPackageLoadMetricsForTesting();
+      await harness.shutdown();
+   });
+
+   it("records the three phase histograms, labeled by status", async () => {
+      recordPackageLoadPhases(
+         {
+            compileDurationMs: 120,
+            schemaFetchDurationMs: 80,
+            schemaFetchCount: 4,
+         },
+         "success",
+      );
+      recordPackageLoadPhases(
+         {
+            compileDurationMs: 40,
+            schemaFetchDurationMs: 10,
+            schemaFetchCount: 1,
+         },
+         "success",
+      );
+
+      const compile = await harness.collectHistogram(
+         "malloy_package_load_compile_duration",
+         { status: "success" },
+      );
+      expect(compile.count).toBe(2);
+      expect(compile.sum).toBe(160);
+
+      const fetchDuration = await harness.collectHistogram(
+         "malloy_package_load_schema_fetch_duration",
+         { status: "success" },
+      );
+      expect(fetchDuration.count).toBe(2);
+      expect(fetchDuration.sum).toBe(90);
+
+      const fetches = await harness.collectHistogram(
+         "malloy_package_load_schema_fetches",
+         { status: "success" },
+      );
+      expect(fetches.count).toBe(2);
+      expect(fetches.sum).toBe(5);
+   });
+
+   it("labels phases by terminal status, so failures are separable from successes", async () => {
+      recordPackageLoadPhases(
+         {
+            compileDurationMs: 30,
+            schemaFetchDurationMs: 5,
+            schemaFetchCount: 1,
+         },
+         "success",
+      );
+      recordPackageLoadPhases(
+         {
+            compileDurationMs: 12,
+            schemaFetchDurationMs: 3,
+            schemaFetchCount: 1,
+         },
+         "compilation_error",
+      );
+
+      const ok = await harness.collectHistogram(
+         "malloy_package_load_compile_duration",
+         { status: "success" },
+      );
+      const failed = await harness.collectHistogram(
+         "malloy_package_load_compile_duration",
+         { status: "compilation_error" },
+      );
+      expect(ok.count).toBe(1);
+      expect(ok.sum).toBe(30);
+      expect(failed.count).toBe(1);
+      expect(failed.sum).toBe(12);
+   });
+
+   it("resolves the slow-load tail past OTel's default 10s cap", async () => {
+      // A 90s load would fall in the +Inf bucket under OTel's default
+      // boundaries (top = 10000ms); the explicit buckets must extend further.
+      recordPackageLoadPhases(
+         {
+            compileDurationMs: 90_000,
+            schemaFetchDurationMs: 0,
+            schemaFetchCount: 0,
+         },
+         "success",
+      );
+      const compile = await harness.collectHistogram(
+         "malloy_package_load_compile_duration",
+      );
+      expect(compile.boundaries.some((b) => b > 10_000)).toBe(true);
+      expect(compile.boundaries[compile.boundaries.length - 1]).toBe(300_000);
+   });
+});

package/src/package_load_metrics.ts

@@ -0,0 +1,127 @@
+/**
+ * Per-load phase timing for package loads.
+ *
+ * `malloy_package_load_duration` already reports the *total* time to load a
+ * package, but an operator watching a slow load can't tell whether it's the
+ * Malloy compile or the connection schema fetches that dominate — the two are
+ * tuned very differently (CPU/worker sizing vs. warehouse round-trips). These
+ * histograms split the load into those phases so a single dashboard answers
+ * "where did the time go?". The worker measures the phases and reports them on
+ * its result; see `package_load/package_load_worker.ts` and
+ * `package_load/rpc_wait_accountant.ts`.
+ *
+ * Labels: `status` only. Deliberately NOT labelled by package name — unlike
+ * `malloy_package_load_duration`, which carries `malloy_package_name` — to keep
+ * cardinality bounded on deployments with many packages. Per-package latency,
+ * when needed, is better answered by exemplars/traces than a label explosion.
+ *
+ * Lazy init for the same reason as `query_cap_metrics.ts` / `query_timeout.ts`:
+ * instruments created before `setGlobalMeterProvider` bind to a NoOp meter
+ * (https://github.com/open-telemetry/opentelemetry-js/issues/3505).
+ */
+
+import { type Histogram } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
+
+/**
+ * Explicit bucket boundaries (ms) for the load-duration histograms. OTel's
+ * default boundaries top out at 10 000 ms, so any load slower than 10 s falls
+ * in the `+Inf` bucket and `histogram_quantile` can't resolve the tail — which
+ * is exactly the tail (large/slow packages) worth seeing. These extend to
+ * 5 minutes while keeping sub-10 ms resolution for the fast common case.
+ * Shared with the total `malloy_package_load_duration` histogram so all
+ * load-timing histograms bucket consistently.
+ */
+export const LOAD_DURATION_BUCKETS_MS = [
+   1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10_000, 30_000, 60_000,
+   120_000, 300_000,
+];
+
+/** Bucket boundaries for the per-load schema-fetch count. */
+const SCHEMA_FETCH_COUNT_BUCKETS = [0, 1, 2, 5, 10, 25, 50, 100, 250, 500];
+
+/**
+ * Terminal status of a package load, mirroring the `status` label on the
+ * existing `malloy_package_load_duration` histogram so the phase metrics slice
+ * the same way. In practice the phase histograms only ever carry `success`,
+ * `compilation_error`, or `error` — a `pool_unavailable` failure happens before
+ * the worker returns any timings, so there is nothing to record for it.
+ */
+export type PackageLoadStatus =
+   | "success"
+   | "compilation_error"
+   | "pool_unavailable"
+   | "error";
+
+/** Phase timings a single package load reports (subset of the total). */
+export interface PackageLoadPhaseTimings {
+   /** Ceiling on Malloy compile CPU (compile region minus schema-fetch wait). */
+   compileDurationMs: number;
+   /** Wall-clock awaiting proxied connection schema fetches. */
+   schemaFetchDurationMs: number;
+   /** Number of proxied connection schema fetches the load drove. */
+   schemaFetchCount: number;
+}
+
+let compileDuration: Histogram | null = null;
+let schemaFetchDuration: Histogram | null = null;
+let schemaFetches: Histogram | null = null;
+
+function ensureInstruments(): void {
+   if (compileDuration && schemaFetchDuration && schemaFetches) return;
+   const meter = publisherMeter();
+   compileDuration ??= meter.createHistogram(
+      "malloy_package_load_compile_duration",
+      {
+         description:
+            "Per-load Malloy compile time (compile region minus proxied schema-fetch wait; a ceiling on compile CPU). Label: status.",
+         unit: "ms",
+         advice: { explicitBucketBoundaries: LOAD_DURATION_BUCKETS_MS },
+      },
+   );
+   schemaFetchDuration ??= meter.createHistogram(
+      "malloy_package_load_schema_fetch_duration",
+      {
+         description:
+            "Per-load wall-clock awaiting proxied connection schema fetches. Label: status.",
+         unit: "ms",
+         advice: { explicitBucketBoundaries: LOAD_DURATION_BUCKETS_MS },
+      },
+   );
+   schemaFetches ??= meter.createHistogram(
+      "malloy_package_load_schema_fetches",
+      {
+         description:
+            "Per-load count of proxied connection schema fetches. Label: status.",
+         advice: { explicitBucketBoundaries: SCHEMA_FETCH_COUNT_BUCKETS },
+      },
+   );
+}
+
+/**
+ * Record one load's phase breakdown. Call once the worker has returned timings,
+ * with the load's terminal `status` (so the phases can be sliced by outcome the
+ * same way the total duration is). The terms are meaningless for a load that
+ * never produced a worker result (e.g. a pool failure), so don't call it there.
+ */
+export function recordPackageLoadPhases(
+   timings: PackageLoadPhaseTimings,
+   status: PackageLoadStatus,
+): void {
+   ensureInstruments();
+   const attrs = { status };
+   compileDuration?.record(timings.compileDurationMs, attrs);
+   schemaFetchDuration?.record(timings.schemaFetchDurationMs, attrs);
+   schemaFetches?.record(timings.schemaFetchCount, attrs);
+}
+
+/**
+ * Visible for tests. Drops cached instruments so a fresh `MeterProvider`
+ * (installed via `startMetricsHarness`) captures future emissions. Do NOT call
+ * from production code.
+ */
+export function resetPackageLoadMetricsForTesting(): void {
+   compileDuration = null;
+   schemaFetchDuration = null;
+   schemaFetches = null;
+}

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/runtime/publisher.js

@@ -5,6 +5,10 @@
 // Exposes window.Publisher with:
 //   - Publisher.query(model, malloy, opts?)     → Promise<rows[]>
 //   - Publisher.queryFull(model, malloy, opts?) → Promise<MalloyResult>  (envelope for <malloy-render>)
+//       opts: { environment?, package?, sourceName?, queryName?, filterParams?,
+//               bypassFilters?, givens? }. givens is a name→value map bound as
+//               Malloy given: runtime parameters for this query (safe parameterization,
+//               not string interpolation) — see the malloy-html-data-app-runtime skill.
 //   - Publisher.embed(selector, { src, height?, token? })
 //   - Publisher.context  ({ environment, package } inferred from URL)
 //   - Publisher.setToken(token)  (override Bearer token; default uses cookies)
@@ -92,6 +96,7 @@
       if (opts.queryName) body.queryName = opts.queryName;
       if (opts.filterParams) body.filterParams = opts.filterParams;
       if (opts.bypassFilters) body.bypassFilters = true;
+      if (opts.givens) body.givens = opts.givens;
 
       var headers = Object.assign(
          { "content-type": "application/json" },