@malloy-publisher/server 0.0.231 → 0.0.233

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.231",
+   "version": "0.0.233",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -36,17 +36,17 @@
       "@azure/storage-blob": "^12.26.0",
       "@duckdb/node-api": "1.5.3-r.2",
       "@google-cloud/storage": "^7.16.0",
-      "@malloydata/db-bigquery": "^0.0.423",
-      "@malloydata/db-databricks": "^0.0.423",
-      "@malloydata/db-duckdb": "^0.0.423",
-      "@malloydata/db-mysql": "^0.0.423",
-      "@malloydata/db-postgres": "^0.0.423",
-      "@malloydata/db-publisher": "^0.0.423",
-      "@malloydata/db-snowflake": "^0.0.423",
-      "@malloydata/db-trino": "^0.0.423",
-      "@malloydata/malloy": "^0.0.423",
-      "@malloydata/malloy-sql": "^0.0.423",
-      "@malloydata/render-validator": "^0.0.423",
+      "@malloydata/db-bigquery": "^0.0.426",
+      "@malloydata/db-databricks": "^0.0.426",
+      "@malloydata/db-duckdb": "^0.0.426",
+      "@malloydata/db-mysql": "^0.0.426",
+      "@malloydata/db-postgres": "^0.0.426",
+      "@malloydata/db-publisher": "^0.0.426",
+      "@malloydata/db-snowflake": "^0.0.426",
+      "@malloydata/db-trino": "^0.0.426",
+      "@malloydata/malloy": "^0.0.426",
+      "@malloydata/malloy-sql": "^0.0.426",
+      "@malloydata/render-validator": "^0.0.426",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.57.0",

package/scripts/bake-duckdb-extensions.js

@@ -25,7 +25,9 @@ import { DuckDBInstance } from "@duckdb/node-api";
 // Every extension the connection layer (packages/server/src/service/connection.ts)
 // and storage manager INSTALL/LOAD at runtime, for cloud attach, the per-package
 // sandbox, federated-database attach, and the materialization catalog. Keep this
-// in sync with the install sites in those files.
+// in sync with the install sites in those files. `excel` is the exception: it
+// has no INSTALL site because DuckDB autoloads it when a package reads an
+// .xlsx file, so baking is what makes those reads work offline.
 //
 // `community: true` marks the community-repo extensions (bigquery, snowflake);
 // the rest are core extensions installed by name. The bake deliberately uses
@@ -40,6 +42,7 @@ const EXTENSIONS = [
    { name: "azure", community: false }, // azure blob storage
    { name: "postgres", community: false, registered: "postgres_scanner" }, // postgres attach + ducklake postgres catalog
    { name: "ducklake", community: false }, // materialization catalog
+   { name: "excel", community: false }, // .xlsx reads in per-package sandboxes (autoloaded on demand)
    { name: "bigquery", community: true },
    { name: "snowflake", community: true },
 ];

package/src/config.spec.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import fs from "fs";
 import path from "path";
 import {
+   getPersistCollisionEnforce,
    getPublisherConfig,
    getPublisherConfigDir,
    type PublisherConfig,
@@ -1494,3 +1495,41 @@ describe("getPublisherConfigDir", () => {
       expect(getPublisherConfigDir(testRoot)).toBeNull();
    });
 });
+
+describe("PERSIST_COLLISION_ENFORCE", () => {
+   // The flag decides whether a persist-target collision blocks a publish, so
+   // mis-parsing it leaves the check warn-only — failing open in exactly the
+   // direction it exists to prevent. An ad-hoc `=== "true"` did that for `1`,
+   // `yes` and `on`.
+   const prev = process.env.PERSIST_COLLISION_ENFORCE;
+   afterEach(() => {
+      if (prev === undefined) delete process.env.PERSIST_COLLISION_ENFORCE;
+      else process.env.PERSIST_COLLISION_ENFORCE = prev;
+   });
+
+   it("defaults to warn-only when unset or empty", () => {
+      delete process.env.PERSIST_COLLISION_ENFORCE;
+      expect(getPersistCollisionEnforce()).toBe(false);
+      process.env.PERSIST_COLLISION_ENFORCE = "   ";
+      expect(getPersistCollisionEnforce()).toBe(false);
+   });
+
+   it("enforces for every spelling of true an operator might use", () => {
+      for (const raw of ["true", "TRUE", " True ", "1", "yes", "on"]) {
+         process.env.PERSIST_COLLISION_ENFORCE = raw;
+         expect(getPersistCollisionEnforce()).toBe(true);
+      }
+   });
+
+   it("stays warn-only for every spelling of false", () => {
+      for (const raw of ["false", "FALSE", "0", "no", "off"]) {
+         process.env.PERSIST_COLLISION_ENFORCE = raw;
+         expect(getPersistCollisionEnforce()).toBe(false);
+      }
+   });
+
+   it("throws on a value that is neither, rather than guessing", () => {
+      process.env.PERSIST_COLLISION_ENFORCE = "enabled";
+      expect(() => getPersistCollisionEnforce()).toThrow(/expected a boolean/i);
+   });
+});

package/src/config.ts

@@ -262,6 +262,73 @@ export const getMemoryGovernorConfig = (): MemoryGovernorConfig | null => {
    };
 };
 
+/**
+ * Settings for the optional embedding provider behind semantic
+ * `malloy_getContext` retrieval. See {@link getEmbeddingConfig}.
+ */
+export interface EmbeddingConfig {
+   /** Bearer token sent to the embedding endpoint. */
+   apiKey: string;
+   /** Embedding model name, e.g. "text-embedding-3-small". */
+   model: string;
+   /** Base URL of an OpenAI-compatible API (no trailing slash). */
+   baseUrl: string;
+   /**
+    * Optional `dimensions` request parameter. Omitted from requests when
+    * unset; the vector length then comes from the provider's response.
+    */
+   dimensions?: number;
+}
+
+const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+const DEFAULT_EMBEDDING_API_BASE = "https://api.openai.com/v1";
+
+/**
+ * Embedding-provider settings for semantic `malloy_getContext` retrieval,
+ * or `null` when the feature is disabled. The feature is enabled iff
+ * `EMBEDDING_API_KEY` is set and non-empty; without it the tool keeps its
+ * lexical (lunr) ranking unchanged.
+ *
+ * The key must be set explicitly. An ambient provider key (for example
+ * `OPENAI_API_KEY`) is deliberately NOT read: enabling this feature sends
+ * entity names, `#(doc)` text, and query strings to the configured
+ * endpoint, and that egress must never switch on just because a commonly
+ * exported variable happens to be present.
+ *
+ * Throws on malformed companion values (bad URL, bad integer) so a typo
+ * surfaces loudly in the log rather than silently degrading to lexical.
+ */
+export const getEmbeddingConfig = (): EmbeddingConfig | null => {
+   const apiKey = process.env.EMBEDDING_API_KEY?.trim();
+   if (!apiKey) {
+      return null;
+   }
+
+   const rawBase = process.env.EMBEDDING_API_BASE;
+   const baseUrl = (rawBase?.trim() || DEFAULT_EMBEDDING_API_BASE).replace(
+      /\/+$/,
+      "",
+   );
+   try {
+      new URL(baseUrl);
+   } catch {
+      throw new Error(
+         `Invalid value for EMBEDDING_API_BASE: expected a URL, got "${rawBase}"`,
+      );
+   }
+
+   const model = process.env.EMBEDDING_MODEL?.trim() || DEFAULT_EMBEDDING_MODEL;
+
+   const dimensions = parseIntEnv("EMBEDDING_DIMENSIONS");
+   if (dimensions !== undefined && dimensions <= 0) {
+      throw new Error(
+         `EMBEDDING_DIMENSIONS must be a positive integer (got ${dimensions})`,
+      );
+   }
+
+   return { apiKey, model, baseUrl, dimensions };
+};
+
 /**
  * Tunables for the standalone {@link MaterializationScheduler}. Sourced from
  * environment variables at startup; see {@link getMaterializationSchedulerConfig}.
@@ -480,6 +547,74 @@ export const getExtensionFetchPolicy = (): ExtensionFetchPolicy => {
    );
 };
 
+/**
+ * The three `#@ persist storage=<conn>` deployment modes, read from
+ * `PERSIST_STORAGE_MODE`. This is a runtime kill switch — flipping DOWN must
+ * never fail an already-loaded package, only change how `storage=` is honored:
+ *
+ *  - `off` (default): `storage=` is inert. Sources build into (colocated) and serve
+ *    from their own warehouse exactly as before the feature existed; a source
+ *    that declares `storage=` is served live and surfaced as a package warning.
+ *    The safe resting state and the incident kill switch.
+ *  - `write-only`: builds materialize into the storage destination (so operators
+ *    can measure and inspect the tables), but the serve path still ignores
+ *    `storage=` and serves live. The de-risking / measurement rung.
+ *  - `on`: full end to end — build into storage AND serve via the virtual-source
+ *    transform, with a per-query fallback to live for anything the transform
+ *    cannot yet serve.
+ *
+ * The publisher NEVER hard-fails a package on `storage=` in any mode; any
+ * stricter "refuse a new package that uses storage= while off" policy is the
+ * caller's, not here (the mechanism/policy split).
+ */
+export type PersistStorageMode = "off" | "write-only" | "on";
+
+const PERSIST_STORAGE_MODES: readonly PersistStorageMode[] = [
+   "off",
+   "write-only",
+   "on",
+];
+
+/**
+ * Resolve the `storage=` deployment mode from `PERSIST_STORAGE_MODE`. Defaults
+ * to `off` (feature dark) when unset/empty; loud-fails on an unrecognized value
+ * so a typo can't silently leave the fleet in a surprising mode. Case-insensitive,
+ * like the sibling `PERSIST_COLLISION_ENFORCE`.
+ */
+export const getPersistStorageMode = (): PersistStorageMode => {
+   const raw = process.env.PERSIST_STORAGE_MODE;
+   if (raw === undefined || raw.trim() === "") return "off";
+   const value = raw.trim().toLowerCase();
+   if ((PERSIST_STORAGE_MODES as readonly string[]).includes(value)) {
+      return value as PersistStorageMode;
+   }
+   throw new Error(
+      `PERSIST_STORAGE_MODE must be one of ${PERSIST_STORAGE_MODES.join(
+         " | ",
+      )} (got ${JSON.stringify(raw)})`,
+   );
+};
+
+/**
+ * Whether a within-package persist-target COLLISION (two distinct persist
+ * sources resolving to the same physical table in the same destination) is a
+ * hard publish rejection, from `PERSIST_COLLISION_ENFORCE` (default `false`).
+ *
+ * Staged on purpose: a package published BEFORE this check existed may carry a
+ * latent collision, so the check ships warn-only — surfaced at load and publish
+ * (so operators can find and remediate) but NOT blocking a re-publish. Flip this
+ * to `true` only after auditing and remediating known collisions, so the
+ * transition to reject-at-publish is deliberate and doesn't break routine
+ * re-publishes of existing packages. Load is ALWAYS warn-only regardless — the
+ * flag only governs whether publish rejects.
+ */
+export const getPersistCollisionEnforce = (): boolean =>
+   // parseBoolEnv, not an ad-hoc === "true": an operator who writes `1` or `yes`
+   // has asked for the check to block, and an ad-hoc compare would silently leave
+   // it warn-only — the flag failing open in exactly the direction it exists to
+   // prevent. A typo throws at startup, like every other flag here.
+   parseBoolEnv("PERSIST_COLLISION_ENFORCE") ?? false;
+
 function substituteEnvVars(value: string): string {
    const envVarPattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 

package/src/controller/materialization.controller.spec.ts

@@ -128,6 +128,68 @@ describe("MaterializationController.createMaterialization validation", () => {
       });
    });
 
+   it("preserves the storage `destination` on a build instruction", async () => {
+      // Regression: `destination` is the orchestrated `storage=` axis. Dropping it
+      // here silently downgrades an orchestrated build to a colocated
+      // build, so it never materializes into the storage destination.
+      const parsed = await parse({
+         buildInstructions: {
+            sources: [
+               {
+                  sourceEntityId: "b2",
+                  materializedTableId: "mt-2",
+                  physicalTableName: "downstream_v1",
+                  realization: "COPY",
+                  destination: "lake",
+               },
+            ],
+         },
+      });
+      expect(parsed.buildInstructions).toEqual([
+         {
+            sourceEntityId: "b2",
+            sourceID: undefined,
+            materializedTableId: "mt-2",
+            physicalTableName: "downstream_v1",
+            realization: "COPY",
+            destination: "lake",
+         },
+      ]);
+   });
+
+   it("preserves the optional `connectionName` on a manifest reference", async () => {
+      // Regression: `connectionName` (added by #904) lets the seed loop dialect-
+      // quote the referenced upstream for a case-folding engine. Dropping it here
+      // silently reverts to an unquoted seed — the same manual-copy drift that
+      // dropped BuildInstruction.destination.
+      const parsed = await parse({
+         buildInstructions: {
+            sources: [
+               {
+                  sourceEntityId: "b2",
+                  materializedTableId: "mt-2",
+                  physicalTableName: "downstream_v1",
+                  realization: "COPY",
+               },
+            ],
+            referenceManifest: [
+               {
+                  sourceEntityId: "b1",
+                  physicalTableName: "upstream_table",
+                  connectionName: "sf",
+               },
+            ],
+         },
+      });
+      expect(parsed.referenceManifest).toEqual([
+         {
+            sourceEntityId: "b1",
+            physicalTableName: "upstream_table",
+            connectionName: "sf",
+         },
+      ]);
+   });
+
    it("rejects a referenceManifest entry missing a required field", async () => {
       const { controller } = build();
       await expect(

package/src/controller/materialization.controller.ts

@@ -141,6 +141,14 @@ export class MaterializationController {
       return {
          sourceEntityId: ref.sourceEntityId as string,
          physicalTableName: ref.physicalTableName as string,
+         // The connection the upstream table lives on. Optional; carried through
+         // so the seed loop can dialect-quote the reference for a case-folding
+         // engine (#904). Dropping it silently reverts to an unquoted seed, which
+         // fails a downstream build on such an engine — the same manual-copy drift
+         // that dropped BuildInstruction.destination.
+         ...(typeof ref.connectionName === "string"
+            ? { connectionName: ref.connectionName }
+            : {}),
       };
    }
 
@@ -179,6 +187,13 @@ export class MaterializationController {
          materializedTableId: instruction.materializedTableId as string,
          physicalTableName: instruction.physicalTableName as string,
          realization: instruction.realization,
+         // The `storage=` destination the orchestrator targets. Optional in the
+         // schema; must be carried through, or an orchestrated build silently
+         // falls back to a colocated build (isStorageBuild=false) and
+         // never materializes into the storage destination.
+         ...(typeof instruction.destination === "string"
+            ? { destination: instruction.destination }
+            : {}),
       };
    }
 

package/src/controller/package.controller.spec.ts

@@ -19,6 +19,7 @@ describe("PackageController.addPackage explores validation", () => {
       const mockPackage = {
          formatInvalidExplores: () => invalidMsg,
          formatInvalidPersistencePolicy: () => "",
+         formatPersistenceCollisionRejections: () => "",
       };
       const unloadPackage = sinon.stub().resolves(undefined);
       const deletePackage = sinon.stub().resolves(undefined);
@@ -56,6 +57,7 @@ describe("PackageController.addPackage explores validation", () => {
       const mockPackage = {
          formatInvalidExplores: () => invalidMsg,
          formatInvalidPersistencePolicy: () => "",
+         formatPersistenceCollisionRejections: () => "",
       };
       // installPackage mimics the real contract: invoke the validator and, if it
       // returns a message, throw BadRequestError (after its internal rollback).
@@ -105,6 +107,7 @@ describe("PackageController.addPackage explores validation", () => {
       const mockPackage = {
          formatInvalidExplores: () => "",
          formatInvalidPersistencePolicy: () => "",
+         formatPersistenceCollisionRejections: () => "",
       };
       const addPackage = sinon.stub().resolves(mockPackage);
       const getEnvironment = sinon.stub().resolves({ addPackage });
@@ -143,6 +146,7 @@ describe("PackageController.addPackage persistence policy validation", () => {
       const mockPackage = {
          formatInvalidExplores: () => "",
          formatInvalidPersistencePolicy: () => cronMsg,
+         formatPersistenceCollisionRejections: () => "",
       };
       const unloadPackage = sinon.stub().resolves(undefined);
       const addPackage = sinon.stub().resolves(mockPackage);
@@ -172,6 +176,7 @@ describe("PackageController.addPackage persistence policy validation", () => {
       const mockPackage = {
          formatInvalidExplores: () => "",
          formatInvalidPersistencePolicy: () => cronMsg,
+         formatPersistenceCollisionRejections: () => "",
       };
       const installPackage = sinon
          .stub()
@@ -226,6 +231,7 @@ describe("PackageController.updatePackage explores validation", () => {
          formatInvalidExplores: (override?: string[]) =>
             override?.includes("nope.malloy") ? invalidMsg : "",
          formatInvalidPersistencePolicy: () => "",
+         formatPersistenceCollisionRejections: () => "",
       };
       const installPackage = sinon
          .stub()

package/src/controller/package.controller.ts

@@ -18,19 +18,24 @@ export type PackageReloadMode = "in-place" | "reinstalled";
  * the Malloy Persistence policy gate (scope is package-level; a
  * `materialization.schedule` is package-root-only + version-scope-only and
  * mutually exclusive with freshness; per-source `sharing`/`schedule` are
- * retired — see Package.persistencePolicyWarnings). At startup/reload both are
- * warn-only instead (fail-safe; see Package.loadViaWorker).
+ * retired — see Package.persistencePolicyWarnings), plus persist-target
+ * collisions ONLY when `PERSIST_COLLISION_ENFORCE` is set (otherwise those are
+ * surfaced warn-only so a pre-existing latent collision doesn't block a routine
+ * re-publish — see Package.formatPersistenceCollisionRejections). At
+ * startup/reload all are warn-only instead (fail-safe; see Package.loadViaWorker).
  */
 function formatPublishRejections(
    pkg: {
       formatInvalidExplores(exploresOverride?: string[]): string;
       formatInvalidPersistencePolicy(): string;
+      formatPersistenceCollisionRejections(): string;
    },
    exploresOverride?: string[],
 ): string | undefined {
    const message = [
       pkg.formatInvalidExplores(exploresOverride),
       pkg.formatInvalidPersistencePolicy(),
+      pkg.formatPersistenceCollisionRejections(),
    ]
       .filter(Boolean)
       .join("\n");

package/src/controller/query.controller.ts

@@ -3,6 +3,7 @@ import { components } from "../api";
 import { getQueryTimeoutMs } from "../config";
 import { API_PREFIX } from "../constants";
 import { ModelNotFoundError } from "../errors";
+import { bigIntReplacer } from "../json_utils";
 import { runWithQueryTimeout } from "../query_timeout";
 import { EnvironmentStore } from "../service/environment_store";
 import type { FilterParams } from "../service/filter";
@@ -10,14 +11,6 @@ import type { GivenValue } from "@malloydata/malloy";
 
 type ApiQuery = components["schemas"]["QueryResult"];
 
-// Replacer function to handle BigInt serialization
-function bigIntReplacer(_key: string, value: unknown): unknown {
-   if (typeof value === "bigint") {
-      return Number(value);
-   }
-   return value;
-}
-
 export class QueryController {
    private environmentStore: EnvironmentStore;
 
@@ -53,19 +46,20 @@ export class QueryController {
       if (!model) {
          throw new ModelNotFoundError(`${modelPath} does not exist`);
       } else {
-         const { result, compactResult } = await runWithQueryTimeout(
-            (abortSignal) =>
-               model.getQueryResults(
-                  sourceName,
-                  queryName,
-                  query,
-                  filterParams,
-                  bypassFilters,
-                  givens,
-                  abortSignal,
-               ),
-            getQueryTimeoutMs(),
-         );
+         const { result, compactResult, rowLimit, rowLimitSource } =
+            await runWithQueryTimeout(
+               (abortSignal) =>
+                  model.getQueryResults(
+                     sourceName,
+                     queryName,
+                     query,
+                     filterParams,
+                     bypassFilters,
+                     givens,
+                     abortSignal,
+                  ),
+               getQueryTimeoutMs(),
+            );
          const renderLogs = validateRenderTags(result);
          return {
             result: compactJson
@@ -73,6 +67,17 @@ export class QueryController {
                : JSON.stringify(result),
             resource: `${API_PREFIX}/environments/${environmentName}/packages/${packageName}/models/${modelPath}/query`,
             renderLogs: renderLogs.length > 0 ? renderLogs : undefined,
+            // The cap the database applied. A caller counting the rows it got
+            // back cannot otherwise tell a complete result from one the limit
+            // cut off: a query with no LIMIT of its own silently gets the
+            // server default, which is well under the hard ceiling, so nothing
+            // raises. Deriving it client-side is not possible, since it depends
+            // on server config and on the query's own LIMIT.
+            queryRowLimit: rowLimit,
+            // Which of the two that cap was. Without it a caller cannot tell a
+            // deliberate `limit:`/`top:` from the silently-applied default, and
+            // so cannot reproduce the MCP envelope's _limit_hit.
+            queryRowLimitSource: rowLimitSource,
          } as ApiQuery;
       }
    }

package/src/errors.ts

@@ -24,6 +24,8 @@ export function internalErrorToHttpError(error: Error) {
       return httpError(422, error.message);
    } else if (error instanceof UnsupportedCatalogFormatError) {
       return httpError(422, error.message);
+   } else if (error instanceof MaterializationEligibilityError) {
+      return httpError(422, error.message);
    } else if (error instanceof ModelCompilationError) {
       return httpError(424, error.message);
    } else if (error instanceof ConnectionError) {
@@ -122,6 +124,23 @@ export class ModelCompilationError extends Error {
    }
 }
 
+/**
+ * A persist source was asked to materialize into a `storage=` destination (the
+ * DuckDB/DuckLake tier) but is ineligible: it has an unbound free parameter, it
+ * references a given (an RLAC/tenant-isolation refusal), or its served shape
+ * does not compile in DuckDB. Mapped to HTTP **422** (the request is
+ * well-formed, but the source cannot be processed into a materialized artifact)
+ * — a hard refuse, never a silent fallback. Kept a distinct class so the
+ * givens/RLAC refusal is greppable for security review. Accepts a
+ * message-bearing object to match {@link ModelCompilationError}'s ergonomics.
+ */
+export class MaterializationEligibilityError extends Error {
+   constructor(error: { message: string }) {
+      super(error.message);
+      this.name = "MaterializationEligibilityError";
+   }
+}
+
 export class FrozenConfigError extends Error {
    constructor(
       message = `Publisher config can't be updated when ${PUBLISHER_CONFIG_NAME} has { "frozenConfig": true }`,

package/src/json_utils.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "bun:test";
+import { bigIntReplacer } from "./json_utils";
+
+const ser = (v: unknown) => JSON.stringify(v, bigIntReplacer);
+
+describe("bigIntReplacer", () => {
+   it("still renders ordinary BigInt ids as numbers", () => {
+      // The common case, and the one that must not change: a DuckDB BIGINT
+      // column of ordinary ids has always reached callers as JSON numbers, and
+      // the MCP rows are byte-compared against the REST payload.
+      expect(ser({ id: 100001n })).toBe('{"id":100001}');
+      expect(ser({ c: 0n })).toBe('{"c":0}');
+      expect(ser({ c: -42n })).toBe('{"c":-42}');
+   });
+
+   it("keeps the largest exactly-representable values as numbers", () => {
+      expect(ser({ v: 9007199254740991n })).toBe('{"v":9007199254740991}');
+      expect(ser({ v: -9007199254740991n })).toBe('{"v":-9007199254740991}');
+   });
+
+   /**
+    * The regression this guards. Number() rounds past 2^53, so an id came back
+    * altered with no error: an agent filtering or joining on it gets a wrong or
+    * empty answer. Malloy's own wrapResult keeps an exact string for the same
+    * case, so a string here matches what the typed-cell path already did.
+    */
+   it("preserves values past the safe range exactly, as strings", () => {
+      expect(ser({ id: 9007199254740993n })).toBe('{"id":"9007199254740993"}');
+      expect(ser({ id: 1234567890123456789n })).toBe(
+         '{"id":"1234567890123456789"}',
+      );
+      expect(ser({ id: -9007199254740993n })).toBe(
+         '{"id":"-9007199254740993"}',
+      );
+   });
+
+   it("round-trips a large id without losing a digit", () => {
+      const exact = "9223372036854775807"; // int64 max
+      expect(JSON.parse(ser({ id: BigInt(exact) })).id).toBe(exact);
+   });
+
+   it("leaves non-BigInt values alone", () => {
+      expect(ser({ a: 1, b: "x", c: null, d: 1.5 })).toBe(
+         '{"a":1,"b":"x","c":null,"d":1.5}',
+      );
+   });
+
+   it("does not throw on the BigInt a plain stringify would reject", () => {
+      expect(() => ser({ c: 150930n })).not.toThrow();
+   });
+});

package/src/json_utils.ts

@@ -0,0 +1,33 @@
+/**
+ * JSON.stringify replacer for raw driver output, which can carry BigInt.
+ *
+ * Load-bearing wherever `compactResult` is serialized: it is
+ * `queryResults.data.value` straight from the connector, and a DuckDB BIGINT
+ * column arrives as a JS BigInt, so a plain JSON.stringify throws
+ * `TypeError: Do not know how to serialize a BigInt`. The wrapped
+ * `Malloy.Result` path does not need this, because API.util.wrapResult has
+ * already normalized values into typed cells.
+ *
+ * Values inside the safe integer range become numbers, which is what callers
+ * have always received and what keeps the MCP and REST payloads byte-identical.
+ * Outside it `Number()` rounds silently: 9007199254740993 becomes ...992, and an
+ * agent that filters or joins on that id gets a wrong or empty answer with no
+ * error. Those are emitted as strings instead, which is what Malloy itself does
+ * for the same case (API.util.wrapResult attaches an exact `string_value`
+ * beside the lossy `number_value` whenever the subtype is bigint).
+ *
+ * So the JSON type varies with magnitude. That is deliberate: a column only
+ * yields a string for a value a JSON number cannot represent, and every such
+ * value was previously being corrupted, so nothing a caller correctly receives
+ * today changes.
+ */
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+
+export function bigIntReplacer(_key: string, value: unknown): unknown {
+   if (typeof value === "bigint") {
+      return value > MAX_SAFE_BIGINT || value < -MAX_SAFE_BIGINT
+         ? value.toString()
+         : Number(value);
+   }
+   return value;
+}

package/src/logger.spec.ts

@@ -1,8 +1,25 @@
 import { describe, expect, it } from "bun:test";
 import type { AxiosError } from "axios";
-import { buildAxiosErrorLog, redactSensitive } from "./logger";
+import {
+   SENSITIVE_KEY_NAMES,
+   buildAxiosErrorLog,
+   redactSensitive,
+} from "./logger";
 
 describe("redactSensitive", () => {
+   it("redacts every name in SENSITIVE_KEY_NAMES (reflective lock)", () => {
+      // Iterates the list itself so a newly-added credential field cannot
+      // be introduced without redaction, and pins apiKey/api_key.
+      const input: Record<string, string> = {};
+      for (const name of SENSITIVE_KEY_NAMES) input[name] = "leak-me";
+      const out = redactSensitive(input) as Record<string, unknown>;
+      for (const name of SENSITIVE_KEY_NAMES) {
+         expect(out[name]).toBe("[REDACTED]");
+      }
+      expect(SENSITIVE_KEY_NAMES).toContain("apiKey");
+      expect(SENSITIVE_KEY_NAMES).toContain("api_key");
+   });
+
    it("masks every known credential field at the top level", () => {
       const input = {
          password: "hunter2",