@malloy-publisher/server 0.0.200 → 0.0.202

package/dist/server.mjs

@@ -221210,7 +221210,9 @@ async function isDatabaseAttached(connection, dbName) {
   try {
     const existingDatabases = await connection.runSQL("SHOW DATABASES");
     const rows = Array.isArray(existingDatabases) ? existingDatabases : existingDatabases.rows || [];
-    logger.debug(`Existing databases:`, rows);
+    logger.debug("connection.duckdb.databases.queried", {
+      count: rows.length
+    });
     return rows.some((row) => Object.values(row).some((value) => typeof value === "string" && value === dbName));
   } catch (error) {
     logger.warn(`Failed to check existing databases:`, error);
@@ -231186,6 +231188,13 @@ class Model {
     this.filterMap = filterMap ?? new Map;
     this.givens = givens;
     this.modelInfo = modelInfo ?? (this.modelDef ? modelDefToModelInfo(this.modelDef) : undefined);
+    if (this.filterMap.size > 0) {
+      logger.warn(`Model "${packageName}/${modelPath}" uses deprecated #(filter) annotations. Migrate to given: — see https://github.com/malloydata/publisher/blob/main/docs/givens.md`, {
+        packageName,
+        modelPath,
+        filterSourceCount: this.filterMap.size
+      });
+    }
   }
   getFilters(sourceName) {
     return this.filterMap.get(sourceName) ?? [];
@@ -231454,7 +231463,6 @@ run: ${sourceName ? sourceName + "->" : ""}${queryName}`;
   }
   async getNotebookModel() {
     const notebookCells = this.runnableNotebookCells.map((cell) => {
-      logger.debug("cell.queryInfo", cell.queryInfo);
       return {
         type: cell.type,
         text: cell.text,
@@ -231555,7 +231563,6 @@ run: ${sourceName ? sourceName + "->" : ""}${queryName}`;
         } else {
           logger.error("Error message: ", errorMessage);
         }
-        logger.debug("Cell content: ", cellIndex, cell.type, cell.text);
         throw new BadRequestError(`Cell execution failed: ${errorMessage}`);
       }
     }
@@ -232244,7 +232251,10 @@ class Environment {
     logger.info(`Creating environment with connection configuration`);
     const malloyConfig = buildEnvironmentMalloyConfig(connections, environmentPath);
     logger.info(`Loaded ${malloyConfig.apiConnections.length} connections for environment ${environmentName}`, {
-      apiConnections: malloyConfig.apiConnections
+      connections: malloyConfig.apiConnections.map((c) => ({
+        name: c.name,
+        type: c.type
+      }))
     });
     const environment = new Environment(environmentName, environmentPath, malloyConfig, malloyConfig.apiConnections);
     await Environment.sweepStaleInstallDirs(environmentPath);
@@ -232481,8 +232491,7 @@ ${source}` : source;
     }
     this.assertCanAdmitNewPackage(packageName, "add a new package", options.allowAdmission === true);
     logger.info(`Adding package ${packageName} to environment ${this.environmentName}`, {
-      packagePath,
-      malloyConfig: this.malloyConfig.malloyConfig
+      packagePath
     });
     return this.withPackageLock(packageName, () => this._addPackageLocked(packageName));
   }
@@ -232507,13 +232516,28 @@ ${source}` : source;
     assertSafePackageName(packageName);
     const stagingPath = this.allocateStagingPath(packageName);
     await fs6.promises.mkdir(path8.dirname(stagingPath), { recursive: true });
+    logger.debug("install.phase1.download.started", {
+      environmentName: this.environmentName,
+      packageName,
+      stagingPath
+    });
+    const downloadStartedAt = performance.now();
     try {
       await downloader(stagingPath);
     } catch (err) {
       await fs6.promises.rm(stagingPath, { recursive: true, force: true }).catch(() => {});
       throw err;
     }
+    logger.debug("install.phase1.download.completed", {
+      environmentName: this.environmentName,
+      packageName,
+      durationMs: performance.now() - downloadStartedAt
+    });
     return this.withPackageLock(packageName, async () => {
+      logger.debug("install.phase2.swap.started", {
+        environmentName: this.environmentName,
+        packageName
+      });
       const canonicalPath = safeJoinUnderRoot(this.environmentPath, packageName);
       let retiredPath;
       const oldPackage = this.packages.get(packageName);
@@ -232524,17 +232548,29 @@ ${source}` : source;
           recursive: true
         });
         await fs6.promises.rename(canonicalPath, retiredPath);
+        logger.debug("install.phase2.retired_old", {
+          environmentName: this.environmentName,
+          packageName,
+          retiredPath
+        });
       }
       let newPackage;
       try {
         await fs6.promises.rename(stagingPath, canonicalPath);
         this.setPackageStatus(packageName, "loading" /* LOADING */);
         newPackage = await Package.create(this.environmentName, packageName, canonicalPath, () => this.malloyConfig.malloyConfig);
+        logger.debug("install.phase2.committed", {
+          environmentName: this.environmentName,
+          packageName,
+          canonicalPath
+        });
       } catch (err) {
         await fs6.promises.rm(canonicalPath, { recursive: true, force: true }).catch(() => {});
+        let restored = false;
         if (retiredPath) {
           try {
             await fs6.promises.rename(retiredPath, canonicalPath);
+            restored = true;
           } catch (restoreErr) {
             logger.error("Failed to restore retired package after install rollback", {
               error: restoreErr,
@@ -232545,6 +232581,12 @@ ${source}` : source;
         }
         await fs6.promises.rm(stagingPath, { recursive: true, force: true }).catch(() => {});
         this.deletePackageStatus(packageName);
+        logger.debug("install.phase2.rollback", {
+          environmentName: this.environmentName,
+          packageName,
+          restored,
+          errorName: err instanceof Error ? err.name : "Unknown"
+        });
         throw err;
       }
       this.packages.set(packageName, newPackage);
@@ -232555,6 +232597,11 @@ ${source}` : source;
       if (retiredPath) {
         const pathToClean = retiredPath;
         setImmediate(() => {
+          logger.debug("install.phase3.retired_cleanup", {
+            environmentName: this.environmentName,
+            packageName,
+            retiredPath: pathToClean
+          });
           fs6.promises.rm(pathToClean, { recursive: true, force: true }).catch((err) => {
             logger.warn(`Failed to clean up retired package directory ${pathToClean}`, { error: err });
           });
@@ -233815,6 +233862,15 @@ class WatchModeController {
 init_errors();
 init_logger();
 
+// src/filter_deprecation.ts
+var setFilterDeprecationHeaders = (res, options) => {
+  const hasFilterParams = options.filterParams !== undefined && options.filterParams !== null && !(typeof options.filterParams === "object" && !Array.isArray(options.filterParams) && Object.keys(options.filterParams).length === 0);
+  if (hasFilterParams || options.bypassFilters !== undefined) {
+    res.setHeader("Deprecation", "true");
+    res.setHeader("Link", '<https://github.com/malloydata/publisher/blob/main/docs/givens.md>; rel="deprecation"; type="text/markdown"');
+  }
+};
+
 // src/heap_check.ts
 init_logger();
 var import_api7 = __toESM(require_src(), 1);
@@ -239891,7 +239947,12 @@ app.get(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/note
         return;
       }
     }
-    res.status(200).json(await modelController.executeNotebookCell(req.params.environmentName, req.params.packageName, notebookPath, cellIndex, filterParams, bypassFilters, givens));
+    const result = await modelController.executeNotebookCell(req.params.environmentName, req.params.packageName, notebookPath, cellIndex, filterParams, bypassFilters, givens);
+    setFilterDeprecationHeaders(res, {
+      filterParams,
+      bypassFilters
+    });
+    res.status(200).json(result);
   } catch (error) {
     logger.error(error);
     const { json, status } = internalErrorToHttpError(error);
@@ -239919,7 +239980,12 @@ app.post(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/mod
   }
   try {
     const modelPath = req.params["0"];
-    res.status(200).json(await queryController.getQuery(req.params.environmentName, req.params.packageName, modelPath, req.body.sourceName, req.body.queryName, req.body.query, req.body.compactJson === true, req.body.filterParams ?? req.body.sourceFilters, req.body.bypassFilters === true ? true : undefined, req.body.givens));
+    const result = await queryController.getQuery(req.params.environmentName, req.params.packageName, modelPath, req.body.sourceName, req.body.queryName, req.body.query, req.body.compactJson === true, req.body.filterParams ?? req.body.sourceFilters, req.body.bypassFilters === true ? true : undefined, req.body.givens);
+    setFilterDeprecationHeaders(res, {
+      filterParams: req.body.filterParams ?? req.body.sourceFilters,
+      bypassFilters: req.body.bypassFilters === true ? true : undefined
+    });
+    res.status(200).json(result);
   } catch (error) {
     logger.error(error);
     const { json, status } = internalErrorToHttpError(error);

package/package.json

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

package/publisher.config.json

@@ -15,6 +15,10 @@
         {
           "name": "faa",
           "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+        },
+        {
+          "name": "faa-givens-demo",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa-givens-demo"
         }
       ],
       "connections": []

package/src/filter_deprecation.spec.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "bun:test";
+import { setFilterDeprecationHeaders } from "./filter_deprecation";
+
+const makeRes = () => {
+   const headers: Record<string, string> = {};
+   const res = {
+      headers,
+      setHeader(name: string, value: string) {
+         headers[name] = value;
+         return res;
+      },
+   };
+   return res;
+};
+
+const DEPRECATION_LINK =
+   '<https://github.com/malloydata/publisher/blob/main/docs/givens.md>; rel="deprecation"; type="text/markdown"';
+
+describe("setFilterDeprecationHeaders", () => {
+   it("does not set headers when neither filterParams nor bypassFilters is supplied", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, {});
+      expect(res.headers.Deprecation).toBeUndefined();
+      expect(res.headers.Link).toBeUndefined();
+   });
+
+   it("does not set headers for an explicit empty filterParams object (no-op opt-out)", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, { filterParams: {} });
+      expect(res.headers.Deprecation).toBeUndefined();
+      expect(res.headers.Link).toBeUndefined();
+   });
+
+   it("sets RFC 8594 headers when filterParams carries values", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, {
+         filterParams: { region: ["US"] },
+      });
+      expect(res.headers.Deprecation).toBe("true");
+      expect(res.headers.Link).toBe(DEPRECATION_LINK);
+   });
+
+   it("sets RFC 8594 headers when bypassFilters is true", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, { bypassFilters: true });
+      expect(res.headers.Deprecation).toBe("true");
+      expect(res.headers.Link).toBe(DEPRECATION_LINK);
+   });
+
+   it("does not set headers when bypassFilters is undefined and filterParams is undefined", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, {
+         filterParams: undefined,
+         bypassFilters: undefined,
+      });
+      expect(res.headers.Deprecation).toBeUndefined();
+   });
+
+   it("does not set headers when filterParams is null", () => {
+      const res = makeRes();
+      setFilterDeprecationHeaders(res, { filterParams: null });
+      expect(res.headers.Deprecation).toBeUndefined();
+   });
+});

package/src/filter_deprecation.ts

@@ -0,0 +1,42 @@
+/**
+ * Minimal structural type the helper needs from an HTTP response. Kept
+ * narrower than `express.Response` so tests can pass a tiny stub instead
+ * of constructing a full Express response.
+ */
+export interface HeaderSetter {
+   setHeader(name: string, value: string): unknown;
+}
+
+/**
+ * Attach RFC 8594 deprecation headers when the request carries any of the
+ * legacy `#(filter)` API surface (`filterParams` / `bypassFilters` on POST,
+ * `filter_params` / `bypass_filters` on the notebook-cell GET). The
+ * complementary operator-facing notice for legacy *models* (independent of
+ * whether the caller used the deprecated request fields) ships as a
+ * one-time warn log in `Model`'s constructor — see service/model.ts.
+ *
+ * `filterParams` here is the *parsed* value (after JSON.parse for the GET
+ * notebook-cell path), so an empty `{}` is treated as a no-op opt-out — the
+ * header only fires when the caller actually supplied filter values.
+ */
+export const setFilterDeprecationHeaders = (
+   res: HeaderSetter,
+   options: { filterParams?: unknown; bypassFilters?: unknown },
+): void => {
+   const hasFilterParams =
+      options.filterParams !== undefined &&
+      options.filterParams !== null &&
+      !(
+         typeof options.filterParams === "object" &&
+         !Array.isArray(options.filterParams) &&
+         Object.keys(options.filterParams as Record<string, unknown>).length ===
+            0
+      );
+   if (hasFilterParams || options.bypassFilters !== undefined) {
+      res.setHeader("Deprecation", "true");
+      res.setHeader(
+         "Link",
+         '<https://github.com/malloydata/publisher/blob/main/docs/givens.md>; rel="deprecation"; type="text/markdown"',
+      );
+   }
+};

package/src/server.ts

@@ -35,6 +35,7 @@ import {
 import { logger, loggerMiddleware } from "./logger";
 
 import { getMemoryGovernorConfig } from "./config";
+import { setFilterDeprecationHeaders } from "./filter_deprecation";
 import { checkHeapConfiguration } from "./heap_check";
 import { queryConcurrency } from "./query_concurrency";
 import { ManifestController } from "./controller/manifest.controller";
@@ -1098,17 +1099,20 @@ app.get(
             }
          }
 
-         res.status(200).json(
-            await modelController.executeNotebookCell(
-               req.params.environmentName,
-               req.params.packageName,
-               notebookPath,
-               cellIndex,
-               filterParams,
-               bypassFilters,
-               givens,
-            ),
+         const result = await modelController.executeNotebookCell(
+            req.params.environmentName,
+            req.params.packageName,
+            notebookPath,
+            cellIndex,
+            filterParams,
+            bypassFilters,
+            givens,
          );
+         setFilterDeprecationHeaders(res, {
+            filterParams,
+            bypassFilters,
+         });
+         res.status(200).json(result);
       } catch (error) {
          logger.error(error);
          const { json, status } = internalErrorToHttpError(error as Error);
@@ -1155,22 +1159,25 @@ app.post(
       try {
          // Express stores wildcard matches in params['0']
          const modelPath = (req.params as Record<string, string>)["0"];
-         res.status(200).json(
-            await queryController.getQuery(
-               req.params.environmentName,
-               req.params.packageName,
-               modelPath,
-               req.body.sourceName as string,
-               req.body.queryName as string,
-               req.body.query as string,
-               req.body.compactJson === true,
-               (req.body.filterParams ?? req.body.sourceFilters) as
-                  | Record<string, string | string[]>
-                  | undefined,
-               req.body.bypassFilters === true ? true : undefined,
-               req.body.givens as Record<string, GivenValue> | undefined,
-            ),
+         const result = await queryController.getQuery(
+            req.params.environmentName,
+            req.params.packageName,
+            modelPath,
+            req.body.sourceName as string,
+            req.body.queryName as string,
+            req.body.query as string,
+            req.body.compactJson === true,
+            (req.body.filterParams ?? req.body.sourceFilters) as
+               | Record<string, string | string[]>
+               | undefined,
+            req.body.bypassFilters === true ? true : undefined,
+            req.body.givens as Record<string, GivenValue> | undefined,
          );
+         setFilterDeprecationHeaders(res, {
+            filterParams: req.body.filterParams ?? req.body.sourceFilters,
+            bypassFilters: req.body.bypassFilters === true ? true : undefined,
+         });
+         res.status(200).json(result);
       } catch (error) {
          logger.error(error);
          const { json, status } = internalErrorToHttpError(error as Error);

package/src/service/connection.spec.ts

@@ -9,6 +9,7 @@ import {
    testConnectionConfig,
 } from "./connection";
 import { assembleEnvironmentConnections } from "./connection_config";
+import { EnvironmentStore } from "./environment_store";
 
 type ApiConnection = components["schemas"]["Connection"];
 type AttachedDatabase = components["schemas"]["AttachedDatabase"];
@@ -45,6 +46,21 @@ const hasGCSCredentials = () =>
 const readBigQueryServiceAccountJson = async (): Promise<string> =>
    fs.readFile(process.env.GOOGLE_APPLICATION_CREDENTIALS!, "utf-8");
 
+// `BIGQUERY_PUBLIC_DATA_*` env vars are populated by the
+// `Setup BigQuery public-data credentials` step in
+// `.github/workflows/connection-integration-tests.yml`. Kept separate
+// from the existing `BIGQUERY_TEST_*` vars (which point at the
+// org-scoped BQ_PRESTO_TRINO_KEY service account) so the two SAs can
+// coexist without one overwriting the other.
+const hasPublicDataBigQueryCredentials = () =>
+   !!(
+      process.env.BIGQUERY_PUBLIC_DATA_CREDENTIALS &&
+      process.env.BIGQUERY_PUBLIC_DATA_PROJECT_ID
+   );
+
+const readPublicDataBigQueryServiceAccountJson = async (): Promise<string> =>
+   fs.readFile(process.env.BIGQUERY_PUBLIC_DATA_CREDENTIALS!, "utf-8");
+
 describe("connection integration tests", () => {
    const testEnvironmentPath = path.join(
       process.cwd(),
@@ -672,6 +688,234 @@ describe("connection integration tests", () => {
          );
       });
 
+      describe("BigQuery direct connection (public-data)", () => {
+         // Single end-to-end check that a real `bigquery`-typed
+         // connection authenticated by the BIGQUERY_PUBLIC_DATA_SA
+         // service account can actually round-trip a query against
+         // bigquery-public-data. Skips locally if the creds aren't
+         // set; runs in CI under .github/workflows/connection-integration-tests.yml.
+         //
+         // Picked `samples.shakespeare` because (a) it's tiny (~6 MB
+         // / ~165k rows) so the BigQuery byte-scanned cost is well
+         // under the 1 TB/month free tier even across many PR runs,
+         // (b) it's a long-stable public table so the assertion stays
+         // valid across years of reruns. If this assertion ever fails
+         // the cause is almost certainly auth, not data drift.
+         it(
+            "should query bigquery-public-data via real BigQuery connection",
+            async () => {
+               if (!hasPublicDataBigQueryCredentials()) {
+                  console.log(
+                     "Skipping: BIGQUERY_PUBLIC_DATA_CREDENTIALS or BIGQUERY_PUBLIC_DATA_PROJECT_ID not configured",
+                  );
+                  return;
+               }
+
+               const serviceAccountJson =
+                  await readPublicDataBigQueryServiceAccountJson();
+
+               const bqConnection: ApiConnection = {
+                  name: "bq_public_data",
+                  type: "bigquery",
+                  bigqueryConnection: {
+                     // Billing/auth project (the SA's own project_id);
+                     // the queried tables live in bigquery-public-data
+                     // and are referenced explicitly in the SQL below.
+                     defaultProjectId:
+                        process.env.BIGQUERY_PUBLIC_DATA_PROJECT_ID!,
+                     serviceAccountKeyJson: serviceAccountJson,
+                  },
+               };
+
+               const { malloyConnections } = await createEnvironmentConnections(
+                  [bqConnection],
+                  testEnvironmentPath,
+               );
+
+               const connection = malloyConnections.get("bq_public_data");
+               expect(connection).toBeDefined();
+
+               try {
+                  const result = await connection!.runSQL(
+                     "SELECT COUNT(*) AS row_count FROM `bigquery-public-data.samples.shakespeare`",
+                  );
+                  expect(result.rows.length).toBe(1);
+                  // Shakespeare has ~165k rows; bound on both sides so
+                  // we catch both "auth succeeded but query returned
+                  // nothing" and "got a confusingly large value" failure
+                  // modes, while staying tolerant of any minor row-count
+                  // jitter Google might introduce.
+                  const row = result.rows[0] as Record<string, unknown>;
+                  const rowCount = Number(row.row_count);
+                  expect(rowCount).toBeGreaterThan(100_000);
+                  expect(rowCount).toBeLessThan(200_000);
+               } finally {
+                  // BigQuery driver holds an HTTP/2 client + auth refresh
+                  // state; close it explicitly so we don't leak across
+                  // the rest of the test run. (createdConnections is
+                  // typed for DuckDBConnection, so we can't use the
+                  // shared cleanup array here.)
+                  await connection?.close();
+               }
+            },
+            { timeout: 60000 },
+         );
+      });
+
+      describe("BigQuery package end-to-end (bq-hackernews)", () => {
+         // Step 2 of Sagar's bun-setup-fixes ask: not just "does the
+         // BigQuery driver round-trip a SQL query" (the previous
+         // describe block covers that), but "does the publisher's
+         // package-loading path successfully use the BigQuery
+         // connection on behalf of a Malloy package."
+         //
+         // Mechanism: stand up a real EnvironmentStore against a
+         // temp publisher.config.json that declares both the BQ
+         // connection (with the BIGQUERY_PUBLIC_DATA_SA injected via
+         // serviceAccountKeyJson) AND the bq-hackernews package
+         // (loaded from credibledata/malloy-samples on GitHub).
+         // EnvironmentStore.initialize then: clones the malloy-samples
+         // repo, extracts the bigquery-hackernews subdirectory, parses
+         // the package's Malloy models, and — crucially — introspects
+         // their BigQuery table schemas during model compilation. A
+         // successful Package.listModels() call therefore proves the
+         // entire package-uses-connection path, not just the bare
+         // driver auth.
+         //
+         // Cost: ~50 MB git clone (one time per test run since
+         // publisher_data lives under testEnvironmentPath which the
+         // afterEach cleans up) + ~6 MB BQ schema scan. Both well
+         // under any meaningful free-tier limit. Test budget: 3 min
+         // (clone is ~30-60s on GH runners; compile is ~10s).
+         it(
+            "should load bq-hackernews package and compile its models via real BQ",
+            async () => {
+               if (!hasPublicDataBigQueryCredentials()) {
+                  console.log(
+                     "Skipping: BIGQUERY_PUBLIC_DATA_CREDENTIALS or BIGQUERY_PUBLIC_DATA_PROJECT_ID not configured",
+                  );
+                  return;
+               }
+
+               const serviceAccountJson =
+                  await readPublicDataBigQueryServiceAccountJson();
+
+               // Each test gets its own serverRoot so publisher_data
+               // doesn't leak across tests; afterEach removes
+               // testEnvironmentPath which carries the whole tree
+               // away.
+               const tempServerRoot = path.join(
+                  testEnvironmentPath,
+                  "bq-hackernews-pkg-test",
+               );
+               await fs.mkdir(tempServerRoot, { recursive: true });
+
+               const config = {
+                  frozenConfig: false,
+                  environments: [
+                     {
+                        name: "malloy-samples",
+                        packages: [
+                           {
+                              name: "bigquery-hackernews",
+                              location:
+                                 "https://github.com/credibledata/malloy-samples/tree/main/bigquery-hackernews",
+                           },
+                        ],
+                        connections: [
+                           {
+                              name: "bigquery",
+                              type: "bigquery",
+                              bigqueryConnection: {
+                                 defaultProjectId:
+                                    process.env
+                                       .BIGQUERY_PUBLIC_DATA_PROJECT_ID!,
+                                 serviceAccountKeyJson: serviceAccountJson,
+                              },
+                           },
+                        ],
+                     },
+                  ],
+               };
+               await fs.writeFile(
+                  path.join(tempServerRoot, "publisher.config.json"),
+                  JSON.stringify(config),
+               );
+
+               // Force the load-from-config init path. Without this,
+               // EnvironmentStore.initialize() takes the load-from-DB
+               // branch and only falls back to config when the DB is
+               // empty (which it is here, by construction, but relying
+               // on that is brittle if the test pattern is reused).
+               //
+               // SAFETY PRECONDITION: this flag is the SAME one users
+               // opt into via `--init` / `start:init` to wipe persisted
+               // storage and re-initialize from config (see CLAUDE.md
+               // and `environment_store.ts:158`). It is destructive on
+               // a real serverRoot. We only set it here because
+               // `tempServerRoot` is a freshly-created empty directory
+               // (path.join(testEnvironmentPath, "bq-hackernews-pkg-test")
+               // mkdir'd ~20 lines above), so there is nothing to wipe.
+               // DO NOT copy this pattern into a test that points
+               // EnvironmentStore at a non-empty or shared serverRoot
+               // — it will delete state.
+               const previousInitializeStorage = process.env.INITIALIZE_STORAGE;
+               process.env.INITIALIZE_STORAGE = "true";
+
+               try {
+                  const envStore = new EnvironmentStore(tempServerRoot);
+                  await envStore.finishedInitialization;
+
+                  // operationalState=serving is the only signal that
+                  // initialize() actually succeeded. initialize swallows
+                  // top-level errors and just calls markNotReady() (see
+                  // environment_store.ts:297-301), so
+                  // finishedInitialization always resolves regardless of
+                  // success. By construction (env_store:288-292), serving
+                  // also implies all configured environments loaded.
+                  const status = await envStore.getStatus();
+                  expect(status.operationalState).toBe("serving");
+
+                  const env = await envStore.getEnvironment("malloy-samples");
+                  const apiPackages = await env.listPackages();
+                  expect(apiPackages.map((p) => p.name)).toContain(
+                     "bigquery-hackernews",
+                  );
+
+                  const apiConnections = env.listApiConnections();
+                  expect(apiConnections.map((c) => c.name)).toContain(
+                     "bigquery",
+                  );
+
+                  // The actual integration assertion. Package.listModels()
+                  // collects compile errors per-model and returns ALL
+                  // models in the result (with `error` populated on
+                  // failures) — so models.length>0 alone would pass even
+                  // if every BQ schema introspection failed. Filter for
+                  // models that compiled cleanly: at least one is the
+                  // real proof that BQ-on-behalf-of-a-package works.
+                  const pkg = await env.getPackage("bigquery-hackernews");
+                  const models = await pkg.listModels();
+                  const okModels = models.filter((m) => !m.error);
+                  if (okModels.length === 0) {
+                     console.error(
+                        "All bq-hackernews model compilations failed:",
+                        models.map((m) => `${m.path}: ${m.error}`),
+                     );
+                  }
+                  expect(okModels.length).toBeGreaterThan(0);
+               } finally {
+                  if (previousInitializeStorage === undefined) {
+                     delete process.env.INITIALIZE_STORAGE;
+                  } else {
+                     process.env.INITIALIZE_STORAGE = previousInitializeStorage;
+                  }
+               }
+            },
+            { timeout: 180000 },
+         );
+      });
+
       describe("DuckDB with Snowflake attachment", () => {
          it(
             "should create DuckDB connection with attached Snowflake database",