@malloy-publisher/server 0.0.198-dev → 0.0.198

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.198-dev",
+   "version": "0.0.198",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -34,16 +34,16 @@
       "@azure/identity": "^4.13.0",
       "@azure/storage-blob": "^12.26.0",
       "@google-cloud/storage": "^7.16.0",
-      "@malloydata/db-bigquery": "^0.0.383",
-      "@malloydata/db-databricks": "^0.0.383",
-      "@malloydata/db-duckdb": "^0.0.383",
-      "@malloydata/db-mysql": "^0.0.383",
-      "@malloydata/db-postgres": "^0.0.383",
-      "@malloydata/db-snowflake": "^0.0.383",
-      "@malloydata/db-trino": "^0.0.383",
-      "@malloydata/malloy": "^0.0.383",
-      "@malloydata/malloy-sql": "^0.0.383",
-      "@malloydata/render-validator": "^0.0.383",
+      "@malloydata/db-bigquery": "^0.0.394",
+      "@malloydata/db-databricks": "^0.0.394",
+      "@malloydata/db-duckdb": "^0.0.394",
+      "@malloydata/db-mysql": "^0.0.394",
+      "@malloydata/db-postgres": "^0.0.394",
+      "@malloydata/db-snowflake": "^0.0.394",
+      "@malloydata/db-trino": "^0.0.394",
+      "@malloydata/malloy": "^0.0.394",
+      "@malloydata/malloy-sql": "^0.0.394",
+      "@malloydata/render-validator": "^0.0.394",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.57.0",
@@ -68,7 +68,6 @@
       "node-cron": "^3.0.3",
       "recursive-readdir": "^2.2.3",
       "simple-git": "^3.28.0",
-      "trino": "^1.1.1",
       "uuid": "^11.0.3"
    },
    "devDependencies": {

package/publisher.config.example.bigquery.json

@@ -0,0 +1,33 @@
+{
+  "frozenConfig": false,
+  "environments": [
+    {
+      "name": "malloy-samples",
+      "packages": [
+        {
+          "name": "ecommerce",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+        },
+        {
+          "name": "imdb",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+        },
+        {
+          "name": "faa",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+        },
+        {
+          "name": "bigquery-hackernews",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/bigquery-hackernews"
+        }
+      ],
+      "connections": [
+        {
+          "name": "bigquery",
+          "type": "bigquery",
+          "bigqueryConnection": {}
+        }
+      ]
+    }
+  ]
+}

package/publisher.config.example.duckdb.json

@@ -0,0 +1,23 @@
+{
+  "frozenConfig": false,
+  "environments": [
+    {
+      "name": "malloy-samples",
+      "packages": [
+        {
+          "name": "ecommerce",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/ecommerce"
+        },
+        {
+          "name": "imdb",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/imdb"
+        },
+        {
+          "name": "faa",
+          "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
+        }
+      ],
+      "connections": []
+    }
+  ]
+}

package/publisher.config.json

@@ -15,19 +15,9 @@
         {
           "name": "faa",
           "location": "https://github.com/credibledata/malloy-samples/tree/main/faa"
-        },
-        {
-          "name": "bigquery-hackernews",
-          "location": "https://github.com/credibledata/malloy-samples/tree/main/bigquery-hackernews"
         }
       ],
-      "connections": [
-        {
-          "name": "bigquery",
-          "type": "bigquery",
-          "bigqueryConnection": {}
-        }
-      ]
+      "connections": []
     }
   ]
 }

package/src/config.spec.ts

@@ -856,3 +856,309 @@ describe("Config Environment Variable Substitution", () => {
       });
    });
 });
+
+// TODO: Remove this during projects cleanup
+describe("Config legacy 'projects' key back-compat", () => {
+   const testServerRoot = path.join(process.cwd(), "test-temp-legacy-config");
+   const configPath = path.join(testServerRoot, PUBLISHER_CONFIG_NAME);
+
+   beforeEach(() => {
+      if (!fs.existsSync(testServerRoot)) {
+         fs.mkdirSync(testServerRoot, { recursive: true });
+      }
+   });
+
+   afterEach(() => {
+      if (fs.existsSync(configPath)) {
+         fs.unlinkSync(configPath);
+      }
+      if (fs.existsSync(testServerRoot)) {
+         fs.rmdirSync(testServerRoot, { recursive: true });
+      }
+   });
+
+   it("reads from legacy 'projects' key when 'environments' is absent", async () => {
+      // Pre-rename on-disk shape: top-level key is `projects`, not
+      // `environments`. Without back-compat this silently parses as empty.
+      const legacyConfig = {
+         frozenConfig: false,
+         projects: [
+            {
+               name: "legacy-env",
+               packages: [
+                  {
+                     name: "p1",
+                     location: "./packages/p1",
+                  },
+               ],
+            },
+         ],
+      };
+
+      fs.writeFileSync(configPath, JSON.stringify(legacyConfig, null, 2));
+
+      // Spy on logger.warn so we can assert the deprecation message fired.
+      const { logger } = await import("./logger");
+      const originalWarn = logger.warn;
+      const warnings: string[] = [];
+      logger.warn = ((msg: unknown, ..._rest: unknown[]) => {
+         warnings.push(typeof msg === "string" ? msg : String(msg));
+         return logger;
+      }) as typeof logger.warn;
+
+      try {
+         const result = getPublisherConfig(testServerRoot);
+
+         expect(result.environments.length).toBe(1);
+         expect(result.environments[0].name).toBe("legacy-env");
+         expect(result.environments[0].packages[0].name).toBe("p1");
+
+         expect(
+            warnings.some((w) => w.includes('uses deprecated "projects" key')),
+         ).toBe(true);
+      } finally {
+         logger.warn = originalWarn;
+      }
+   });
+
+   it("prefers the new 'environments' key when both are present", async () => {
+      const config = {
+         frozenConfig: false,
+         environments: [
+            {
+               name: "new-env",
+               packages: [{ name: "p1", location: "./packages/p1" }],
+            },
+         ],
+         projects: [
+            {
+               name: "should-be-ignored",
+               packages: [{ name: "p2", location: "./packages/p2" }],
+            },
+         ],
+      };
+
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+      const { logger } = await import("./logger");
+      const originalWarn = logger.warn;
+      const warnings: string[] = [];
+      logger.warn = ((msg: unknown, ..._rest: unknown[]) => {
+         warnings.push(typeof msg === "string" ? msg : String(msg));
+         return logger;
+      }) as typeof logger.warn;
+
+      try {
+         const result = getPublisherConfig(testServerRoot);
+
+         expect(result.environments.length).toBe(1);
+         expect(result.environments[0].name).toBe("new-env");
+
+         // No deprecation warning should fire when `environments` is present.
+         expect(
+            warnings.some((w) => w.includes('uses deprecated "projects" key')),
+         ).toBe(false);
+      } finally {
+         logger.warn = originalWarn;
+      }
+   });
+});
+
+describe("Committed example configs", () => {
+   const serverDir = path.resolve(__dirname, "..");
+
+   it.each([
+      ["publisher.config.json", false],
+      ["publisher.config.example.duckdb.json", false],
+      ["publisher.config.example.bigquery.json", true],
+   ])(
+      "%s parses as a valid PublisherConfig",
+      (filename, expectsBigQueryConnection) => {
+         const filePath = path.join(serverDir, filename);
+         expect(fs.existsSync(filePath)).toBe(true);
+
+         const raw = fs.readFileSync(filePath, "utf-8");
+         const parsed = JSON.parse(raw) as PublisherConfig;
+
+         expect(parsed).toHaveProperty("environments");
+         expect(Array.isArray(parsed.environments)).toBe(true);
+         expect(parsed.environments.length).toBeGreaterThan(0);
+
+         const env = parsed.environments[0];
+         expect(env.name).toBeTruthy();
+         expect(Array.isArray(env.packages)).toBe(true);
+         expect(env.packages.length).toBeGreaterThan(0);
+
+         if (expectsBigQueryConnection) {
+            expect(
+               (env.connections ?? []).some((c) => c.type === "bigquery"),
+            ).toBe(true);
+            expect(
+               env.packages.some((p) => p.name === "bigquery-hackernews"),
+            ).toBe(true);
+         } else {
+            expect(
+               env.packages.some((p) => p.name === "bigquery-hackernews"),
+            ).toBe(false);
+         }
+      },
+   );
+});
+
+describe("Config path resolution (--config and bundled default)", () => {
+   const emptyServerRoot = path.join(process.cwd(), "test-empty-server-root");
+   const customConfigPath = path.join(
+      process.cwd(),
+      "test-custom-publisher.config.json",
+   );
+
+   beforeEach(() => {
+      if (!fs.existsSync(emptyServerRoot)) {
+         fs.mkdirSync(emptyServerRoot, { recursive: true });
+      }
+      delete process.env.PUBLISHER_CONFIG_PATH;
+      delete process.env.PUBLISHER_USE_BUNDLED_DEFAULT;
+   });
+
+   afterEach(() => {
+      delete process.env.PUBLISHER_CONFIG_PATH;
+      delete process.env.PUBLISHER_USE_BUNDLED_DEFAULT;
+      if (fs.existsSync(customConfigPath)) {
+         fs.unlinkSync(customConfigPath);
+      }
+      if (fs.existsSync(emptyServerRoot)) {
+         fs.rmSync(emptyServerRoot, { recursive: true, force: true });
+      }
+   });
+
+   it("falls back to the bundled default config when serverRoot has no publisher.config.json and bundled-default opt-in is set", () => {
+      // The bundled default is opt-in (server.ts sets the env var when
+      // the user passed neither --server_root nor --config) so embedded
+      // callers don't get a surprise filesystem read.
+      process.env.PUBLISHER_USE_BUNDLED_DEFAULT = "true";
+      const result = getPublisherConfig(emptyServerRoot);
+
+      expect(result.environments.length).toBeGreaterThan(0);
+      const env = result.environments[0];
+      expect(env.name).toBe("malloy-samples");
+      expect(env.packages.some((p) => p.name === "ecommerce")).toBe(true);
+      expect(env.packages.some((p) => p.name === "bigquery-hackernews")).toBe(
+         false,
+      );
+   });
+
+   it("does NOT fall back to the bundled default when opt-in flag is unset (programmatic construction)", () => {
+      // No PUBLISHER_USE_BUNDLED_DEFAULT, no PUBLISHER_CONFIG_PATH, no
+      // file in emptyServerRoot — result should be the original empty
+      // shape, preserving prior behavior for embeds and tests.
+      const result = getPublisherConfig(emptyServerRoot);
+      expect(result.environments).toEqual([]);
+   });
+
+   it("honors PUBLISHER_CONFIG_PATH (set by --config) over the server root", () => {
+      const customConfig = {
+         frozenConfig: false,
+         environments: [
+            { name: "custom-env", packages: [{ name: "foo", location: "/x" }] },
+         ],
+      };
+      fs.writeFileSync(customConfigPath, JSON.stringify(customConfig));
+      process.env.PUBLISHER_CONFIG_PATH = customConfigPath;
+
+      const result = getPublisherConfig(emptyServerRoot);
+      expect(result.environments[0].name).toBe("custom-env");
+   });
+
+   it("returns empty environments (not the bundled default) when --config points at a missing file", () => {
+      process.env.PUBLISHER_CONFIG_PATH = path.join(
+         process.cwd(),
+         "does-not-exist.json",
+      );
+      // Even with bundled-default opt-in, --config with a missing target
+      // is a user error and we don't paper over it.
+      process.env.PUBLISHER_USE_BUNDLED_DEFAULT = "true";
+      const result = getPublisherConfig(emptyServerRoot);
+      expect(result.environments).toEqual([]);
+   });
+});
+
+describe("getMemoryGovernorConfig", () => {
+   const GOVERNOR_ENV_VARS = [
+      "PUBLISHER_MAX_MEMORY_BYTES",
+      "PUBLISHER_MEMORY_HIGH_WATER_FRACTION",
+      "PUBLISHER_MEMORY_LOW_WATER_FRACTION",
+      "PUBLISHER_MEMORY_CHECK_INTERVAL_MS",
+      "PUBLISHER_MEMORY_BACKPRESSURE",
+   ];
+
+   beforeEach(() => {
+      for (const v of GOVERNOR_ENV_VARS) delete process.env[v];
+   });
+   afterEach(() => {
+      for (const v of GOVERNOR_ENV_VARS) delete process.env[v];
+   });
+
+   it("returns null when PUBLISHER_MAX_MEMORY_BYTES is unset", async () => {
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(getMemoryGovernorConfig()).toBeNull();
+   });
+
+   it("parses defaults when only PUBLISHER_MAX_MEMORY_BYTES is set", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = String(2 * 1024 * 1024 * 1024);
+      const { getMemoryGovernorConfig } = await import("./config");
+      const cfg = getMemoryGovernorConfig();
+      expect(cfg).not.toBeNull();
+      expect(cfg!.maxMemoryBytes).toBe(2 * 1024 * 1024 * 1024);
+      expect(cfg!.backpressureEnabled).toBe(true);
+      expect(cfg!.highWaterFraction).toBeGreaterThan(cfg!.lowWaterFraction);
+   });
+
+   it("honours fraction and interval overrides", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "1000000000";
+      process.env.PUBLISHER_MEMORY_HIGH_WATER_FRACTION = "0.85";
+      process.env.PUBLISHER_MEMORY_LOW_WATER_FRACTION = "0.7";
+      process.env.PUBLISHER_MEMORY_CHECK_INTERVAL_MS = "10000";
+      process.env.PUBLISHER_MEMORY_BACKPRESSURE = "false";
+      const { getMemoryGovernorConfig } = await import("./config");
+      const cfg = getMemoryGovernorConfig();
+      expect(cfg).not.toBeNull();
+      expect(cfg!.highWaterFraction).toBe(0.85);
+      expect(cfg!.lowWaterFraction).toBe(0.7);
+      expect(cfg!.checkIntervalMs).toBe(10000);
+      expect(cfg!.backpressureEnabled).toBe(false);
+   });
+
+   it("treats PUBLISHER_MAX_MEMORY_BYTES=0 as disabled (returns null)", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "0";
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(getMemoryGovernorConfig()).toBeNull();
+   });
+
+   it("rejects a negative PUBLISHER_MAX_MEMORY_BYTES", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "-1";
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(() => getMemoryGovernorConfig()).toThrow();
+   });
+
+   it("rejects low >= high", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "1000000000";
+      process.env.PUBLISHER_MEMORY_HIGH_WATER_FRACTION = "0.7";
+      process.env.PUBLISHER_MEMORY_LOW_WATER_FRACTION = "0.8";
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(() => getMemoryGovernorConfig()).toThrow();
+   });
+
+   it("rejects an out-of-range fraction", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "1000000000";
+      process.env.PUBLISHER_MEMORY_HIGH_WATER_FRACTION = "1.5";
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(() => getMemoryGovernorConfig()).toThrow();
+   });
+
+   it("rejects a check interval below the safety floor", async () => {
+      process.env.PUBLISHER_MAX_MEMORY_BYTES = "1000000000";
+      process.env.PUBLISHER_MEMORY_CHECK_INTERVAL_MS = "10";
+      const { getMemoryGovernorConfig } = await import("./config");
+      expect(() => getMemoryGovernorConfig()).toThrow();
+   });
+});

package/src/config.ts

@@ -1,9 +1,68 @@
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 import { components } from "./api";
 import { API_PREFIX, PUBLISHER_CONFIG_NAME } from "./constants";
 import { logger } from "./logger";
 
+/**
+ * Path to the publisher.config.json file shipped inside the published
+ * package. Used as a last-resort fallback so `npx @malloy-publisher/server`
+ * with no args still boots with the DuckDB-only sample packages.
+ *
+ * The file is copied next to the running module by `build.ts` at production
+ * build time. In a source/dev checkout it lives alongside this file.
+ */
+const BUNDLED_DEFAULT_CONFIG_PATH = path.join(
+   path.dirname(fileURLToPath(import.meta.url)),
+   "default-publisher.config.json",
+);
+
+/**
+ * Decide which `publisher.config.json` to read.
+ *
+ * Precedence:
+ *   1. `--config <path>` (surfaced via `process.env.PUBLISHER_CONFIG_PATH`)
+ *   2. `<serverRoot>/publisher.config.json`
+ *   3. The bundled default shipped inside the package — ONLY when
+ *      `process.env.PUBLISHER_USE_BUNDLED_DEFAULT === "true"`. server.ts
+ *      sets that flag when the user passed neither `--server_root` nor
+ *      `--config`, so `npx @malloy-publisher/server` with zero args
+ *      boots into something usable. Callers that construct an
+ *      EnvironmentStore programmatically (tests, embeds) don't get
+ *      surprise filesystem fallbacks they didn't ask for.
+ *
+ * Returns `null` if step 1 was requested but the file doesn't exist —
+ * that's an explicit user mistake and the caller should surface it as
+ * an error rather than silently falling back.
+ */
+function resolvePublisherConfigPath(serverRoot: string): {
+   path: string;
+   isBundledDefault: boolean;
+} | null {
+   const explicitPath = process.env.PUBLISHER_CONFIG_PATH;
+   if (explicitPath && explicitPath.length > 0) {
+      if (!fs.existsSync(explicitPath)) {
+         return null;
+      }
+      return { path: explicitPath, isBundledDefault: false };
+   }
+
+   const serverRootPath = path.join(serverRoot, PUBLISHER_CONFIG_NAME);
+   if (fs.existsSync(serverRootPath)) {
+      return { path: serverRootPath, isBundledDefault: false };
+   }
+
+   if (
+      process.env.PUBLISHER_USE_BUNDLED_DEFAULT === "true" &&
+      fs.existsSync(BUNDLED_DEFAULT_CONFIG_PATH)
+   ) {
+      return { path: BUNDLED_DEFAULT_CONFIG_PATH, isBundledDefault: true };
+   }
+
+   return null;
+}
+
 type FilesystemPath = `./${string}` | `../${string}` | `/${string}`;
 type GcsPath = `gs://${string}`;
 type ApiConnection = components["schemas"]["Connection"];
@@ -40,6 +99,132 @@ export type ProcessedPublisherConfig = {
    environments: ProcessedEnvironment[];
 };
 
+/**
+ * Tunables for {@link PackageMemoryGovernor}. All values are sourced
+ * from environment variables at startup; see {@link getMemoryGovernorConfig}
+ * for parsing and defaults.
+ *
+ * The governor is admission control only: it polls process RSS on
+ * `checkIntervalMs` and toggles a single `isBackpressured` flag using
+ * a low/high-water hysteresis band. It does NOT evict, unload, or
+ * interrupt already-loaded packages — recovery is left to the kernel
+ * reclaiming pages as in-flight traffic completes.
+ */
+export interface MemoryGovernorConfig {
+   /** Hard ceiling for process RSS in bytes (the OOM-relevant figure). */
+   maxMemoryBytes: number;
+   /** Fraction of `maxMemoryBytes` at which the governor activates back-pressure (new package loads start returning HTTP 503). Must be in (0, 1) and strictly greater than `lowWaterFraction`. */
+   highWaterFraction: number;
+   /** Fraction of `maxMemoryBytes` at which the governor clears back-pressure (new package loads admitted again). Must be in (0, 1) and strictly less than `highWaterFraction`; the gap is the hysteresis band that prevents flap. */
+   lowWaterFraction: number;
+   /** Polling cadence for the RSS sampler, in milliseconds. */
+   checkIntervalMs: number;
+   /** When true, RSS crossings flip the back-pressure flag. When false, the governor still samples and emits metrics but never rejects requests — useful for a monitoring-only rollout before enabling the 503 behaviour. */
+   backpressureEnabled: boolean;
+}
+
+const DEFAULT_HIGH_WATER_FRACTION = 0.8;
+const DEFAULT_LOW_WATER_FRACTION = 0.7;
+const DEFAULT_CHECK_INTERVAL_MS = 5_000;
+const MIN_CHECK_INTERVAL_MS = 100;
+
+function parseIntEnv(name: string): number | undefined {
+   const raw = process.env[name];
+   if (raw === undefined || raw.trim() === "") return undefined;
+   const value = Number.parseInt(raw, 10);
+   if (!Number.isFinite(value) || String(value) !== raw.trim()) {
+      throw new Error(
+         `Invalid value for ${name}: expected a base-10 integer, got "${raw}"`,
+      );
+   }
+   return value;
+}
+
+function parseFloatEnv(name: string): number | undefined {
+   const raw = process.env[name];
+   if (raw === undefined || raw.trim() === "") return undefined;
+   const value = Number.parseFloat(raw);
+   if (!Number.isFinite(value)) {
+      throw new Error(
+         `Invalid value for ${name}: expected a finite number, got "${raw}"`,
+      );
+   }
+   return value;
+}
+
+function parseBoolEnv(name: string): boolean | undefined {
+   const raw = process.env[name];
+   if (raw === undefined || raw.trim() === "") return undefined;
+   const normalised = raw.trim().toLowerCase();
+   if (["1", "true", "yes", "on"].includes(normalised)) return true;
+   if (["0", "false", "no", "off"].includes(normalised)) return false;
+   throw new Error(
+      `Invalid value for ${name}: expected a boolean (true/false), got "${raw}"`,
+   );
+}
+
+/**
+ * Parse memory-governor settings from environment variables and return
+ * either a fully-validated config or `null` when the feature is
+ * disabled. The feature is disabled iff `PUBLISHER_MAX_MEMORY_BYTES`
+ * is unset or set to `0`.
+ *
+ * Throws at startup on malformed input so a typo in a k8s manifest
+ * surfaces as a loud failure rather than silently disabling the cap.
+ */
+export const getMemoryGovernorConfig = (): MemoryGovernorConfig | null => {
+   const maxMemoryBytes = parseIntEnv("PUBLISHER_MAX_MEMORY_BYTES");
+   if (maxMemoryBytes === undefined || maxMemoryBytes === 0) {
+      return null;
+   }
+   if (maxMemoryBytes < 0) {
+      throw new Error(
+         `PUBLISHER_MAX_MEMORY_BYTES must be a positive integer (got ${maxMemoryBytes})`,
+      );
+   }
+
+   const highWaterFraction =
+      parseFloatEnv("PUBLISHER_MEMORY_HIGH_WATER_FRACTION") ??
+      DEFAULT_HIGH_WATER_FRACTION;
+   const lowWaterFraction =
+      parseFloatEnv("PUBLISHER_MEMORY_LOW_WATER_FRACTION") ??
+      DEFAULT_LOW_WATER_FRACTION;
+   const checkIntervalMs =
+      parseIntEnv("PUBLISHER_MEMORY_CHECK_INTERVAL_MS") ??
+      DEFAULT_CHECK_INTERVAL_MS;
+   const backpressureEnabled =
+      parseBoolEnv("PUBLISHER_MEMORY_BACKPRESSURE") ?? true;
+
+   if (highWaterFraction <= 0 || highWaterFraction >= 1) {
+      throw new Error(
+         `PUBLISHER_MEMORY_HIGH_WATER_FRACTION must be in (0, 1) (got ${highWaterFraction})`,
+      );
+   }
+   if (lowWaterFraction <= 0 || lowWaterFraction >= 1) {
+      throw new Error(
+         `PUBLISHER_MEMORY_LOW_WATER_FRACTION must be in (0, 1) (got ${lowWaterFraction})`,
+      );
+   }
+   if (lowWaterFraction >= highWaterFraction) {
+      throw new Error(
+         `PUBLISHER_MEMORY_LOW_WATER_FRACTION (${lowWaterFraction}) must be strictly less than PUBLISHER_MEMORY_HIGH_WATER_FRACTION (${highWaterFraction})`,
+      );
+   }
+   if (checkIntervalMs < MIN_CHECK_INTERVAL_MS) {
+      throw new Error(
+         `PUBLISHER_MEMORY_CHECK_INTERVAL_MS must be >= ${MIN_CHECK_INTERVAL_MS} (got ${checkIntervalMs})`,
+      );
+   }
+
+   return {
+      maxMemoryBytes,
+      highWaterFraction,
+      lowWaterFraction,
+      checkIntervalMs,
+      backpressureEnabled,
+   };
+};
+
 function substituteEnvVars(value: string): string {
    const envVarPattern = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 
@@ -77,13 +262,30 @@ function processConfigValue(value: unknown): unknown {
 }
 
 export const getPublisherConfig = (serverRoot: string): PublisherConfig => {
-   const publisherConfigPath = path.join(serverRoot, PUBLISHER_CONFIG_NAME);
-   if (!fs.existsSync(publisherConfigPath)) {
+   const resolved = resolvePublisherConfigPath(serverRoot);
+   if (!resolved) {
+      if (
+         process.env.PUBLISHER_CONFIG_PATH &&
+         process.env.PUBLISHER_CONFIG_PATH.length > 0
+      ) {
+         // Explicit --config was given but the path didn't exist. Loud
+         // failure here so a typo in the flag doesn't silently boot the
+         // server with an empty environment list.
+         logger.error(
+            `--config path not found: ${process.env.PUBLISHER_CONFIG_PATH}. Using default empty config.`,
+         );
+      }
       return {
          frozenConfig: false,
          environments: [],
       };
    }
+   const publisherConfigPath = resolved.path;
+   if (resolved.isBundledDefault) {
+      logger.info(
+         `No publisher.config.json found at ${path.join(serverRoot, PUBLISHER_CONFIG_NAME)}; falling back to bundled DuckDB-only default. Pass --config <path> or place a config in the server root to override.`,
+      );
+   }
 
    let rawConfig: unknown;
    try {
@@ -108,6 +310,24 @@ export const getPublisherConfig = (serverRoot: string): PublisherConfig => {
    // Process environment variables in config values
    const processedConfig = processConfigValue(rawConfig);
 
+   // TODO: Remove this during projects cleanup
+   // Back-compat: the top-level key was renamed `projects` → `environments`.
+   // If a config still uses the old key, accept it once with a deprecation
+   // warning so existing on-disk configs don't silently parse as empty.
+   if (
+      processedConfig &&
+      typeof processedConfig === "object" &&
+      !("environments" in processedConfig) &&
+      "projects" in processedConfig
+   ) {
+      logger.warn(
+         `${PUBLISHER_CONFIG_NAME} uses deprecated "projects" key; rename to "environments".`,
+      );
+      (processedConfig as Record<string, unknown>).environments = (
+         processedConfig as Record<string, unknown>
+      ).projects;
+   }
+
    if (
       processedConfig &&
       typeof processedConfig === "object" &&