@malloy-publisher/server 0.0.232 → 0.0.234

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.232",
+   "version": "0.0.234",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"

package/src/config.ts

@@ -189,7 +189,7 @@ function parseFloatEnv(name: string): number | undefined {
    return value;
 }
 
-function parseBoolEnv(name: string): boolean | undefined {
+export function parseBoolEnv(name: string): boolean | undefined {
    const raw = process.env[name];
    if (raw === undefined || raw.trim() === "") return undefined;
    const normalised = raw.trim().toLowerCase();
@@ -615,6 +615,40 @@ export const getPersistCollisionEnforce = (): boolean =>
    // prevent. A typo throws at startup, like every other flag here.
    parseBoolEnv("PERSIST_COLLISION_ENFORCE") ?? false;
 
+/**
+ * Whether the publisher attaches per-query metadata at all, from
+ * `PUBLISHER_QUERY_METADATA` (default `off`).
+ *
+ * Ships dark for a release, like `PERSIST_STORAGE_MODE` before it, and for the
+ * same reason: this is the rare feature that touches EVERY statement the server
+ * sends. On a backend with no native tag facility the bag rides as a leading SQL
+ * comment, so `on` changes the text of the statement (never its meaning or its
+ * results) and puts the bag in query logs and `pg_stat_activity`.
+ *
+ * The risk that decides the default is upstream, not here. Malloy validates the
+ * bag at dispatch and THROWS on one it cannot render, and the contract it
+ * validates against is mirrored in `service/query_metadata.ts` against a pinned
+ * version. Every mitigation on this path — clamping, shedding, never throwing —
+ * is downstream of that mirror being right, so a tightened upstream limit would
+ * surface as failing customer queries on a path nobody opted into. `off` for a
+ * release means a deployment turns attribution on deliberately, having read
+ * what it does to its statements.
+ *
+ * Case-insensitive; loud-fails on an unrecognized value, so a typo cannot
+ * silently leave a deployment that asked for attribution without it.
+ */
+export type QueryMetadataMode = "on" | "off";
+
+export const getQueryMetadataMode = (): QueryMetadataMode => {
+   const raw = process.env.PUBLISHER_QUERY_METADATA;
+   if (raw === undefined || raw.trim() === "") return "off";
+   const value = raw.trim().toLowerCase();
+   if (value === "on" || value === "off") return value;
+   throw new Error(
+      `PUBLISHER_QUERY_METADATA must be on | off (got ${JSON.stringify(raw)})`,
+   );
+};
+
 function substituteEnvVars(value: string): string {
    const envVarPattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 

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

@@ -60,6 +60,52 @@ function buildController(
    return { controller, runSQL, assertCanAdmitQuery };
 }
 
+describe("ConnectionController connection queryMetadata", () => {
+   afterEach(() => sinon.restore());
+
+   it("rejects a connection default the contract cannot render", async () => {
+      // The connection is the one metadata layer whose author is right here, so
+      // it is the one that can be told. `cost-centre` is the natural spelling
+      // and would otherwise be dropped at dispatch, leaving every statement on
+      // the connection missing the property its operator configured.
+      const { controller } = buildController(sinon.stub().resolves());
+      await expect(
+         controller.addConnection("env", "warehouse", {
+            name: "warehouse",
+            type: "postgres",
+            queryMetadata: { "cost-centre": "eng" },
+         }),
+      ).rejects.toThrow(/queryMetadata is invalid/);
+   });
+
+   it("rejects an enforced bag the contract cannot render", async () => {
+      const { controller } = buildController(sinon.stub().resolves());
+      await expect(
+         controller.addConnection("env", "warehouse", {
+            name: "warehouse",
+            type: "postgres",
+            queryMetadataEnforced: { "org.id": "acme" },
+         }),
+      ).rejects.toThrow(/queryMetadataEnforced is invalid/);
+   });
+
+   it("accepts a conforming connection default", async () => {
+      const { controller } = buildController(sinon.stub().resolves());
+      const addConnection = sinon.stub().resolves();
+      (
+         controller as unknown as {
+            connectionService: { addConnection: sinon.SinonStub };
+         }
+      ).connectionService = { addConnection } as never;
+      await controller.addConnection("env", "warehouse", {
+         name: "warehouse",
+         type: "postgres",
+         queryMetadata: { cost_centre: "eng" },
+      });
+      expect(addConnection.calledOnce).toBe(true);
+   });
+});
+
 describe("ConnectionController.getConnectionQueryData row cap", () => {
    const originalEnv = process.env.PUBLISHER_MAX_QUERY_ROWS;
 

package/src/controller/connection.controller.ts

@@ -21,6 +21,15 @@ import {
    getSchemasForConnection,
    listTablesForSchema,
 } from "../service/db_utils";
+import {
+   mergeQueryMetadata,
+   mintCorrelationId,
+   parseQueryClass,
+   parseSuppliedQueryMetadata,
+   queryMetadataViolations,
+   type QueryClass,
+   type QueryMetadata,
+} from "../service/query_metadata";
 import type { Environment } from "../service/environment";
 import { EnvironmentStore } from "../service/environment_store";
 import { isStreamingConnection, streamSqlWithBudget } from "../stream_helpers";
@@ -112,6 +121,22 @@ function validateAdminAuthoredConnection(
    } catch (error) {
       throw new BadRequestError((error as Error).message);
    }
+
+   // The connection is the one metadata layer whose author is right here, so it
+   // is the one that can be told. A property the contract rejects (a hyphen in
+   // `cost-centre` is the natural spelling and the first thing anyone tries)
+   // would otherwise be dropped at dispatch and only ever surface as a metric —
+   // every statement on the connection missing the property its operator
+   // believes they configured. Config LOAD warns instead of throwing (see
+   // assembleEnvironmentConnections): a tag must never fail an environment.
+   for (const field of ["queryMetadata", "queryMetadataEnforced"] as const) {
+      const violations = queryMetadataViolations(connectionConfig[field]);
+      if (violations.length > 0) {
+         throw new BadRequestError(
+            `Connection "${connectionName}" ${field} is invalid: ${violations.join("; ")}`,
+         );
+      }
+   }
 }
 
 export class ConnectionController {
@@ -140,6 +165,43 @@ export class ConnectionController {
       return environment.getApiConnection(connectionName);
    }
 
+   /**
+    * A connection's default per-query metadata, or null when it declares none.
+    * Fails open: metadata is observability, so a connection whose config can't be
+    * read contributes no default rather than failing the query the caller asked
+    * for.
+    */
+   private async connectionQueryMetadata(
+      environmentName: string,
+      connectionName: string,
+   ): Promise<{
+      default: QueryMetadata | null;
+      enforced: QueryMetadata | null;
+   }> {
+      try {
+         const environment = await this.environmentStore.getEnvironment(
+            environmentName,
+            false,
+         );
+         const connection = this.getApiConnectionForLookup(
+            environment,
+            connectionName,
+         );
+         return {
+            default: connection.queryMetadata ?? null,
+            enforced: connection.queryMetadataEnforced ?? null,
+         };
+      } catch (error) {
+         // Fails open like every other metadata path, but not invisibly: the
+         // layer lost here is the enforced one, and no metric covers it.
+         logger.debug("No query-metadata layers for connection", {
+            connectionName,
+            error,
+         });
+         return { default: null, enforced: null };
+      }
+   }
+
    private async getMalloyConnection(
       environmentName: string,
       connectionName: string,
@@ -453,6 +515,12 @@ export class ConnectionController {
       sqlStatement: string,
       options: string,
       packageName?: string,
+      /**
+       * The request's per-query metadata fields, unvalidated — this controller is
+       * the boundary that turns a bad bag into a 400 rather than letting the
+       * connector refuse the statement at dispatch.
+       */
+      metadata?: { queryMetadata?: unknown; queryClass?: unknown },
    ): Promise<ApiQueryData> {
       // Express parses repeated query parameters (?sqlStatement=a&sqlStatement=b)
       // and array-shaped JSON bodies as `string[]`, not `string`. The route
@@ -512,6 +580,41 @@ export class ConnectionController {
          runSQLOptions.abortSignal = undefined;
       }
 
+      // Per-query metadata. Validated here, not clamped: a raw-SQL caller gets a
+      // 400 telling it which property is wrong instead of a statement the
+      // connector refuses at dispatch. `options` is forwarded as RunSQLOptions, so
+      // a bag can also arrive inside it — validate that one too, and let the
+      // documented field win.
+      const suppliedMetadata =
+         metadata?.queryMetadata ?? runSQLOptions.queryMetadata;
+      let requestMetadata: QueryMetadata | undefined;
+      let queryClass: QueryClass | undefined;
+      try {
+         requestMetadata = parseSuppliedQueryMetadata(suppliedMetadata);
+         queryClass = parseQueryClass(metadata?.queryClass);
+      } catch (error) {
+         throw new BadRequestError((error as Error).message);
+      }
+      const connectionLayers = await this.connectionQueryMetadata(
+         environmentName,
+         connectionName,
+      );
+      const resolvedMetadata = mergeQueryMetadata({
+         connection: connectionLayers.default,
+         enforced: connectionLayers.enforced,
+         request: requestMetadata,
+         context: {
+            // Raw SQL against a connection is platform maintenance unless the
+            // caller says otherwise — it is not a modeled query.
+            queryClass: queryClass ?? "ops",
+            environment: environmentName,
+            package: packageName,
+            correlationId: mintCorrelationId(),
+         },
+      });
+      runSQLOptions.queryMetadata = resolvedMetadata.metadata;
+      const queryCorrelationId = resolvedMetadata.metadata?.query_id ?? null;
+
       // Bound the response with two layered caps:
       //
       //   - Row cap (PUBLISHER_MAX_QUERY_ROWS) — pushed to the driver as
@@ -572,7 +675,7 @@ export class ConnectionController {
                throw new ConnectionError((error as Error).message);
             }
          }, getQueryTimeoutMs());
-         return { data: JSON.stringify(streamed) };
+         return { data: JSON.stringify(streamed), queryCorrelationId };
       }
 
       const result = await runWithQueryTimeout(async (signal) => {
@@ -601,7 +704,7 @@ export class ConnectionController {
          );
       }
 
-      return { data: JSON.stringify(result) };
+      return { data: JSON.stringify(result), queryCorrelationId };
    }
 
    public async getConnectionTemporaryTable(

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

@@ -265,4 +265,29 @@ describe("MaterializationController.createMaterialization validation", () => {
          }),
       ).rejects.toThrow(BadRequestError);
    });
+
+   it("rejects a runId the metadata contract cannot carry", async () => {
+      // runId becomes the `run_id` property on every statement of the build, so
+      // an over-long or unrenderable value is silently truncated and rewritten
+      // at dispatch — leaving the caller holding an id that joins to nothing.
+      // The neighbouring `trigger` is enum-validated; this is the same kind of
+      // boundary and gets the same treatment.
+      const { controller } = build();
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            runContext: { runId: "x".repeat(300) },
+         }),
+      ).rejects.toThrow(BadRequestError);
+      await expect(
+         controller.createMaterialization("env", "pkg", {
+            runContext: { runId: 'has "quotes"' },
+         }),
+      ).rejects.toThrow(BadRequestError);
+   });
+
+   it("still accepts a conforming runId", async () => {
+      expect(
+         await parse({ runContext: { trigger: "publish", runId: "run-42" } }),
+      ).toEqual({ runContext: { trigger: "publish", runId: "run-42" } });
+   });
 });

package/src/controller/materialization.controller.ts

@@ -1,9 +1,15 @@
+import type { components } from "../api";
 import { BadRequestError } from "../errors";
 import {
    BuildInstruction,
    ManifestReference,
 } from "../storage/DatabaseInterface";
 import { MaterializationService } from "../service/materialization_service";
+import { queryMetadataViolations } from "../service/query_metadata";
+
+type RunContext = components["schemas"]["RunContext"];
+
+const RUN_TRIGGERS = ["publish", "on_demand", "scheduler"] as const;
 
 export class MaterializationController {
    constructor(private materializationService: MaterializationService) {}
@@ -31,6 +37,7 @@ export class MaterializationController {
       buildInstructions?: BuildInstruction[];
       referenceManifest?: ManifestReference[];
       strictUpstreams?: boolean;
+      runContext?: RunContext;
    } {
       const result: {
          forceRefresh?: boolean;
@@ -38,7 +45,11 @@ export class MaterializationController {
          buildInstructions?: BuildInstruction[];
          referenceManifest?: ManifestReference[];
          strictUpstreams?: boolean;
+         runContext?: RunContext;
       } = {};
+      if (body.runContext !== undefined && body.runContext !== null) {
+         result.runContext = this.validateRunContext(body.runContext);
+      }
       if (
          body.buildInstructions !== undefined &&
          body.buildInstructions !== null
@@ -72,6 +83,55 @@ export class MaterializationController {
       return result;
    }
 
+   /**
+    * Validate `runContext`, the caller's observability context for one run.
+    * `trigger` is a closed enum here even though it feeds a metadata property:
+    * the whole point is that a reader can group runs by how they started, which a
+    * free-form value would quietly break.
+    *
+    * Note this is NOT the service-level `trigger` the parser above deliberately
+    * refuses. That one decides whether the run counts as scheduled; this one only
+    * labels the statements the run issues, so accepting `publish` from a caller
+    * forges nothing.
+    */
+   private validateRunContext(raw: unknown): RunContext {
+      if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+         throw new BadRequestError("runContext must be an object");
+      }
+      const obj = raw as Record<string, unknown>;
+      const context: RunContext = {};
+      if (obj.trigger !== undefined && obj.trigger !== null) {
+         if (
+            typeof obj.trigger !== "string" ||
+            !RUN_TRIGGERS.includes(obj.trigger as (typeof RUN_TRIGGERS)[number])
+         ) {
+            throw new BadRequestError(
+               `runContext.trigger must be one of ${RUN_TRIGGERS.join(" | ")}`,
+            );
+         }
+         context.trigger = obj.trigger as RunContext["trigger"];
+      }
+      if (obj.runId !== undefined && obj.runId !== null) {
+         if (typeof obj.runId !== "string") {
+            throw new BadRequestError("runContext.runId must be a string");
+         }
+         // Held to the metadata contract like any other caller-supplied
+         // property: it becomes the `run_id` on every statement of the build,
+         // and a value the contract rejects would otherwise be truncated and
+         // rewritten in silence — leaving the caller with an id it cannot join
+         // on and no way to know why.
+         const violations = queryMetadataViolations({ run_id: obj.runId });
+         if (violations.length > 0) {
+            throw new BadRequestError(
+               `runContext.runId is attached to every statement as the run_id ` +
+                  `property: ${violations.join("; ")}`,
+            );
+         }
+         context.runId = obj.runId;
+      }
+      return context;
+   }
+
    /**
     * Validate the orchestrated `buildInstructions` payload (BuildInstructions:
     * `{ sources: BuildInstruction[], referenceManifest?, strictUpstreams? }`)

package/src/controller/model.controller.ts

@@ -1,6 +1,7 @@
 import { components } from "../api";
 import { getQueryTimeoutMs } from "../config";
 import { ModelNotFoundError } from "../errors";
+import { logger } from "../logger";
 import { runWithQueryTimeout } from "../query_timeout";
 import { EnvironmentStore } from "../service/environment_store";
 import type { FilterParams } from "../service/filter";
@@ -133,6 +134,29 @@ export class ModelController {
                bypassFilters,
                givens,
                abortSignal,
+               {
+                  environment: environmentName,
+                  // The environment owns the connection configs, so the default
+                  // and enforced layers are read here rather than from the model.
+                  connectionMetadata: (connectionName) => {
+                     try {
+                        const connection =
+                           environment.getApiConnection(connectionName);
+                        return {
+                           default: connection.queryMetadata,
+                           enforced: connection.queryMetadataEnforced,
+                        };
+                     } catch (error) {
+                        // Fails open, and says so: what an unreadable
+                        // connection costs is the enforced layer.
+                        logger.debug(
+                           "No query-metadata layers for connection",
+                           { connectionName, error },
+                        );
+                        return null;
+                     }
+                  },
+               },
             ),
          getQueryTimeoutMs(),
       );

package/src/controller/query.controller.ts

@@ -2,7 +2,16 @@ import { validateRenderTags } from "@malloydata/render-validator";
 import { components } from "../api";
 import { getQueryTimeoutMs } from "../config";
 import { API_PREFIX } from "../constants";
-import { ModelNotFoundError } from "../errors";
+import { BadRequestError, ModelNotFoundError } from "../errors";
+import { bigIntReplacer } from "../json_utils";
+import { logger } from "../logger";
+import {
+   mintCorrelationId,
+   parseQueryClass,
+   parseSuppliedQueryMetadata,
+   type QueryClass,
+   type QueryMetadata,
+} from "../service/query_metadata";
 import { runWithQueryTimeout } from "../query_timeout";
 import { EnvironmentStore } from "../service/environment_store";
 import type { FilterParams } from "../service/filter";
@@ -10,14 +19,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;
 
@@ -36,7 +37,26 @@ export class QueryController {
       filterParams?: FilterParams,
       bypassFilters?: boolean,
       givens?: Record<string, GivenValue>,
+      /**
+       * The request's per-query metadata fields, unvalidated — this controller is
+       * the boundary that turns a bad bag into a 400 rather than letting the
+       * connector refuse the statement at dispatch.
+       */
+      metadata?: {
+         queryMetadata?: unknown;
+         queryClass?: unknown;
+         versionId?: string;
+      },
    ): Promise<ApiQuery> {
+      let requestMetadata: QueryMetadata | undefined;
+      let queryClass: QueryClass | undefined;
+      try {
+         requestMetadata = parseSuppliedQueryMetadata(metadata?.queryMetadata);
+         queryClass = parseQueryClass(metadata?.queryClass);
+      } catch (error) {
+         throw new BadRequestError((error as Error).message);
+      }
+
       const environment = await this.environmentStore.getEnvironment(
          environmentName,
          false,
@@ -53,7 +73,13 @@ export class QueryController {
       if (!model) {
          throw new ModelNotFoundError(`${modelPath} does not exist`);
       } else {
-         const { result, compactResult } = await runWithQueryTimeout(
+         const {
+            result,
+            compactResult,
+            rowLimit,
+            rowLimitSource,
+            queryCorrelationId,
+         } = await runWithQueryTimeout(
             (abortSignal) =>
                model.getQueryResults(
                   sourceName,
@@ -63,6 +89,41 @@ export class QueryController {
                   bypassFilters,
                   givens,
                   abortSignal,
+                  {
+                     request: requestMetadata,
+                     queryClass,
+                     environment: environmentName,
+                     // Always undefined today: the route 501s any versionId
+                     // before this runs. Wired so that lifting that rejection
+                     // is the whole change.
+                     version: metadata?.versionId,
+                     // Minted here because this is the boundary that returns
+                     // it; a path with nowhere to put it does not mint one.
+                     correlationId: mintCorrelationId(),
+                     // The environment owns the connection configs, so the
+                     // default and enforced layers are read here rather than
+                     // from the model.
+                     connectionMetadata: (connectionName) => {
+                        try {
+                           const connection =
+                              environment.getApiConnection(connectionName);
+                           return {
+                              default: connection.queryMetadata,
+                              enforced: connection.queryMetadataEnforced,
+                           };
+                        } catch (error) {
+                           // Failing open is right — a tag must not fail a
+                           // query — but this is the one drop with no metric
+                           // behind it, and what it costs is the ENFORCED
+                           // layer. Log it so it is diagnosable.
+                           logger.debug(
+                              "No query-metadata layers for connection",
+                              { connectionName, error },
+                           );
+                           return null;
+                        }
+                     },
+                  },
                ),
             getQueryTimeoutMs(),
          );
@@ -73,6 +134,18 @@ 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,
+            queryCorrelationId,
          } as ApiQuery;
       }
    }

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;
+}