@malloy-publisher/server 0.0.226 → 0.0.228

package/src/service/package_reload_safety.spec.ts

@@ -0,0 +1,193 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+
+import { Environment, PackageStatus } from "./environment";
+
+/**
+ * Regression tests for RELOAD data loss.
+ *
+ * `Package.create`'s failure cleanup was written for a fresh install, where the
+ * half-built tree is Publisher's to remove. A reload runs the same code against
+ * a directory that already exists and is already serving, so a model that
+ * failed to compile deleted the user's package directory and evicted the
+ * last-good compiled model, taking the package offline until it was
+ * re-provisioned. That is reachable from the reload endpoint and the
+ * malloy_reloadPackage MCP tool by any caller that saves a broken model and
+ * reloads, which is the ordinary authoring mistake.
+ *
+ * Directory cleanup is now opt-in and only `installPackage` asks for it, so
+ * these two guard the reload path. Run against a real `Environment` and a real
+ * `Package.create` over temp dirs, the same way package_rollback.spec.ts does.
+ */
+describe("failed reload does not destroy a serving package", () => {
+   let rootDir: string;
+   let envPath: string;
+
+   const GOOD_MODEL = `source: ones is duckdb.sql("SELECT 1 as x")\n`;
+   const BROKEN_MODEL = `source: broken is @@@ not valid malloy !!!\n`;
+
+   async function writePackageDir(dir: string, model: string): Promise<void> {
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(
+         path.join(dir, "publisher.json"),
+         JSON.stringify({ name: "pkg", description: "reload fixture" }),
+      );
+      await fs.writeFile(path.join(dir, "model.malloy"), model);
+   }
+
+   async function copyDir(src: string, dst: string): Promise<void> {
+      await fs.mkdir(dst, { recursive: true });
+      await fs.cp(src, dst, { recursive: true });
+   }
+
+   beforeEach(async () => {
+      rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "publisher-reload-"));
+      envPath = path.join(rootDir, "env");
+      await fs.mkdir(envPath, { recursive: true });
+   });
+
+   afterEach(async () => {
+      await fs.rm(rootDir, { recursive: true, force: true }).catch(() => {});
+   });
+
+   it("keeps the package directory on disk when the reloaded model does not compile", async () => {
+      const env = await Environment.create("testEnv", envPath, []);
+      const pkgDir = path.join(envPath, "pkg");
+      await writePackageDir(pkgDir, GOOD_MODEL);
+      await env.addPackage("pkg");
+
+      // The ordinary authoring mistake: save something that does not compile,
+      // then reload.
+      await fs.writeFile(path.join(pkgDir, "model.malloy"), BROKEN_MODEL);
+      await expect(env.getPackage("pkg", true)).rejects.toThrow();
+
+      // The directory and the file the user was editing both survive.
+      const modelText = await fs.readFile(
+         path.join(pkgDir, "model.malloy"),
+         "utf-8",
+      );
+      expect(modelText).toBe(BROKEN_MODEL);
+   });
+
+   it("keeps serving the last good model after a failed reload", async () => {
+      const env = await Environment.create("testEnv", envPath, []);
+      const pkgDir = path.join(envPath, "pkg");
+      await writePackageDir(pkgDir, GOOD_MODEL);
+      await env.addPackage("pkg");
+
+      const servingBefore = await env.getPackage("pkg", false);
+
+      await fs.writeFile(path.join(pkgDir, "model.malloy"), BROKEN_MODEL);
+      await expect(env.getPackage("pkg", true)).rejects.toThrow();
+
+      // The package is still loaded and answerable: a failed reload reports the
+      // compile error, it does not take the package down. Assert the exact
+      // state, not just that something is there: a status stranded at LOADING
+      // would satisfy toBeDefined() while listPackages skips it, so the package
+      // would answer getPackage and be invisible to listings and discovery.
+      const stillServing = await env.getPackage("pkg", false);
+      expect(stillServing).toBe(servingBefore);
+      expect(env.getPackageStatus("pkg")?.status).toBe(PackageStatus.SERVING);
+      expect((await env.listPackages()).map((p) => p.name)).toContain("pkg");
+   });
+
+   it("keeps a rolled-back reinstall listed and serving", async () => {
+      // The other reload path. A package with an install location reloads via
+      // installPackage, whose rollback restores the previous tree but used to
+      // drop the status while `packages` kept the old package: it answered
+      // getPackage but vanished from listPackages and discovery until a
+      // restart. Both maps must agree that it is still serving.
+      const env = await Environment.create("testEnv", envPath, []);
+      const goodFixture = path.join(rootDir, "good");
+      const brokenFixture = path.join(rootDir, "broken");
+      await writePackageDir(goodFixture, GOOD_MODEL);
+      await writePackageDir(brokenFixture, BROKEN_MODEL);
+
+      await env.installPackage("pkg", (stagingPath) =>
+         copyDir(goodFixture, stagingPath),
+      );
+      const servingBefore = await env.getPackage("pkg", false);
+
+      await expect(
+         env.installPackage("pkg", (stagingPath) =>
+            copyDir(brokenFixture, stagingPath),
+         ),
+      ).rejects.toThrow();
+
+      expect(env.getPackageStatus("pkg")?.status).toBe(PackageStatus.SERVING);
+      expect((await env.listPackages()).map((p) => p.name)).toContain("pkg");
+      expect(await env.getPackage("pkg", false)).toBe(servingBefore);
+      // The on-disk half of the same claim: the rejected tree is gone and the
+      // user's is back. Without this, nothing pins "your files are left alone".
+      expect(
+         await fs.readFile(path.join(envPath, "pkg", "model.malloy"), "utf-8"),
+      ).toBe(GOOD_MODEL);
+   });
+
+   it("does not advertise a package as serving when the rollback could not restore it", async () => {
+      // Keeping the last-good package served is only honest when the rollback
+      // actually put its tree back. If nothing was restored, the cached package
+      // no longer matches disk, and claiming SERVING would advertise a package
+      // over a canonical path that is missing or still holds rejected content.
+      const env = await Environment.create("testEnv", envPath, []);
+      const pkgDir = path.join(envPath, "pkg");
+      await writePackageDir(pkgDir, GOOD_MODEL);
+      await env.addPackage("pkg");
+      expect(env.getPackageStatus("pkg")?.status).toBe(PackageStatus.SERVING);
+
+      // Record retirements rather than scheduling the real drain, which is a
+      // 30s timer this test has no reason to wait on.
+      const retiredLabels: string[] = [];
+      (
+         env as unknown as {
+            retireConnectionGeneration: (label: string) => void;
+         }
+      ).retireConnectionGeneration = (label: string) => {
+         retiredLabels.push(label);
+      };
+
+      // The tree disappears from under Publisher, so the reinstall has nothing
+      // to retire and the rollback has nothing to restore.
+      await fs.rm(pkgDir, { recursive: true, force: true });
+
+      const brokenFixture = path.join(rootDir, "broken-nofallback");
+      await writePackageDir(brokenFixture, BROKEN_MODEL);
+      await expect(
+         env.installPackage("pkg", (stagingPath) =>
+            copyDir(brokenFixture, stagingPath),
+         ),
+      ).rejects.toThrow();
+
+      // Eviction is the honest outcome here, and both maps must agree on it.
+      expect(env.getPackageStatus("pkg")).toBeUndefined();
+      expect((await env.listPackages()).map((p) => p.name)).not.toContain(
+         "pkg",
+      );
+      // Assert the packages map too, not just the status: asserting only the
+      // status leaves the half that actually strands a package untested.
+      await expect(env.getPackage("pkg", false)).rejects.toThrow();
+
+      // Evicting must retire the old package's connections. Once it leaves
+      // this.packages, closeAllConnections cannot reach its MalloyConfig, so
+      // skipping the retire orphans its native handles for the process's life.
+      // The drain is timer-based, so assert it was scheduled, not that it ran.
+      expect(retiredLabels).toContain("package pkg");
+   });
+
+   it("recovers on the next reload once the model compiles again", async () => {
+      const env = await Environment.create("testEnv", envPath, []);
+      const pkgDir = path.join(envPath, "pkg");
+      await writePackageDir(pkgDir, GOOD_MODEL);
+      await env.addPackage("pkg");
+
+      await fs.writeFile(path.join(pkgDir, "model.malloy"), BROKEN_MODEL);
+      await expect(env.getPackage("pkg", true)).rejects.toThrow();
+
+      // Because nothing was deleted, fixing the model and reloading is enough.
+      await fs.writeFile(path.join(pkgDir, "model.malloy"), GOOD_MODEL);
+      const reloaded = await env.getPackage("pkg", true);
+      expect(reloaded).toBeDefined();
+   });
+});

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/fixtures/query-givens/data/orders.csv

@@ -0,0 +1,7 @@
+id,region,status,amount
+1,US,active,100
+2,US,active,200
+3,US,cancelled,50
+4,EU,active,300
+5,EU,cancelled,400
+6,EU,active,500

package/tests/fixtures/query-givens/model.malloy

@@ -0,0 +1,34 @@
+##! experimental.givens
+
+given: target_region :: string is 'US'
+given: min_amount :: number is 0
+given: role :: string is 'guest'
+
+#(filter) dimension=status type=equal
+source: orders is duckdb.table('data/orders.csv') extend {
+   primary_key: id
+
+   measure:
+      order_count is count()
+
+   view: by_given_region is {
+      where: region = $target_region and amount >= $min_amount
+      aggregate: order_count
+   }
+}
+
+// Gated variant for authorize-interaction coverage: only $role = 'admin' may
+// read it. Shares the givens above so we can prove the name-vs-value-vs-authorize
+// status matrix on a gated source.
+#(authorize) "$role = 'admin'"
+source: gated_orders is duckdb.table('data/orders.csv') extend {
+   primary_key: id
+
+   measure:
+      order_count is count()
+
+   view: by_given_region is {
+      where: region = $target_region and amount >= $min_amount
+      aggregate: order_count
+   }
+}

package/tests/fixtures/query-givens/publisher.json

@@ -0,0 +1,5 @@
+{
+  "name": "query-givens",
+  "version": "1.0.0",
+  "description": "Fixture for /query givens forwarding (server + SDK)"
+}

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();
 
 /**

package/tests/integration/mcp/mcp_execute_query_tool.integration.spec.ts

@@ -23,8 +23,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
    let env: McpE2ETestEnvironment | null = null;
    let mcpClient: Client;
 
-   const ENVIRONMENT_NAME = "malloy-samples";
-   const PACKAGE_NAME = "faa";
+   const ENVIRONMENT_NAME = "examples";
+   const PACKAGE_NAME = "storefront";
 
    beforeAll(async () => {
       // Setup the E2E environment (starts server, connects client)
@@ -49,8 +49,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
                arguments: {
                   environmentName: ENVIRONMENT_NAME,
                   packageName: PACKAGE_NAME,
-                  modelPath: "flights.malloy",
-                  query: "run: flights->{ aggregate: c is count() }",
+                  modelPath: "storefront.malloy",
+                  query: "run: order_items->{ aggregate: c is count() }",
                },
             });
 
@@ -97,9 +97,9 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             const params = {
                environmentName: ENVIRONMENT_NAME,
                packageName: PACKAGE_NAME,
-               modelPath: "flights.malloy",
-               sourceName: "flights", // Added sourceName
-               queryName: "top_carriers",
+               modelPath: "storefront.malloy",
+               sourceName: "order_items", // Added sourceName
+               queryName: "top_products",
             };
 
             // Expect RESOLUTION with success
@@ -142,8 +142,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             const params = {
                environmentName: ENVIRONMENT_NAME,
                packageName: PACKAGE_NAME,
-               modelPath: "flights.malloy",
-               query: "run: flights->{BAD SYNTAX aggregate: flight_count is count()}",
+               modelPath: "storefront.malloy",
+               query: "run: order_items->{BAD SYNTAX aggregate: order_count is count()}",
             };
 
             // Application Error (Malloy Compilation): Expect RESOLUTION with isError: true
@@ -181,9 +181,9 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const params = {
             environmentName: ENVIRONMENT_NAME,
             packageName: PACKAGE_NAME,
-            modelPath: "flights.malloy",
-            query: "run: flights->{aggregate: c is count()}",
-            queryName: "top_carriers",
+            modelPath: "storefront.malloy",
+            query: "run: order_items->{aggregate: c is count()}",
+            queryName: "top_products",
          };
 
          // Expect RESOLUTION because the error is thrown *inside* the handler
@@ -209,7 +209,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const params = {
             environmentName: ENVIRONMENT_NAME,
             packageName: PACKAGE_NAME,
-            modelPath: "flights.malloy",
+            modelPath: "storefront.malloy",
             // Missing query AND queryName
          };
 
@@ -237,7 +237,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             // Missing modelPath
             environmentName: ENVIRONMENT_NAME,
             packageName: PACKAGE_NAME,
-            query: "run: flights->{aggregate: flight_count is count()}",
+            query: "run: order_items->{aggregate: c is count()}",
          };
 
          // Protocol Error (Caught by Zod/MCP): Expect REJECTION
@@ -259,8 +259,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const params = {
             environmentName: ENVIRONMENT_NAME,
             packageName: "nonexistent_package", // Use a package that doesn't exist
-            modelPath: "flights.malloy",
-            query: "run: flights->{aggregate: c is count()}",
+            modelPath: "storefront.malloy",
+            query: "run: order_items->{aggregate: c is count()}",
          };
 
          // Application Error (Service Layer): Expect RESOLUTION with isError: true
@@ -304,7 +304,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             environmentName: ENVIRONMENT_NAME,
             packageName: PACKAGE_NAME,
             modelPath: "nonexistent_model.malloy", // Use a model that doesn't exist
-            query: "run: flights->{aggregate: c is count()}",
+            query: "run: order_items->{aggregate: c is count()}",
          };
 
          // Application Error (Service Layer): Expect RESOLUTION with isError: true
@@ -364,8 +364,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
                arguments: {
                   environmentName: ENVIRONMENT_NAME,
                   packageName: PACKAGE_NAME,
-                  modelPath: "flights.malloy",
-                  query: "run: flights->{aggregate: c is count()}",
+                  modelPath: "storefront.malloy",
+                  query: "run: order_items->{aggregate: c is count()}",
                },
             }),
          ).rejects.toThrow();
@@ -377,8 +377,8 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const params = {
             environmentName: ENVIRONMENT_NAME,
             packageName: PACKAGE_NAME,
-            modelPath: "flights.malloy",
-            queryName: "top_carriers", // Nested view, but sourceName is missing
+            modelPath: "storefront.malloy",
+            queryName: "top_products", // Nested view, but sourceName is missing
          };
 
          // Expect RESOLUTION with error because it's invalid usage processed by the handler
@@ -405,7 +405,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const errorPayload = JSON.parse(errorJsonText);
          // Expect error about the query/view itself not found
          expect(errorPayload.error).toMatch(
-            /Query 'top_carriers' not found|Reference to undefined object 'top_carriers'/i,
+            /Query 'top_products' not found|Reference to undefined object 'top_products'/i,
          );
          expect(Array.isArray(errorPayload.suggestions)).toBe(true);
       });

package/tests/integration/mcp/mcp_transport.integration.spec.ts

@@ -34,32 +34,20 @@ describe.serial("MCP Transport Tests (E2E Integration)", () => {
 
    describe("Basic Protocol", () => {
       it(
-         "should handle a simple listResources request",
+         "should handle a simple listTools request",
          async () => {
             if (!env) throw new Error("Test environment not initialized");
-            const result = await mcpClient.listResources();
+            const result = await mcpClient.listTools();
             // Assert based on actual successful response structure
-            expect(result).toHaveProperty("resources");
-            expect(Array.isArray(result.resources)).toBe(true);
+            expect(result).toHaveProperty("tools");
+            expect(Array.isArray(result.tools)).toBe(true);
+            expect(
+               result.tools.some((t) => t.name === "malloy_executeQuery"),
+            ).toBe(true);
          },
          { timeout: 30000 },
       );
 
-      it("should receive InvalidParams error when calling a known method with invalid params", async () => {
-         if (!env) throw new Error("Test environment not initialized");
-         expect.assertions(2);
-         try {
-            // Use the client from the test environment
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            await mcpClient.readResource({} as any); // Force invalid params
-         } catch (error) {
-            expect(error).toBeInstanceOf(Error);
-            // Check error code and message
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            expect((error as any).code).toBe(ErrorCode.InternalError);
-         }
-      });
-
       it("should receive MethodNotFound error for unknown methods", async () => {
          if (!env) throw new Error("Test environment not initialized");
          expect.assertions(2); // Expecting error instance and specific code
@@ -84,18 +72,6 @@ describe.serial("MCP Transport Tests (E2E Integration)", () => {
    });
 
    describe("Connection Management & Bridge Logic", () => {
-      // DELETED - Test irrelevant in stateless mode
-      // it("should maintain session across multiple sequential requests", async () => {
-      //    ...
-      // });
-
-      // DELETED - Test irrelevant in stateless mode
-      // it("should handle reconnection after close", async () => {
-      //    ...
-      // });
-
-      // --- Bridge Error Handling ---
-
       it("should return 405 Method Not Allowed for GET requests", async () => {
          if (!env) throw new Error("Test environment not initialized");
          const getUrl = new URL(`${env.serverUrl}/mcp`); // No session ID needed

package/tests/integration/query_givens/query_givens.integration.spec.ts

@@ -0,0 +1,146 @@
+/// <reference types="bun-types" />
+
+/**
+ * HTTP E2E coverage for `given:` runtime parameters on POST .../query:
+ * givens retarget query results, unknown/mistyped givens surface as 400 (not
+ * 500), givens compose with filterParams, a `null` given value is an
+ * explicit SQL-NULL override, and a numeric-string value is accepted for a
+ * `number`-typed given (Malloy's own coercion). Malloy is the single validator:
+ * an unknown name or bad value throws a `runtime-given-*` error that
+ * model.ts maps to a 400 (see getQueryResults).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import path from "path";
+import { fileURLToPath } from "url";
+import { type RestE2EEnv, startRestE2E } from "../../harness/rest_e2e";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENV_NAME = "query-givens-env";
+const PKG = "query-givens";
+const MODEL = "model.malloy";
+
+type Row = Record<string, unknown>;
+
+describe("givens forwarding on /query (HTTP E2E)", () => {
+   let env: (RestE2EEnv & { stop(): Promise<void> }) | null = null;
+   let baseUrl: string;
+
+   beforeAll(async () => {
+      env = await startRestE2E();
+      baseUrl = env.baseUrl;
+      const fixtureDir = path.resolve(__dirname, "../../fixtures/query-givens");
+      const createRes = await fetch(`${baseUrl}/api/v0/environments`, {
+         method: "POST",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({
+            name: ENV_NAME,
+            packages: [{ name: PKG, location: fixtureDir }],
+            connections: [],
+         }),
+      });
+      if (!createRes.ok) {
+         throw new Error(
+            `Failed to create test environment (${createRes.status}): ${await createRes.text()}`,
+         );
+      }
+      const deadline = Date.now() + 30_000;
+      while (Date.now() < deadline) {
+         const res = await fetch(
+            `${baseUrl}/api/v0/environments/${ENV_NAME}/packages/${PKG}`,
+         );
+         if (res.ok) break;
+         await new Promise((r) => setTimeout(r, 250));
+      }
+   });
+
+   afterAll(async () => {
+      await fetch(`${baseUrl}/api/v0/environments/${ENV_NAME}`, {
+         method: "DELETE",
+      }).catch(() => {});
+      await env?.stop();
+   });
+
+   const query = (body: Record<string, unknown>) =>
+      fetch(
+         `${baseUrl}/api/v0/environments/${ENV_NAME}/packages/${PKG}/models/${MODEL}/query`,
+         {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+               sourceName: "orders",
+               queryName: "by_given_region",
+               compactJson: true,
+               ...body,
+            }),
+         },
+      );
+
+   async function rows(res: Response): Promise<Row[]> {
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { result: string };
+      return JSON.parse(body.result) as Row[];
+   }
+
+   it("retargets rows via a given override (EU vs default US)", async () => {
+      const res = await query({ givens: { target_region: "EU" } });
+      const r = await rows(res);
+      expect(r.length).toBe(1);
+      expect(Number(r[0].order_count)).toBe(3);
+   });
+
+   it("returns 400 for an unknown given name, naming it in the message", async () => {
+      // Malloy rejects the unknown name (`runtime-given-unknown`, with a
+      // did-you-mean hint) at prepare time; model.ts maps that to a 400 and
+      // forwards Malloy's message, which names the given.
+      const res = await query({ givens: { NOtaGiven: 1 } });
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { message: string };
+      expect(body.message).toContain("NOtaGiven");
+   });
+
+   it("returns 400 for a value-type mismatch on a number-typed given", async () => {
+      // "min_amount" is declared `:: number`; a non-numeric string can't be
+      // coerced, so Malloy rejects it at prepare time (`runtime-given-*`),
+      // surfaced as a 400 via the run try/catch in model.ts, not a 500.
+      const res = await query({ givens: { min_amount: "not-a-number" } });
+      expect(res.status).toBe(400);
+   });
+
+   it("composes givens with filterParams", async () => {
+      // target_region=EU narrows to ids 4,5,6; filterParams status=active
+      // narrows further to ids 4,6 -> order_count=2.
+      const res = await query({
+         givens: { target_region: "EU" },
+         filterParams: { status: "active" },
+      });
+      const r = await rows(res);
+      expect(r.length).toBe(1);
+      expect(Number(r[0].order_count)).toBe(2);
+   });
+
+   it("omitting givens entirely uses the declared defaults (US baseline)", async () => {
+      const res = await query({});
+      const r = await rows(res);
+      expect(r.length).toBe(1);
+      expect(Number(r[0].order_count)).toBe(3);
+   });
+
+   it("a null given value is an explicit SQL-NULL override", async () => {
+      // `region = NULL` is never true in SQL, so this should return zero
+      // matching rows rather than falling back to the 'US' default.
+      const res = await query({ givens: { target_region: null } });
+      const r = await rows(res);
+      expect(r.length).toBe(1);
+      expect(Number(r[0].order_count)).toBe(0);
+   });
+
+   it("accepts a numeric string for a number-typed given", async () => {
+      // Guards against Malloy's numeric-string coercion for `number` givens
+      // regressing; "5" should be accepted just like the literal 5.
+      const res = await query({ givens: { min_amount: "5" } });
+      const r = await rows(res);
+      expect(r.length).toBe(1);
+      expect(Number(r[0].order_count)).toBe(3);
+   });
+});