@malloy-publisher/server 0.0.231 → 0.0.233

package/tests/integration/first_boot/readiness_line.integration.spec.ts

@@ -0,0 +1,177 @@
+/// <reference types="bun-types" />
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { type ChildProcess, spawn } from "child_process";
+import fs from "fs";
+import net from "net";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * End-to-end coverage for the PUBLISHER_READY line: the contract scripts grep
+ * for instead of polling /api/v0/status. It must appear on stderr exactly
+ * once, only when the server is actually serving, and carry the environment,
+ * package, and load-error counts. That contract spans process boundaries
+ * (a real stderr stream from a real boot), so it needs a dedicated server
+ * subprocess rather than the in-process REST harness.
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// tests/integration/first_boot -> packages/server
+const SERVER_DIR = path.resolve(__dirname, "../../..");
+
+const ENV_NAME = "ready-env";
+const PKG_NAME = "ready-pkg";
+
+/** Allocate an OS-assigned free TCP port (avoids fixed-port collisions). */
+async function getFreePort(): Promise<number> {
+   return new Promise<number>((resolve, reject) => {
+      const srv = net.createServer();
+      srv.on("error", reject);
+      srv.listen(0, "127.0.0.1", () => {
+         const addr = srv.address();
+         const found = typeof addr === "object" && addr ? addr.port : 0;
+         srv.close(() =>
+            found ? resolve(found) : reject(new Error("no free port")),
+         );
+      });
+   });
+}
+
+/** Returns true once `predicate` does, or false if `timeoutMs` elapses first. */
+async function poll(
+   predicate: () => Promise<boolean>,
+   timeoutMs: number,
+   intervalMs = 300,
+): Promise<boolean> {
+   const deadline = Date.now() + timeoutMs;
+   while (Date.now() < deadline) {
+      if (await predicate()) return true;
+      await new Promise((r) => setTimeout(r, intervalMs));
+   }
+   return false;
+}
+
+describe("first-boot readiness line", () => {
+   let proc: ChildProcess | undefined;
+   let exited = false;
+   let stderrLog = "";
+   let combinedLog = "";
+   let srcDir = "";
+   let serverRoot = "";
+   let port = 0;
+
+   const readyLines = () =>
+      stderrLog
+         .split("\n")
+         .filter((line) => line.startsWith("PUBLISHER_READY"));
+
+   beforeAll(async () => {
+      srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "ready-src-"));
+      fs.writeFileSync(
+         path.join(srcDir, "publisher.json"),
+         JSON.stringify({ name: PKG_NAME }),
+      );
+      fs.writeFileSync(
+         path.join(srcDir, "first.malloy"),
+         'source: first_source is duckdb.sql("SELECT 1 as n")\n',
+      );
+
+      serverRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ready-root-"));
+      fs.writeFileSync(
+         path.join(serverRoot, "publisher.config.json"),
+         JSON.stringify({
+            frozenConfig: false,
+            environments: [
+               {
+                  name: ENV_NAME,
+                  packages: [{ name: PKG_NAME, location: srcDir }],
+                  connections: [],
+               },
+            ],
+         }),
+      );
+
+      port = await getFreePort();
+      let mcpPort = await getFreePort();
+      while (mcpPort === port) mcpPort = await getFreePort();
+
+      proc = spawn("bun", ["src/server.ts"], {
+         cwd: SERVER_DIR,
+         env: {
+            ...process.env,
+            SERVER_ROOT: serverRoot,
+            PUBLISHER_HOST: "127.0.0.1",
+            PUBLISHER_PORT: String(port),
+            MCP_PORT: String(mcpPort),
+         },
+         stdio: ["ignore", "pipe", "pipe"],
+      });
+      proc.stdout?.on("data", (d: Buffer) => {
+         combinedLog = (combinedLog + d.toString()).slice(-8000);
+      });
+      proc.stderr?.on("data", (d: Buffer) => {
+         stderrLog += d.toString();
+         combinedLog = (combinedLog + d.toString()).slice(-8000);
+      });
+      proc.on("exit", () => {
+         exited = true;
+      });
+
+      const serving = await poll(async () => {
+         if (exited) throw new Error("server exited before becoming ready");
+         try {
+            const res = await fetch(`http://127.0.0.1:${port}/api/v0/status`);
+            if (!res.ok) return false;
+            const body = (await res.json()) as { operationalState?: string };
+            return body.operationalState === "serving";
+         } catch {
+            return false;
+         }
+      }, 120_000);
+      if (!serving) {
+         throw new Error(
+            `server did not reach serving within 120s\n--- log tail ---\n${combinedLog}`,
+         );
+      }
+      // The line is written in the same tick that flips the status to
+      // serving, but the pipe delivery can trail the HTTP response.
+      await poll(async () => readyLines().length > 0, 10_000, 100);
+   }, 150_000);
+
+   afterAll(async () => {
+      if (proc && !exited) {
+         await new Promise<void>((resolve) => {
+            // Backstop in case SIGTERM is ignored; cleared once the process exits.
+            const backstop = setTimeout(() => proc?.kill("SIGKILL"), 5_000);
+            proc?.on("exit", () => {
+               clearTimeout(backstop);
+               resolve();
+            });
+            proc?.kill("SIGTERM");
+         });
+      }
+      for (const dir of [srcDir, serverRoot]) {
+         try {
+            fs.rmSync(dir, { recursive: true, force: true });
+         } catch {
+            // best-effort cleanup
+         }
+      }
+   });
+
+   it("prints one PUBLISHER_READY line on stderr once serving", () => {
+      const lines = readyLines();
+      expect(lines).toHaveLength(1);
+      // The URL host/port are the ones the server was actually started with,
+      // so a script can dial what the line says.
+      expect(lines[0]).toMatch(
+         new RegExp(
+            `^PUBLISHER_READY url=http://127\\.0\\.0\\.1:${port} ` +
+               `mcp=http://127\\.0\\.0\\.1:\\d+ ` +
+               `environments=1 packages=1 load_errors=0$`,
+         ),
+      );
+   });
+});

package/tests/integration/materialization/manifest_binding.integration.spec.ts

@@ -192,6 +192,37 @@ describe("Manifest binding via Package.manifestLocation (E2E)", () => {
       return file;
    }
 
+   /**
+    * Write a manifest carrying a `storage=` (cross-connection) entry — one that
+    * names a `storageConnectionName` and carries a captured `schema`. Such an
+    * entry serves through the virtual-source transform, so it must bind as a
+    * serve BINDING, never as a same-connection tableName substitution.
+    */
+   async function writeStorageManifest(
+      sourceEntityId: string,
+   ): Promise<string> {
+      const file = path.join(tmpDir, `storage-manifest-${Date.now()}.json`);
+      await fsp.writeFile(
+         file,
+         JSON.stringify({
+            builtAt: new Date().toISOString(),
+            strict: false,
+            entries: {
+               [sourceEntityId]: {
+                  sourceEntityId,
+                  sourceName: "order_summary",
+                  physicalTableName: "order_summary",
+                  connectionName: "duckdb",
+                  storageConnectionName: "lake",
+                  schema: [{ name: "c", type: "BIGINT" }],
+               },
+            },
+         }),
+         "utf8",
+      );
+      return file;
+   }
+
    async function writeManifest(): Promise<string> {
       const file = path.join(tmpDir, `manifest-${Date.now()}.json`);
       await fsp.writeFile(
@@ -303,6 +334,79 @@ describe("Manifest binding via Package.manifestLocation (E2E)", () => {
       { timeout: 120_000 },
    );
 
+   it(
+      "binds a storage= entry as a cross-connection serve binding, not a tableName substitution",
+      async () => {
+         await getPackage(true); // start from live (unbound)
+         const sourceEntityId = await orderSummarySourceEntityId();
+         const manifestFile = await writeStorageManifest(sourceEntityId);
+
+         const patchRes = await patchPackage({
+            manifestLocation: manifestFile,
+         });
+         expect(patchRes.status).toBe(200);
+         const patched = (await patchRes.json()) as Record<string, unknown>;
+
+         // The storage entry never enters the same-connection tableName manifest,
+         // so there is nothing to substitute (and no recompile happened).
+         expect(patched.manifestEntryCount).toBe(0);
+         // It surfaces instead as a cross-connection storage serve binding.
+         expect(patched.storageServeBindings).toEqual([
+            {
+               sourceName: "order_summary",
+               storageConnectionName: "lake",
+               tablePath: "lake.order_summary",
+            },
+         ]);
+         // The bound URI is recorded even though no tableName manifest bound.
+         expect(patched.boundManifestUri).toBe(manifestFile);
+
+         // Clearing reverts: the storage serve binding is dropped.
+         const clearRes = await patchPackage({ manifestLocation: null });
+         expect(clearRes.status).toBe(200);
+         const cleared = (await clearRes.json()) as Record<string, unknown>;
+         expect(cleared.storageServeBindings ?? null).toBeNull();
+         await getPackage(true);
+      },
+      { timeout: 60_000 },
+   );
+
+   it(
+      "a rebind to a manifest whose storage entries vanished clears the old bindings",
+      async () => {
+         // Regression (MED-2): bindManifest must drop storage serve bindings when
+         // a NEW manifest (still a real URI, not a clear) no longer carries them —
+         // otherwise stale bindings keep routing at a table the host no longer
+         // vouches for.
+         await getPackage(true);
+         const sourceEntityId = await orderSummarySourceEntityId();
+         const withStorage = await writeStorageManifest(sourceEntityId);
+         const bound = (await (
+            await patchPackage({ manifestLocation: withStorage })
+         ).json()) as Record<string, unknown>;
+         expect(
+            (bound.storageServeBindings as unknown[] | undefined)?.length,
+         ).toBe(1);
+
+         // Rebind to a DIFFERENT manifest URI that carries no storage entries.
+         const noStorage = path.join(tmpDir, `no-storage-${Date.now()}.json`);
+         await fsp.writeFile(
+            noStorage,
+            JSON.stringify({ builtAt: new Date().toISOString(), entries: {} }),
+            "utf8",
+         );
+         const rebound = (await (
+            await patchPackage({ manifestLocation: noStorage })
+         ).json()) as Record<string, unknown>;
+         // Stale storage binding must be gone, not left routing.
+         expect(rebound.storageServeBindings ?? null).toBeNull();
+
+         await patchPackage({ manifestLocation: null });
+         await getPackage(true);
+      },
+      { timeout: 60_000 },
+   );
+
    it("degrades to serving live when the manifest is unreachable", async () => {
       const missing = path.join(tmpDir, "does-not-exist.json");
 

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

@@ -71,7 +71,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             for (const block of content) {
                expect(block.type).toBe("resource");
                expect(block.resource).toBeDefined();
-               expect(block.resource.type).toBe("application/json");
+               expect(block.resource.mimeType).toBe("application/json");
                expect(block.resource.text).toBeDefined();
                expect(typeof block.resource.text).toBe("string");
             }
@@ -80,12 +80,24 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
 
             const queryResultBlock = content[0].resource;
             expect(queryResultBlock.uri).toContain("#result");
-            const queryResultData = JSON.parse(queryResultBlock.text);
-            expect(queryResultData).toBeDefined();
-            // Check properties directly on the parsed Result object
-            expect(queryResultData.data).toBeDefined();
-            expect(Array.isArray(queryResultData.data.array_value)).toBe(true);
-            // Could add more specific checks on data if needed
+            const envelope = JSON.parse(queryResultBlock.text);
+
+            // Flat rows keyed by column name: the same shape an in-package data
+            // app receives, not the type-tagged Malloy cell envelope.
+            expect(Array.isArray(envelope.rows)).toBe(true);
+            expect(envelope.rows.length).toBeGreaterThan(0);
+            expect(typeof envelope.rows[0]).toBe("object");
+            expect(envelope.rows[0].data).toBeUndefined();
+
+            // Credible's field names, so an agent sees one shape whether the
+            // app is authored locally against Publisher or served in production.
+            expect(typeof envelope._query_row_limit).toBe("number");
+            expect(typeof envelope._limit_hit).toBe("boolean");
+            // Absent rather than false when nothing was dropped.
+            expect("_rows_truncated" in envelope).toBe(false);
+            // The metadata flat rows drop.
+            expect(envelope._meta.schema).toBeDefined();
+            expect(typeof envelope._meta.connection_name).toBe("string");
          },
          { timeout: 30000 },
       );
@@ -120,7 +132,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             const queryResultBlock = result.content![0];
             expect(queryResultBlock.type).toBe("resource");
             expect(queryResultBlock.resource).toBeDefined();
-            expect(queryResultBlock.resource.type).toBe("application/json");
+            expect(queryResultBlock.resource.mimeType).toBe("application/json");
             expect(queryResultBlock.resource.uri).toMatch(/result/); // Check URI contains queryResult
             expect(queryResultBlock.resource.text).toBeDefined();
 
@@ -159,7 +171,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
             const errorBlockSyntax = result.content![0];
             expect(errorBlockSyntax.type).toBe("resource");
             expect(errorBlockSyntax.resource).toBeDefined();
-            expect(errorBlockSyntax.resource.type).toBe("application/json");
+            expect(errorBlockSyntax.resource.mimeType).toBe("application/json");
 
             // Check for Malloy compilation error message from getMalloyErrorDetails
             const errorJsonTextSyntax = errorBlockSyntax.resource
@@ -169,6 +181,17 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
                /syntax error|no viable alternative/i,
             );
             expect(Array.isArray(errorPayloadSyntax.suggestions)).toBe(true);
+
+            // The resource block is invisible to a client that renders only
+            // text on an isError result, which is how a real diagnostic gets
+            // reported as a bare "Unknown error". Pinned here, over the real
+            // HTTP transport, because the unit spec calls the handler directly
+            // and so cannot catch the block being dropped in serialization.
+            const textBlockSyntax = result.content!.find(
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               (b: any) => b.type === "text",
+            );
+            expect(textBlockSyntax?.text).toContain(errorPayloadSyntax.error);
          },
          { timeout: 30000 },
       );
@@ -277,7 +300,9 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const errorBlockPkgNotFound = result.content![0];
          expect(errorBlockPkgNotFound.type).toBe("resource");
          expect(errorBlockPkgNotFound.resource).toBeDefined();
-         expect(errorBlockPkgNotFound.resource.type).toBe("application/json");
+         expect(errorBlockPkgNotFound.resource.mimeType).toBe(
+            "application/json",
+         );
 
          // Parse the JSON string from the resource text content
          const errorJsonTextPkgNotFound = errorBlockPkgNotFound.resource
@@ -321,7 +346,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const errorBlockModel = result.content![0];
          expect(errorBlockModel.type).toBe("resource");
          expect(errorBlockModel.resource).toBeDefined();
-         expect(errorBlockModel.resource.type).toBe("application/json");
+         expect(errorBlockModel.resource.mimeType).toBe("application/json");
 
          // Parse the JSON string from the resource text content
          const errorJsonTextModel = errorBlockModel.resource.text as string;
@@ -398,7 +423,7 @@ describe.serial("MCP Tool Handlers (E2E Integration)", () => {
          const errorBlock = result.content![0];
          expect(errorBlock.type).toBe("resource");
          expect(errorBlock.resource).toBeDefined();
-         expect(errorBlock.resource.type).toBe("application/json");
+         expect(errorBlock.resource.mimeType).toBe("application/json");
 
          // Check for Malloy error indicating the query/view wasn't found at the top level
          const errorJsonText = errorBlock.resource.text as string;

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

@@ -0,0 +1,235 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+   Notification,
+   Request,
+   Result,
+} from "@modelcontextprotocol/sdk/types.js";
+import http from "http";
+import { AddressInfo } from "net";
+import {
+   McpE2ETestEnvironment,
+   cleanupE2ETestEnvironment,
+   setupE2ETestEnvironment,
+} from "../../harness/mcp_test_setup";
+
+/**
+ * End-to-end coverage of semantic malloy_getContext retrieval: the real
+ * server, the real DuckDB vector cache, and a deterministic in-test
+ * embedding endpoint (letter-bigram bag-of-words vectors, so related
+ * phrases genuinely land near each other, no network, no key).
+ */
+
+const ENVIRONMENT_NAME = "examples";
+const PACKAGE_NAME = "storefront";
+const DIMS = 64;
+
+/** Deterministic unit vector from letter bigrams. */
+function bigramVector(text: string): number[] {
+   const v = new Array<number>(DIMS).fill(0);
+   const s = ` ${text.toLowerCase().replace(/[^a-z0-9]+/g, " ")} `;
+   for (let i = 0; i < s.length - 1; i++) {
+      v[(s.charCodeAt(i) * 31 + s.charCodeAt(i + 1)) % DIMS] += 1;
+   }
+   const norm = Math.sqrt(v.reduce((acc, x) => acc + x * x, 0)) || 1;
+   return v.map((x) => x / norm);
+}
+
+let env: McpE2ETestEnvironment | null = null;
+let mcpClient: Client<Request, Notification, Result>;
+let embeddingStub: http.Server;
+let stubFailing = false;
+let stubRequests = 0;
+
+const savedEnv: Record<string, string | undefined> = {};
+const ENV_KEYS = [
+   "EMBEDDING_API_KEY",
+   "EMBEDDING_API_BASE",
+   "EMBEDDING_MODEL",
+   "EMBEDDING_DIMENSIONS",
+];
+
+interface GetContextPayload {
+   retrieval?: string;
+   results?: Array<{
+      kind: string;
+      name: string;
+      source?: string;
+      score?: number;
+   }>;
+   error?: string;
+}
+
+async function callGetContext(
+   args: Record<string, unknown>,
+): Promise<GetContextPayload> {
+   const result = (await mcpClient.callTool({
+      name: "malloy_getContext",
+      arguments: args,
+   })) as {
+      content: Array<{ type: string; resource?: { text?: string } }>;
+   };
+   const text = result.content?.[0]?.resource?.text;
+   if (!text) throw new Error("malloy_getContext returned no resource text");
+   return JSON.parse(text) as GetContextPayload;
+}
+
+describe.serial("MCP getContext semantic retrieval (E2E Integration)", () => {
+   beforeAll(async () => {
+      // A local OpenAI-compatible /embeddings endpoint with deterministic
+      // vectors. Bound to 127.0.0.1:0; the real port comes from the OS.
+      embeddingStub = http.createServer((req, res) => {
+         let body = "";
+         req.on("data", (chunk) => (body += chunk));
+         req.on("end", () => {
+            stubRequests++;
+            if (stubFailing) {
+               res.writeHead(500).end("stub down");
+               return;
+            }
+            const { input } = JSON.parse(body) as { input: string[] };
+            res.writeHead(200, { "Content-Type": "application/json" }).end(
+               JSON.stringify({
+                  data: input.map((text, index) => ({
+                     index,
+                     embedding: bigramVector(text),
+                  })),
+               }),
+            );
+         });
+      });
+      await new Promise<void>((resolve) =>
+         embeddingStub.listen(0, "127.0.0.1", resolve),
+      );
+      const port = (embeddingStub.address() as AddressInfo).port;
+
+      // Set the embedding env vars BEFORE the server harness dynamically
+      // imports src/server; config is read per call, but this keeps the
+      // whole server lifetime consistently configured.
+      for (const key of ENV_KEYS) {
+         savedEnv[key] = process.env[key];
+      }
+      process.env.EMBEDDING_API_KEY = "integration-test-key";
+      process.env.EMBEDDING_API_BASE = `http://127.0.0.1:${port}/v1`;
+      // A stub-distinct model name: the suite shares publisher.db with
+      // local manual runs, and rows cached under the real default model
+      // name would poison a later real-provider run (the stub's bigram
+      // vectors are not text-embedding-3-small's). Under this name the
+      // leftovers are inert; a real run's model diff replaces them.
+      process.env.EMBEDDING_MODEL = "integration-test-bigram-stub";
+      delete process.env.EMBEDDING_DIMENSIONS;
+
+      env = await setupE2ETestEnvironment();
+      mcpClient = env.mcpClient;
+   }, 200000);
+
+   afterAll(async () => {
+      await cleanupE2ETestEnvironment(env);
+      env = null;
+      // Restore the embedding env so later suites in this process run
+      // unconfigured (the provider getter re-reads env per call).
+      for (const key of ENV_KEYS) {
+         if (savedEnv[key] === undefined) delete process.env[key];
+         else process.env[key] = savedEnv[key];
+      }
+      await new Promise<void>((resolve, reject) =>
+         embeddingStub.close((err) => (err ? reject(err) : resolve())),
+      );
+   });
+
+   it(
+      "answers lexically while indexing, then flips to semantic with scores",
+      async () => {
+         const first = await callGetContext({
+            environmentName: ENVIRONMENT_NAME,
+            packageName: PACKAGE_NAME,
+            query: "total sales revenue",
+         });
+         // Configured server: the marker is always present on tier 4.
+         expect(["lexical", "semantic"]).toContain(first.retrieval);
+
+         let payload = first;
+         for (let i = 0; i < 60 && payload.retrieval !== "semantic"; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            payload = await callGetContext({
+               environmentName: ENVIRONMENT_NAME,
+               packageName: PACKAGE_NAME,
+               query: "total sales revenue",
+            });
+         }
+         expect(payload.retrieval).toBe("semantic");
+         expect(stubRequests).toBeGreaterThan(0);
+
+         const results = payload.results ?? [];
+         expect(results.length).toBeGreaterThan(0);
+         for (const r of results) {
+            expect(typeof r.score).toBe("number");
+         }
+         // The bigram embedding puts "total sales revenue" on top of the
+         // total_sales measure ("total sales" once humanized).
+         expect(results.some((r) => r.name === "total_sales")).toBe(true);
+      },
+      { timeout: 60000 },
+   );
+
+   it(
+      "keeps the semantic index warm across calls (no re-embed per call)",
+      async () => {
+         const before = stubRequests;
+         const payload = await callGetContext({
+            environmentName: ENVIRONMENT_NAME,
+            packageName: PACKAGE_NAME,
+            query: "orders by month",
+         });
+         expect(payload.retrieval).toBe("semantic");
+         // Exactly one stub call: the query embedding. No bulk re-sync.
+         expect(stubRequests).toBe(before + 1);
+      },
+      { timeout: 30000 },
+   );
+
+   it(
+      "narrows semantic retrieval with sourceName",
+      async () => {
+         const payload = await callGetContext({
+            environmentName: ENVIRONMENT_NAME,
+            packageName: PACKAGE_NAME,
+            query: "total sales revenue",
+            sourceName: "order_items",
+         });
+         expect(payload.retrieval).toBe("semantic");
+         const results = payload.results ?? [];
+         // Non-empty, or the per-result loop below pins nothing.
+         expect(results.length).toBeGreaterThan(0);
+         for (const r of results) {
+            expect(r.source).toBe("order_items");
+         }
+      },
+      { timeout: 30000 },
+   );
+
+   // Keep this test LAST: the induced failure starts the provider
+   // cool-down, which short-circuits the semantic path for its window.
+   it(
+      "falls back to lexical, marked, when the embedding endpoint fails",
+      async () => {
+         stubFailing = true;
+         try {
+            const payload = await callGetContext({
+               environmentName: ENVIRONMENT_NAME,
+               packageName: PACKAGE_NAME,
+               query: "top selling products",
+            });
+            expect(payload.retrieval).toBe("lexical");
+            const results = payload.results ?? [];
+            expect(results.length).toBeGreaterThan(0);
+            for (const r of results) {
+               expect(r.score).toBeUndefined();
+            }
+         } finally {
+            stubFailing = false;
+         }
+      },
+      { timeout: 30000 },
+   );
+});