@malloy-publisher/server 0.0.232 → 0.0.234

package/src/service/connection_config.ts

@@ -2,7 +2,13 @@ import { createPrivateKey } from "crypto";
 import { existsSync } from "fs";
 import path from "path";
 import { components } from "../api";
+import { logger } from "../logger";
 import { parseHostKeys } from "./proxy";
+import {
+   queryMetadataAdvisoryWarnings,
+   queryMetadataBudgetWarning,
+   queryMetadataViolations,
+} from "./query_metadata";
 
 type ApiConnection = components["schemas"]["Connection"];
 type AttachedDatabase = components["schemas"]["AttachedDatabase"];
@@ -271,6 +277,48 @@ function buildDuckdbEntry(
    };
 }
 
+/**
+ * Report a connection default that will not do what it says — a property name
+ * the contract rejects, one BigQuery would drop, a bag with no room for the
+ * server's own context.
+ *
+ * Warns rather than throws, unlike everything else in this file: query metadata
+ * is observability, and an environment that refuses to load because a tag has a
+ * hyphen in it would trade a missing label for an outage. The connection update
+ * API rejects the same bag outright (see validateAdminAuthoredConnection) —
+ * strict where a human is waiting, lenient where a config is being loaded.
+ */
+function warnOnConnectionQueryMetadata(connection: ApiConnection): void {
+   let declared = 0;
+   for (const field of ["queryMetadata", "queryMetadataEnforced"] as const) {
+      const metadata = connection[field];
+      if (!metadata) continue;
+      declared += Object.keys(metadata).length;
+      const problems = [
+         ...queryMetadataViolations(metadata),
+         ...queryMetadataAdvisoryWarnings(metadata),
+      ];
+      for (const problem of problems) {
+         logger.warn("Connection query metadata will not apply as declared", {
+            connectionName: connection.name,
+            field,
+            problem,
+         });
+      }
+   }
+   // The budget is checked over BOTH maps, not each one: they merge into the
+   // same bag, so a connection declaring 6 defaults and 6 enforced is over it
+   // while neither map is. This is the boundary where the admin who created the
+   // squeeze is the one reading the warning.
+   const overBudget = queryMetadataBudgetWarning(declared);
+   if (overBudget) {
+      logger.warn("Connection query metadata will not apply as declared", {
+         connectionName: connection.name,
+         problem: overBudget,
+      });
+   }
+}
+
 function validateConnectionShape(connection: ApiConnection): void {
    if (connection.proxy) {
       // A connection proxy makes THIS server open an outbound SSH tunnel to a
@@ -444,6 +492,32 @@ function validateConnectionShape(connection: ApiConnection): void {
                `Storage bucketUrl is required for DuckLake: ${connection.name}`,
             );
          }
+         // metadataSchema is optional, but when present it reaches the ATTACH as a
+         // quoted string literal AND the catalog-format preflight as a quoted
+         // identifier. Rather than escape one value for two grammars, restrict it
+         // to a plain identifier here — a deterministic config error, caught at
+         // load instead of at the connection's first attach.
+         //
+         // The typeof check is load-bearing, not defensive: the value arrives from
+         // untyped JSON, and RegExp.test() coerces its argument, so `true` and `null`
+         // both satisfy the pattern as "true"/"null" and would reach escapeSQL's
+         // String.replace as a non-string — a TypeError at the first attach, which is
+         // exactly the failure this check exists to turn into a config error.
+         if (
+            connection.ducklakeConnection.catalog.metadataSchema !== undefined
+         ) {
+            const schema = connection.ducklakeConnection.catalog.metadataSchema;
+            if (
+               typeof schema !== "string" ||
+               !/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)
+            ) {
+               throw new Error(
+                  `DuckLake catalog metadataSchema must be a plain identifier ` +
+                     `([A-Za-z_][A-Za-z0-9_]*), got '${schema}' for connection: ` +
+                     `${connection.name}`,
+               );
+            }
+         }
          break;
       case "trino":
          if (!connection.trinoConnection) {
@@ -580,6 +654,7 @@ export function assembleEnvironmentConnections(
       processedConnections.add(connection.name);
       validateDuckdbApiSurface(connection);
       validateConnectionShape(connection);
+      warnOnConnectionQueryMetadata(connection);
 
       const apiConnection = cloneApiConnection(connection);
       apiConnection.attributes = getStaticConnectionAttributes(connection.type);

package/src/service/duckdb_instance_isolation.spec.ts

@@ -0,0 +1,137 @@
+import { DuckDBConnection } from "@malloydata/db-duckdb";
+import { afterEach, describe, expect, it } from "bun:test";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+
+/**
+ * Pins the DuckDB instance-isolation contract that same-named connections depend
+ * on for multi-tenant safety.
+ *
+ * `@malloydata/db-duckdb` pools DuckDB instances in a process-global cache keyed
+ * by a share key that deliberately EXCLUDES the connection name, and it caches a
+ * `:memory:` primary like any other. Meanwhile the DuckLake attach aliases by
+ * connection name (`ATTACH OR REPLACE … AS <name>`). Put those together and two
+ * same-named connections that land on ONE pooled instance clobber each other's
+ * attach: one ends up reading the other's database.
+ *
+ * `createIsolatedBuildSession` prevents that by giving every build session a
+ * unique `workingDirectory`, relying on it participating in the share key. That
+ * is an upstream implementation detail, so nothing here asserted it — and the
+ * failure mode is silent: no error, just the wrong data. This spec asserts the
+ * behaviour instead of the mechanism, so it holds however upstream achieves it.
+ *
+ * Deliberately NOT asserted: the converse (same name AND same working directory
+ * DO share an instance). That is the pooling artifact, not a property we want; if
+ * upstream ever made pooling connection-aware, asserting it would fail on an
+ * improvement.
+ *
+ * Each connection creates and populates its OWN attached store rather than
+ * reopening a pre-seeded file. Handing a file from one connection to another
+ * requires the first to have released its OS lock, and `close()` is refcount-only
+ * — which fails outright under Windows' mandatory locking. Attaching a store the
+ * connection itself owns avoids the handoff, and matches how a DuckLake
+ * destination is actually used.
+ */
+describe("DuckDB instance isolation", () => {
+   const tempDirs: string[] = [];
+   const openConnections: DuckDBConnection[] = [];
+
+   const tempDir = async (label: string): Promise<string> => {
+      const dir = await fs.mkdtemp(
+         path.join(os.tmpdir(), `duckdb-iso-${label}-`),
+      );
+      tempDirs.push(dir);
+      return dir;
+   };
+
+   afterEach(async () => {
+      for (const connection of openConnections) {
+         await connection.close().catch(() => undefined);
+      }
+      openConnections.length = 0;
+      for (const dir of tempDirs) {
+         // Best-effort: a still-locked file must not fail the test.
+         await fs
+            .rm(dir, { recursive: true, force: true })
+            .catch(() => undefined);
+      }
+      tempDirs.length = 0;
+   });
+
+   /**
+    * A connection with the given name and its own working directory, which
+    * attaches its own private store under `alias` and writes one distinguishing
+    * value into it.
+    */
+   const connectionWithOwnStore = async (
+      name: string,
+      label: string,
+      alias: string,
+      value: number,
+   ): Promise<DuckDBConnection> => {
+      const sessionDir = await tempDir(`session-${label}`);
+      const connection = new DuckDBConnection(name, ":memory:", sessionDir);
+      openConnections.push(connection);
+      const storeDir = await tempDir(`store-${label}`);
+      const storeFile = path.join(storeDir, `${label}.duckdb`);
+      // OR REPLACE mirrors the DuckLake attach: on a shared instance the second
+      // caller silently replaces the first caller's alias.
+      await connection.runSQL(`ATTACH OR REPLACE '${storeFile}' AS ${alias};`);
+      await connection.runSQL(
+         `CREATE OR REPLACE TABLE ${alias}.t AS SELECT ${value} AS x;`,
+      );
+      return connection;
+   };
+
+   const readValue = async (
+      connection: DuckDBConnection,
+      alias: string,
+   ): Promise<number> => {
+      const result = await connection.runSQL(`SELECT x FROM ${alias}.t;`);
+      return Number(Object.values(result.rows[0])[0]);
+   };
+
+   it("keeps same-named connections apart when their working directories differ", async () => {
+      // Identical connection NAME and identical `:memory:` primary — only the
+      // working directory differs. That is exactly the shape a build session
+      // uses, and the only thing standing between it and a shared instance.
+      //
+      // ORDERING IS LOAD-BEARING FOR THIS TEST. The instance cache is consulted
+      // inside an async `init()`, so constructing both connections before either
+      // is used lets both race past the cache miss and each create a private
+      // instance — isolation for the wrong reason, and a test that could never
+      // fail. Each helper call fully initializes its connection (the ATTACH
+      // forces it) before the next is built, so a shared share key really would
+      // hand back the cached instance. Verified: with identical working
+      // directories this ordering yields 2 for both connections — the clobber.
+      const a = await connectionWithOwnStore("store", "a", "lake", 1);
+      const b = await connectionWithOwnStore("store", "b", "lake", 2);
+
+      expect(await readValue(a, "lake")).toBe(1);
+      expect(await readValue(b, "lake")).toBe(2);
+   });
+
+   it("keeps a build-session-shaped connection apart from a long-lived one", async () => {
+      // The pairing the build-session comment calls out specifically: a transient
+      // build session overlapping a long-lived serve connection. Same name, same
+      // alias, both `:memory:` — distinct only by working directory.
+      const serve = await connectionWithOwnStore(
+         "credible",
+         "serve",
+         "lake",
+         10,
+      );
+      const build = await connectionWithOwnStore(
+         "credible",
+         "build",
+         "lake",
+         20,
+      );
+
+      // The serve connection must still see its own store after the build
+      // session attaches a different one under the same alias.
+      expect(await readValue(serve, "lake")).toBe(10);
+      expect(await readValue(build, "lake")).toBe(20);
+   });
+});

package/src/service/environment.ts

@@ -1639,6 +1639,60 @@ export class Environment {
             logger.warn(`Could not read manifest for ${packageName}`);
          }
 
+         const onDiskMaterialization =
+            existingManifest.materialization !== null &&
+            typeof existingManifest.materialization === "object" &&
+            !Array.isArray(existingManifest.materialization)
+               ? (existingManifest.materialization as Record<string, unknown>)
+               : undefined;
+
+         // Scope has two homes: `materialization.scope` (canonical) and the
+         // manifest root (deprecated). The server writes BOTH, in sync, for as
+         // long as the root form is supported:
+         //
+         //  - writing only the root would author a manifest this build's loader
+         //    refuses, since a root that disagrees with an existing envelope is a
+         //    conflict (see resolvePackageScope);
+         //  - writing only the envelope would silently downgrade a package read
+         //    by an older publisher, which knows only the root and would default
+         //    to `package` — cross-version table reuse for a package declared
+         //    `version`.
+         //
+         // A caller can only express scope through the top-level `scope` field
+         // (the wire materialization block has no `scope`), so an envelope value
+         // already on disk is preserved rather than dropped by a materialization
+         // PATCH that says nothing about it.
+         const resolvedScope =
+            metadata.scope ??
+            (onDiskMaterialization?.scope as ApiPackage["scope"] | undefined) ??
+            (existingManifest.scope as ApiPackage["scope"] | undefined);
+
+         // A materialization PATCH replaces the block wholesale, which is right
+         // for schedule and freshness — they are the policy the caller is
+         // setting, and they are mutually exclusive with each other.
+         // `queryMetadata` is orthogonal to both: a client setting a schedule
+         // has no reason to re-send the package's tags, and dropping them
+         // silently untags every statement the package's builds issue. So it is
+         // preserved on omission, like `scope` above; an explicit null still
+         // clears it, which keeps the block expressible.
+         const preservedQueryMetadata =
+            metadata.materialization !== undefined &&
+            metadata.materialization?.queryMetadata === undefined &&
+            onDiskMaterialization?.queryMetadata !== undefined
+               ? { queryMetadata: onDiskMaterialization.queryMetadata }
+               : {};
+
+         const materializationBase: Record<string, unknown> | undefined =
+            metadata.materialization !== undefined
+               ? { ...metadata.materialization, ...preservedQueryMetadata }
+               : onDiskMaterialization !== undefined
+                 ? { ...onDiskMaterialization }
+                 : undefined;
+         const materializationBlock =
+            resolvedScope !== undefined
+               ? { ...(materializationBase ?? {}), scope: resolvedScope }
+               : materializationBase;
+
          // Update with new metadata. `explores`/`queryableSources` are only
          // overwritten when the caller explicitly provides them; otherwise the
          // existing on-disk value is preserved via the spread (an undefined here
@@ -1656,9 +1710,9 @@ export class Environment {
             ...(metadata.manifestLocation !== undefined
                ? { manifestLocation: metadata.manifestLocation }
                : {}),
-            ...(metadata.scope !== undefined ? { scope: metadata.scope } : {}),
-            ...(metadata.materialization !== undefined
-               ? { materialization: metadata.materialization }
+            ...(resolvedScope !== undefined ? { scope: resolvedScope } : {}),
+            ...(materializationBlock !== undefined
+               ? { materialization: materializationBlock }
                : {}),
          };
 

package/src/service/materialization_config_validation.spec.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "bun:test";
+import type { components } from "../api";
+import { materializationConfigWarnings } from "./materialization_config_validation";
+
+const source = (
+   name: string,
+   queryMetadata: Record<string, string> | null,
+): components["schemas"]["PersistSourcePlan"] => ({
+   name,
+   sourceID: `${name}@m`,
+   connectionName: "duckdb",
+   sourceEntityId: "bid",
+   sql: "SELECT 1",
+   columns: [],
+   queryMetadata,
+});
+
+describe("materializationConfigWarnings", () => {
+   it("says nothing about a clean config", () => {
+      expect(
+         materializationConfigWarnings({
+            packageMaterialization: {
+               schedule: null,
+               freshness: null,
+               queryMetadata: { team: "finance" },
+            },
+            sources: [source("orders", { team: "finance" })],
+         }),
+      ).toEqual([]);
+   });
+
+   it("passes manifest deprecations through", () => {
+      expect(
+         materializationConfigWarnings({
+            manifestWarnings: ['"scope" at the manifest root is deprecated'],
+         }),
+      ).toEqual([{ message: '"scope" at the manifest root is deprecated' }]);
+   });
+
+   it("reports a package-level property that violates the contract", () => {
+      const warnings = materializationConfigWarnings({
+         packageMaterialization: {
+            schedule: null,
+            freshness: null,
+            queryMetadata: { "team.name": "finance" },
+         },
+      });
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0].message).toContain("materialization.queryMetadata");
+      expect(warnings[0].message).toContain("team.name");
+      expect(warnings[0].target).toBeUndefined();
+   });
+
+   it("reports the offending property at the source that resolves it", () => {
+      const warnings = materializationConfigWarnings({
+         sources: [source("orders", { "team.name": "finance" })],
+      });
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0].target).toBe("orders");
+      expect(warnings[0].message).toContain("#@ persist queryMetadata");
+   });
+
+   it("reports a BigQuery-dropped name as a warning, not silence", () => {
+      const warnings = materializationConfigWarnings({
+         sources: [source("orders", { _team: "finance" })],
+      });
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0].message).toMatch(/BigQuery/);
+   });
+
+   it("reports the problem at every level that resolves it", () => {
+      // The package declares it and both sources inherit it. Reporting each
+      // level is what lets an author find the one they can edit; identical
+      // messages are collapsed, different levels are not.
+      const warnings = materializationConfigWarnings({
+         packageMaterialization: {
+            schedule: null,
+            freshness: null,
+            queryMetadata: { "team.name": "finance" },
+         },
+         sources: [
+            source("orders", { "team.name": "finance" }),
+            source("returns", { "team.name": "finance" }),
+         ],
+      });
+      expect(warnings).toHaveLength(3);
+      expect(warnings.map((w) => w.target)).toEqual([
+         undefined,
+         "orders",
+         "returns",
+      ]);
+   });
+
+   it("ignores sources with no metadata", () => {
+      expect(
+         materializationConfigWarnings({ sources: [source("orders", null)] }),
+      ).toEqual([]);
+   });
+});

package/src/service/materialization_config_validation.ts

@@ -0,0 +1,120 @@
+/**
+ * Publish-time validation of a package's materialization config.
+ *
+ * One module for the rules so they cannot drift between the levels a knob can be
+ * declared at. Two principles, both learned from shipped bugs:
+ *
+ *  1. **Nothing is silently dropped.** A declaration that will not do what it
+ *     says has to surface somewhere — a publish error, a publish warning, a 400,
+ *     or a metered runtime drop. A `#@ persist` name that was silently ignored
+ *     (source published, never materialized, no error anywhere) is why
+ *     `persist_annotation_validation.ts` exists; the same rule applies here.
+ *  2. **Strict at declaration, lenient at execution.** Publish and the API have a
+ *     human behind them and report problems; the runtime resolve path clamps and
+ *     meters instead, because metadata must never break a query or a build.
+ *
+ * Today this owns the `queryMetadata` rules and the manifest-shape deprecations,
+ * which are ADVISORY — they surface on the package's operator warnings array.
+ * They deliberately do NOT go through `Package.persistencePolicyWarnings`, which
+ * is a publish REJECTION gate (and disarms the scheduler): a deprecated manifest
+ * shape or a mistyped tag must not stop a package from publishing. The
+ * scope/schedule/freshness coherence rules that do reject still live there;
+ * moving them here is a mechanical follow-up with no behavior change.
+ */
+
+import type { components } from "../api";
+import {
+   queryMetadataAdvisoryWarnings,
+   queryMetadataBudgetWarning,
+   queryMetadataViolations,
+   type QueryMetadata,
+} from "./query_metadata";
+
+type WirePackageMaterialization =
+   components["schemas"]["PackageMaterializationConfig"];
+type WirePersistSourcePlan = components["schemas"]["PersistSourcePlan"];
+
+export interface MaterializationConfigInput {
+   /** The package manifest's `materialization` block, as parsed. */
+   packageMaterialization?: WirePackageMaterialization | null;
+   /** The compiled plan's sources, carrying each one's RESOLVED metadata. */
+   sources?: WirePersistSourcePlan[];
+   /**
+    * Deprecations the manifest parse tolerated (e.g. a root-level `scope`), which
+    * a load keeps working but a publish should report.
+    */
+   manifestWarnings?: string[];
+}
+
+/** One finding, in the shape the wire package's operator warnings array uses. */
+export interface MaterializationConfigWarning {
+   /** The persist source the finding belongs to, absent for a package-level one. */
+   target?: string;
+   message: string;
+}
+
+function metadataWarnings(
+   level: string,
+   metadata: QueryMetadata | null | undefined,
+   target?: string,
+): MaterializationConfigWarning[] {
+   if (!metadata) return [];
+   const budget = queryMetadataBudgetWarning(Object.keys(metadata).length);
+   return [
+      ...queryMetadataViolations(metadata),
+      ...queryMetadataAdvisoryWarnings(metadata),
+      ...(budget ? [budget] : []),
+   ].map((message) => ({
+      // The level is in the message because a reader needs to know WHICH
+      // declaration to edit, and an inherited property has more than one.
+      message: `${level}: ${message}`,
+      ...(target ? { target } : {}),
+   }));
+}
+
+/**
+ * Everything wrong or inadvisable about a package's materialization config, as
+ * actionable messages. Warnings rather than errors: a package published before a
+ * rule existed must keep loading, and a bad metadata property degrades
+ * attribution rather than corrupting anything.
+ *
+ * A source's metadata is checked in its RESOLVED form (the effective bag from
+ * package → model-file → `#@ persist`), because that is what will actually be
+ * attached — a property inherited from the manifest is just as broken at the
+ * source as it is at the package, and reporting it at both is how an author finds
+ * the one they can edit.
+ */
+export function materializationConfigWarnings(
+   input: MaterializationConfigInput,
+): MaterializationConfigWarning[] {
+   const warnings: MaterializationConfigWarning[] = (
+      input.manifestWarnings ?? []
+   ).map((message) => ({ message }));
+
+   warnings.push(
+      ...metadataWarnings(
+         "materialization.queryMetadata",
+         input.packageMaterialization?.queryMetadata,
+      ),
+   );
+
+   for (const source of input.sources ?? []) {
+      warnings.push(
+         ...metadataWarnings(
+            `#@ persist queryMetadata`,
+            source.queryMetadata,
+            source.name,
+         ),
+      );
+   }
+
+   // Identical findings collapse (two sources inheriting one bad package
+   // property produce one message each, not one per level per source).
+   const seen = new Set<string>();
+   return warnings.filter((warning) => {
+      const key = `${warning.target ?? ""}\u0000${warning.message}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+   });
+}

package/src/service/materialization_schedule_surface.spec.ts

@@ -54,6 +54,7 @@ describe("materialization schedule surfacing", () => {
          expect(pkg.getPackageMetadata().materialization).toEqual({
             schedule: "0 6 * * *",
             freshness: null,
+            queryMetadata: null,
          });
       },
       { timeout: 20000 },
@@ -77,6 +78,7 @@ describe("materialization schedule surfacing", () => {
          expect(pkg.getPackageMetadata().materialization).toEqual({
             schedule: null,
             freshness: { window: "24h", fallback: "stale_ok" },
+            queryMetadata: null,
          });
       },
       { timeout: 20000 },
@@ -119,14 +121,136 @@ describe("materialization schedule surfacing", () => {
          expect(updated.materialization).toEqual({
             schedule: "0 6 * * *",
             freshness: null,
+            queryMetadata: null,
          });
 
          const pkg = await env.getPackage("pkg", false);
          expect(pkg.getPackageMetadata().materialization).toEqual({
             schedule: "0 6 * * *",
             freshness: null,
+            queryMetadata: null,
          });
       },
       { timeout: 20000 },
    );
+
+   async function readManifest(): Promise<Record<string, unknown>> {
+      return JSON.parse(
+         await fs.readFile(path.join(envPath, "pkg", "publisher.json"), "utf8"),
+      );
+   }
+
+   it(
+      "writes scope to both homes so the manifest it authors still loads",
+      async () => {
+         // A scope PATCH used to write only the manifest root. With scope also
+         // living in the materialization block, that authored a manifest whose
+         // two homes disagreed — which the loader refuses, so the package
+         // survived the PATCH and then failed on the next restart.
+         const env = await Environment.create("testEnv", envPath, []);
+         await writePackageDir({
+            materialization: {
+               scope: "package",
+               queryMetadata: { team: "fin" },
+            },
+         });
+         await env.addPackage("pkg");
+
+         await env.updatePackage("pkg", { name: "pkg", scope: "version" });
+
+         const manifest = await readManifest();
+         expect(manifest.scope).toBe("version");
+         expect(manifest.materialization).toMatchObject({
+            scope: "version",
+            queryMetadata: { team: "fin" },
+         });
+
+         // The real assertion: it loads again.
+         const reloaded = await Environment.create("testEnv", envPath, []);
+         await reloaded.addPackage("pkg");
+         const pkg = await reloaded.getPackage("pkg", false);
+         expect(pkg.getPackageMetadata().scope).toBe("version");
+      },
+      { timeout: 20000 },
+   );
+
+   it(
+      "keeps the envelope scope a materialization PATCH cannot express",
+      async () => {
+         // The wire materialization block has no `scope`, so a PATCH that sends
+         // one must not be read as "the author dropped it".
+         const env = await Environment.create("testEnv", envPath, []);
+         await writePackageDir({ materialization: { scope: "version" } });
+         await env.addPackage("pkg");
+
+         await env.updatePackage("pkg", {
+            name: "pkg",
+            materialization: { schedule: "0 6 * * *" },
+         });
+
+         const manifest = await readManifest();
+         expect(manifest.materialization).toMatchObject({
+            scope: "version",
+            schedule: "0 6 * * *",
+         });
+         expect(manifest.scope).toBe("version");
+      },
+      { timeout: 20000 },
+   );
+
+   it(
+      "keeps queryMetadata a schedule PATCH said nothing about",
+      async () => {
+         // The block is replaced wholesale, which is right for the policy the
+         // caller is setting — but queryMetadata is orthogonal to it, so a
+         // client that sets a schedule without re-sending the tags would
+         // silently untag every statement the package's builds issue. The UI
+         // and the control plane are separate clients; preserving it here fixes
+         // all of them at once.
+         const env = await Environment.create("testEnv", envPath, []);
+         await writePackageDir({
+            materialization: {
+               scope: "version",
+               queryMetadata: { team: "finance" },
+            },
+         });
+         await env.addPackage("pkg");
+
+         await env.updatePackage("pkg", {
+            name: "pkg",
+            materialization: { schedule: "0 6 * * *" },
+         });
+
+         expect((await readManifest()).materialization).toMatchObject({
+            schedule: "0 6 * * *",
+            queryMetadata: { team: "finance" },
+         });
+      },
+      { timeout: 20000 },
+   );
+
+   it(
+      "still lets an explicit null clear queryMetadata",
+      async () => {
+         // Preserved-on-omission must not make it unclearable.
+         const env = await Environment.create("testEnv", envPath, []);
+         await writePackageDir({
+            materialization: {
+               scope: "version",
+               queryMetadata: { team: "finance" },
+            },
+         });
+         await env.addPackage("pkg");
+
+         await env.updatePackage("pkg", {
+            name: "pkg",
+            materialization: { schedule: "0 6 * * *", queryMetadata: null },
+         });
+
+         expect(
+            (await readManifest()).materialization as Record<string, unknown>,
+         ).toMatchObject({ schedule: "0 6 * * *", queryMetadata: null });
+      },
+      { timeout: 20000 },
+   );
 });