@malloy-publisher/server 0.0.233 → 0.0.235

package/src/service/package_manifest.ts

@@ -18,10 +18,10 @@ export const PACKAGE_SCOPES = ["version", "package"] as const;
 export type PackageScope = (typeof PACKAGE_SCOPES)[number];
 
 /**
- * Read the manifest root's `scope`, defaulting to `"package"` when absent or
- * null. Any other value is a manifest error: scope is load-bearing (it decides
- * version-owned vs cross-version reuse), so a typo must fail loudly rather than
- * silently pick a default. Throws on an invalid value.
+ * Read a `scope` value, defaulting to `"package"` when absent or null. Any other
+ * value is a manifest error: scope is load-bearing (it decides version-owned vs
+ * cross-version reuse), so a typo must fail loudly rather than silently pick a
+ * default. Throws on an invalid value.
  */
 export function parsePackageScope(raw: unknown): PackageScope {
    if (raw === undefined || raw === null) {
@@ -36,6 +36,69 @@ export function parsePackageScope(raw: unknown): PackageScope {
    );
 }
 
+/**
+ * Resolve the package's scope from its two possible homes: `materialization.scope`
+ * (canonical — every other build-behavioral knob lives in that block) and the
+ * manifest root (the original home, deprecated).
+ *
+ * The root form keeps working because scope rides the published artifact: a
+ * package published before the move must keep parsing until it is republished.
+ * Declaring DIFFERENT values in the two homes throws, because scope decides
+ * whether an artifact is version-owned and guessing which one the author meant
+ * could reuse a table across versions that was never supposed to be shared.
+ *
+ * Only a root-ONLY declaration is deprecated. Both homes agreeing is the
+ * transition state the server itself writes (see `writePackageManifest`): the
+ * envelope for this build, the root for an older publisher that would otherwise
+ * silently default to `package`. Warning about that would be warning an operator
+ * about something the server did on their behalf and they cannot fix.
+ */
+export function resolvePackageScope(
+   rootRaw: unknown,
+   materializationRaw: unknown,
+): { scope: PackageScope; warnings: string[] } {
+   const envelopeRaw =
+      materializationRaw && typeof materializationRaw === "object"
+         ? (materializationRaw as { scope?: unknown }).scope
+         : undefined;
+   const rootDeclared = rootRaw !== undefined && rootRaw !== null;
+   const envelopeDeclared = envelopeRaw !== undefined && envelopeRaw !== null;
+
+   // Validate both homes before comparing, so a typo is reported as a typo
+   // rather than as a conflict.
+   const rootScope = parsePackageScope(rootRaw);
+   const envelopeScope = parsePackageScope(envelopeRaw);
+
+   if (rootDeclared && envelopeDeclared) {
+      if (rootScope !== envelopeScope) {
+         // Names the fix, because this throw fails the package LOAD: the
+         // package is skipped and its only trace is /status loadErrors, so the
+         // message is the whole diagnosis. Guessing instead would be worse —
+         // picking the wrong one reuses a table across versions that was never
+         // meant to be shared, silently.
+         throw new Error(
+            `Conflicting "scope" in publisher.json: root "${rootScope}" vs ` +
+               `"materialization.scope" "${envelopeScope}". The package cannot ` +
+               `load until they agree. Edit "materialization": { "scope": ... } ` +
+               `to the value you want and delete the root-level "scope" (the ` +
+               `server rewrites both homes on its next manifest write).`,
+         );
+      }
+      return { scope: envelopeScope, warnings: [] };
+   }
+   if (rootDeclared) {
+      return { scope: rootScope, warnings: [SCOPE_ROOT_DEPRECATION] };
+   }
+   return { scope: envelopeScope, warnings: [] };
+}
+
+const SCOPE_ROOT_DEPRECATION =
+   `"scope" at the manifest root is deprecated: declare it as ` +
+   `"materialization": { "scope": ... } alongside the other build knobs. The ` +
+   `root form still works and will be removed in a future release; until then ` +
+   `the server keeps both homes in sync when it writes the manifest, so an ` +
+   `older publisher still reads the right value.`;
+
 /**
  * The manifest's `materialization.freshness` block, surfaced verbatim for the
  * control plane (which owns the scheduling and query-time gating logic).
@@ -63,6 +126,18 @@ export interface PackageMaterializationConfig {
     * "no policy" from "policy with no valid fields".
     */
    freshness: PackageFreshnessConfig | null;
+   /**
+    * Package-level per-query metadata: the least specific model-side layer,
+    * overridden per property by a model-file, source or per-request declaration.
+    * Null when the manifest declares none.
+    *
+    * Kept VERBATIM (every string-valued property, conforming or not) rather than
+    * filtered to what Malloy will accept. A property that violates the contract
+    * has to be visible somewhere to be fixable: publish reports it as a warning
+    * from this block, and the runtime clamps it with a metric. Filtering here
+    * would make an author's typo disappear with nothing to point at.
+    */
+   queryMetadata: Record<string, string> | null;
 }
 
 function parseFreshness(raw: unknown): PackageFreshnessConfig | null {
@@ -83,11 +158,55 @@ function parseFreshness(raw: unknown): PackageFreshnessConfig | null {
    return freshness;
 }
 
+/**
+ * The `materialization.queryMetadata` block: string-valued properties verbatim.
+ * A non-object block, or one with no string values, degrades to null so absence
+ * on the wire always means "declared nothing usable". A non-string value is
+ * dropped here because it cannot round-trip as a property at all; contract
+ * violations of the string values are deliberately NOT dropped (see
+ * {@link PackageMaterializationConfig.queryMetadata}).
+ *
+ * Each dropped value is reported, because the drop happens BEFORE the config
+ * validation that would otherwise name it: an unquoted `"team": 123` is a
+ * plausible hand-edit, and without this it disappears with nothing anywhere to
+ * point at.
+ */
+function parseQueryMetadata(raw: unknown): {
+   metadata: Record<string, string> | null;
+   warnings: string[];
+} {
+   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return { metadata: null, warnings: [] };
+   }
+   const out: Record<string, string> = {};
+   const warnings: string[] = [];
+   for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof value === "string") {
+         out[name] = value;
+      } else {
+         warnings.push(
+            `materialization.queryMetadata: property '${name}' must be a ` +
+               `string (got ${value === null ? "null" : typeof value}); it is ` +
+               `not attached to any statement`,
+         );
+      }
+   }
+   return {
+      metadata: Object.keys(out).length > 0 ? out : null,
+      warnings,
+   };
+}
+
 /**
  * Read the manifest's `materialization` object, keeping only recognized fields.
  * Returns null when the block is absent so the API field is null rather than an
  * empty object; a non-string schedule degrades to null, and an absent or
  * non-object freshness degrades to null.
+ *
+ * `materialization.scope` is deliberately NOT read here: scope is a package-level
+ * mode rather than a layered knob, and it has two possible homes to reconcile —
+ * see {@link resolvePackageScope}, which owns that read and surfaces the
+ * resolved value on the package itself.
  */
 export function parsePackageMaterialization(
    raw: unknown,
@@ -95,12 +214,28 @@ export function parsePackageMaterialization(
    if (!raw || typeof raw !== "object") {
       return null;
    }
-   const { schedule, freshness } = raw as {
+   const { schedule, freshness, queryMetadata } = raw as {
       schedule?: unknown;
       freshness?: unknown;
+      queryMetadata?: unknown;
    };
    return {
       schedule: typeof schedule === "string" ? schedule : null,
       freshness: parseFreshness(freshness),
+      queryMetadata: parseQueryMetadata(queryMetadata).metadata,
    };
 }
+
+/**
+ * What the `materialization` parse tolerated but could not keep, for the
+ * operator warnings array. Reads the same parse as
+ * {@link parsePackageMaterialization} rather than re-deriving it, so the two
+ * cannot disagree about what was dropped.
+ */
+export function packageMaterializationWarnings(raw: unknown): string[] {
+   if (!raw || typeof raw !== "object") {
+      return [];
+   }
+   const { queryMetadata } = raw as { queryMetadata?: unknown };
+   return parseQueryMetadata(queryMetadata).warnings;
+}

package/src/service/persist_annotation_validation.spec.ts

@@ -66,6 +66,18 @@ describe("assertPersistNamesQuoted", () => {
       ).not.toThrow();
    });
 
+   it("does not mistake a DOTTED key for the name field", () => {
+      // `.` is a word boundary, so a `\b`-anchored pattern reads
+      // `queryMetadata.name=` as the persist name and fails the whole model
+      // load with a 424 about quoting a name the author never declared.
+      expect(() =>
+         assertPersistNamesQuoted(
+            `#@ persist name="bar" queryMetadata.name=finance`,
+            "m.malloy",
+         ),
+      ).not.toThrow();
+   });
+
    it("reports every offending annotation in the message", () => {
       expect(() =>
          assertPersistNamesQuoted(

package/src/service/persist_annotation_validation.ts

@@ -5,11 +5,16 @@ const PERSIST_LINE_PATTERN = /^\s*#@\s+persist\b/;
 /**
  * A `name=` key whose value is NOT immediately opened by a single or double
  * quote — i.e. a bare `name=engaged_events` (whitespace around `=` tolerated).
- * `name="..."` and `name='...'` pass. The `\bname` word boundary requires a
- * standalone key, so neighbours like `tablename=` / `realization_name=` are
- * never mistaken for it.
+ * `name="..."` and `name='...'` pass.
+ *
+ * The lookbehind requires a standalone key: neither an `_`-joined neighbour
+ * (`tablename=`, `realization_name=`) nor a DOTTED one (`queryMetadata.name=`)
+ * is the persist name. A `\b` word boundary would catch the underscore case but
+ * not the dotted one, because `.` is itself a boundary — so a legitimate
+ * `#@ persist queryMetadata.name=finance` would fail the load with a 424 about
+ * quoting a persist name it never declared.
  */
-const UNQUOTED_NAME_PATTERN = /\bname\s*=\s*(?!["'])/;
+const UNQUOTED_NAME_PATTERN = /(?<![.\w])name\s*=\s*(?!["'])/;
 
 /**
  * Reject `#@ persist name=<value>` annotations whose name is unquoted.

package/src/service/query_metadata.spec.ts

@@ -0,0 +1,408 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+   CONTEXT_SHED_ORDER,
+   MAX_PROPERTIES,
+   MAX_PROPERTY_VALUE_LENGTH,
+   mergeQueryMetadata,
+   mintCorrelationId,
+   parseQueryClass,
+   parseSuppliedQueryMetadata,
+   queryContextProperties,
+   RESERVED_CONTEXT_PROPERTIES,
+   queryMetadataAdvisoryWarnings,
+   queryMetadataBudgetWarning,
+   queryMetadataViolations,
+} from "./query_metadata";
+
+const originalMode = process.env.PUBLISHER_QUERY_METADATA;
+
+// The feature ships dark, so every test of the resolution logic has to turn it
+// on. The one test that asserts what `off` does sets it back for itself.
+beforeEach(() => {
+   process.env.PUBLISHER_QUERY_METADATA = "on";
+});
+
+afterEach(() => {
+   if (originalMode === undefined) {
+      delete process.env.PUBLISHER_QUERY_METADATA;
+   } else {
+      process.env.PUBLISHER_QUERY_METADATA = originalMode;
+   }
+});
+
+describe("queryMetadataViolations", () => {
+   it("accepts a conforming bag", () => {
+      expect(
+         queryMetadataViolations({ team: "finance", run_id: "abc-123" }),
+      ).toEqual([]);
+      expect(queryMetadataViolations(undefined)).toEqual([]);
+      expect(queryMetadataViolations(null)).toEqual([]);
+   });
+
+   it("rejects a non-object", () => {
+      expect(queryMetadataViolations("team=finance")).toHaveLength(1);
+      expect(queryMetadataViolations([1, 2])).toHaveLength(1);
+   });
+
+   it("rejects a property name outside the contract", () => {
+      // A dot is the one an author reaches for first, and Malloy throws on it at
+      // dispatch — so it has to come back as a message here.
+      expect(queryMetadataViolations({ "team.name": "finance" })).toHaveLength(
+         1,
+      );
+      expect(queryMetadataViolations({ "team-name": "finance" })).toHaveLength(
+         1,
+      );
+   });
+
+   it("rejects a value that cannot be rendered", () => {
+      expect(queryMetadataViolations({ team: 'fin"ance' })).toHaveLength(1);
+      expect(queryMetadataViolations({ team: "fin\nance" })).toHaveLength(1);
+      expect(queryMetadataViolations({ team: "финансы" })).toHaveLength(1);
+   });
+
+   it("rejects a non-string value, naming the property", () => {
+      const problems = queryMetadataViolations({ retries: 3 });
+      expect(problems).toHaveLength(1);
+      expect(problems[0]).toContain("retries");
+   });
+
+   it("rejects an over-long value and too many properties", () => {
+      expect(
+         queryMetadataViolations({
+            team: "x".repeat(MAX_PROPERTY_VALUE_LENGTH + 1),
+         }),
+      ).toHaveLength(1);
+      const tooMany: Record<string, string> = {};
+      for (let i = 0; i <= MAX_PROPERTIES; i++) tooMany[`p${i}`] = "v";
+      expect(queryMetadataViolations(tooMany)).toHaveLength(1);
+   });
+});
+
+describe("queryMetadataAdvisoryWarnings", () => {
+   it("flags a name BigQuery will silently drop", () => {
+      // Legal per the contract, kept by every other backend, gone on BigQuery.
+      expect(queryMetadataAdvisoryWarnings({ _team: "finance" })).toHaveLength(
+         1,
+      );
+      expect(
+         queryMetadataAdvisoryWarnings({ "2team": "finance" }),
+      ).toHaveLength(1);
+      expect(queryMetadataAdvisoryWarnings({ team2: "finance" })).toEqual([]);
+   });
+});
+
+describe("queryContextProperties", () => {
+   it("emits only the fields that are set", () => {
+      expect(
+         queryContextProperties({
+            queryClass: "materialize",
+            environment: "prod",
+            package: "sales",
+            source: "order_rollup",
+            trigger: "scheduler",
+            runId: "run-7",
+            correlationId: "q-1",
+         }),
+      ).toEqual({
+         class: "materialize",
+         environment: "prod",
+         package: "sales",
+         source: "order_rollup",
+         trigger: "scheduler",
+         run_id: "run-7",
+         query_id: "q-1",
+      });
+      expect(queryContextProperties({})).toEqual({});
+   });
+});
+
+describe("queryMetadataBudgetWarning", () => {
+   it("warns when a declaration leaves no room for the server context", () => {
+      // 20 is the size of the whole bag, and the server adds its own on top, so
+      // a declaration that fills the contract quietly loses properties later.
+      expect(queryMetadataBudgetWarning(MAX_PROPERTIES)).toContain(
+         "the server adds up to",
+      );
+      expect(queryMetadataBudgetWarning(1)).toBeUndefined();
+   });
+
+   it("is a count, not a bag, so a caller can sum the maps that share the budget", () => {
+      // A connection declares a default AND an enforced map; 6 + 6 is over
+      // budget while neither map is.
+      const authorBudget = MAX_PROPERTIES - RESERVED_CONTEXT_PROPERTIES;
+      expect(queryMetadataBudgetWarning(authorBudget)).toBeUndefined();
+      expect(queryMetadataBudgetWarning(authorBudget + 1)).toBeDefined();
+   });
+});
+
+describe("CONTEXT_SHED_ORDER", () => {
+   it("covers every context property exactly once", () => {
+      // The shed order also sizes the author budget the declaration warning
+      // uses, so a context property added to one list and not the other would
+      // quietly move that threshold.
+      const every = queryContextProperties({
+         queryClass: "interactive",
+         environment: "e",
+         package: "p",
+         version: "v",
+         model: "m.malloy",
+         source: "s",
+         trigger: "publish",
+         runId: "r",
+         correlationId: "q",
+      });
+      expect([...CONTEXT_SHED_ORDER].sort()).toEqual(Object.keys(every).sort());
+      expect(RESERVED_CONTEXT_PROPERTIES).toBe(Object.keys(every).length);
+   });
+});
+
+describe("mintCorrelationId", () => {
+   it("mints a distinct id per call", () => {
+      const first = mintCorrelationId();
+      expect(first).toMatch(/^[0-9a-f-]{36}$/);
+      expect(mintCorrelationId()).not.toBe(first);
+   });
+});
+
+describe("mergeQueryMetadata", () => {
+   it("returns nothing when every layer is empty", () => {
+      expect(mergeQueryMetadata({})).toEqual({ drops: [] });
+   });
+
+   it("merges most-specific-wins per property", () => {
+      const resolved = mergeQueryMetadata({
+         connection: { team: "finance", tier: "bronze", deployment: "eu" },
+         model: { tier: "silver", surface: "marts" },
+         request: { tier: "gold" },
+      });
+      expect(resolved.metadata).toEqual({
+         team: "finance",
+         tier: "gold",
+         surface: "marts",
+         deployment: "eu",
+      });
+   });
+
+   it("lets context win over an author property of the same name", () => {
+      // Otherwise a caller could label its own interactive query as a build and
+      // corrupt exactly the attribution this feature exists to produce.
+      const resolved = mergeQueryMetadata({
+         request: { class: "materialize", package: "not-this-one" },
+         context: { queryClass: "interactive", package: "sales" },
+      });
+      expect(resolved.metadata).toEqual({
+         class: "interactive",
+         package: "sales",
+      });
+   });
+
+   it("reserves query_id: a caller cannot supply the correlation key", () => {
+      // The response hands this back as the join key, so a caller-owned value
+      // would let two calls claim the same id.
+      const resolved = mergeQueryMetadata({
+         request: { query_id: "mine" },
+         context: { correlationId: "server-minted" },
+      });
+      expect(resolved.metadata?.query_id).toBe("server-minted");
+   });
+
+   it("lets an enforced property beat every declaration", () => {
+      // The connection API is administered; a package annotation and a request
+      // are not. A tenant must not be able to relabel the traffic its host is
+      // billed for.
+      const resolved = mergeQueryMetadata({
+         connection: { org: "acme" },
+         model: { org: "not_acme" },
+         request: { org: "definitely_not_acme" },
+         enforced: { org: "acme" },
+      });
+      expect(resolved.metadata?.org).toBe("acme");
+   });
+
+   it("still lets the server's own context beat an enforced property", () => {
+      // Context describes what the server is actually doing; an admin cannot
+      // declare a query into a different class.
+      const resolved = mergeQueryMetadata({
+         enforced: { class: "interactive", org: "acme" },
+         context: { queryClass: "materialize" },
+      });
+      expect(resolved.metadata).toEqual({ class: "materialize", org: "acme" });
+   });
+
+   it("sheds enforced properties after every declared one", () => {
+      // The point of enforcing a property is that it is still there at the end:
+      // twenty declared properties must not be able to push it out of the bag.
+      const request: Record<string, string> = {};
+      for (let i = 0; i < MAX_PROPERTIES; i++) request[`p${i}`] = "v";
+      const resolved = mergeQueryMetadata({
+         request,
+         enforced: { org: "acme" },
+         context: { queryClass: "interactive" },
+      });
+      expect(resolved.metadata?.org).toBe("acme");
+      expect(resolved.metadata?.class).toBe("interactive");
+      expect(resolved.drops.every((d) => d.name.startsWith("p"))).toBe(true);
+   });
+
+   it("keeps a property named __proto__, which the contract allows", () => {
+      // `__proto__` passes the name rule, so it reaches the merge — and on an
+      // object literal the assignment hits the prototype setter, which ignores
+      // a string and drops the property with no drop record and no metric. It
+      // is the one silent loss in a module whose whole argument is that a lost
+      // property is always accounted for.
+      // JSON.parse, not a literal: `__proto__:` in source sets the prototype,
+      // while a parsed request body carries it as an own property — which is
+      // how it arrives here.
+      const resolved = mergeQueryMetadata({
+         request: JSON.parse('{"__proto__":"surprise","team":"finance"}'),
+      });
+      expect(Object.keys(resolved.metadata ?? {}).sort()).toEqual([
+         "__proto__",
+         "team",
+      ]);
+      expect(resolved.drops).toEqual([]);
+      // A string property, not a reshaped bag.
+      expect(JSON.stringify(resolved.metadata)).toContain('"__proto__"');
+   });
+
+   it("drops a property whose name violates the contract", () => {
+      // Never throws: it would fail the customer's query at dispatch.
+      const resolved = mergeQueryMetadata({
+         request: { "team.name": "finance", team: "finance" },
+      });
+      expect(resolved.metadata).toEqual({ team: "finance" });
+      expect(resolved.drops).toEqual([
+         { name: "team.name", reason: "invalid_name" },
+      ]);
+   });
+
+   it("sanitizes an unrenderable value instead of failing", () => {
+      const resolved = mergeQueryMetadata({
+         request: { note: 'a"b\nc' },
+      });
+      expect(resolved.metadata).toEqual({ note: "a_b_c" });
+   });
+
+   it("truncates an over-long value", () => {
+      const resolved = mergeQueryMetadata({
+         request: { note: "x".repeat(MAX_PROPERTY_VALUE_LENGTH + 50) },
+      });
+      expect(resolved.metadata?.note).toHaveLength(MAX_PROPERTY_VALUE_LENGTH);
+   });
+
+   it("sheds the least specific author property first", () => {
+      // The caller's own per-request property is the last one standing: it is
+      // most likely its join key, and precedence says the connection-wide
+      // default is the cheapest thing to lose.
+      const connection: Record<string, string> = {};
+      for (let i = 0; i < MAX_PROPERTIES - 2; i++) connection[`c${i}`] = "v";
+      const resolved = mergeQueryMetadata({
+         connection,
+         model: { modelProp: "m" },
+         request: { request_id: "7f3a" },
+         context: { queryClass: "interactive", package: "sales" },
+      });
+      expect(resolved.metadata?.request_id).toBe("7f3a");
+      expect(resolved.metadata?.modelProp).toBe("m");
+      expect(resolved.drops.every((d) => d.name.startsWith("c"))).toBe(true);
+   });
+
+   it("sheds by the layer whose value won, not the first that mentioned it", () => {
+      // `tier` is declared on the connection but the request's value is what
+      // survives, so it must be shed as a request property, i.e. last.
+      const connection: Record<string, string> = { tier: "bronze" };
+      for (let i = 0; i < MAX_PROPERTIES; i++) connection[`c${i}`] = "v";
+      const resolved = mergeQueryMetadata({
+         connection,
+         request: { tier: "gold" },
+         context: { queryClass: "interactive" },
+      });
+      expect(resolved.metadata?.tier).toBe("gold");
+   });
+
+   it("enforces the property cap by dropping author properties, keeping context", () => {
+      const request: Record<string, string> = {};
+      for (let i = 0; i < MAX_PROPERTIES; i++) request[`p${i}`] = "v";
+      const resolved = mergeQueryMetadata({
+         request,
+         context: { queryClass: "index", package: "sales" },
+      });
+      expect(Object.keys(resolved.metadata ?? {})).toHaveLength(MAX_PROPERTIES);
+      // Context survived; the overflow came out of the author's properties.
+      expect(resolved.metadata?.class).toBe("index");
+      expect(resolved.metadata?.package).toBe("sales");
+      expect(resolved.drops.map((d) => d.reason)).toContain("property_cap");
+   });
+
+   it("keeps the serialized bag inside Snowflake's tag limit", () => {
+      // db-snowflake slices an over-long JSON tag, which leaves it unparseable —
+      // so whole properties come out here instead.
+      const request: Record<string, string> = {};
+      for (let i = 0; i < 12; i++) {
+         request[`p${i}`] = "x".repeat(MAX_PROPERTY_VALUE_LENGTH);
+      }
+      const resolved = mergeQueryMetadata({
+         request,
+         context: { queryClass: "interactive" },
+      });
+      expect(JSON.stringify(resolved.metadata).length).toBeLessThanOrEqual(
+         2000,
+      );
+      expect(resolved.drops.map((d) => d.reason)).toContain("serialized_cap");
+      expect(resolved.metadata?.class).toBe("interactive");
+   });
+
+   it("attaches nothing by default: the feature ships dark", () => {
+      // The release default. Every statement leaves exactly as Malloy compiled
+      // it until a deployment opts in, because this is the one feature that
+      // touches all of them — and on the comment-carrying backends it changes
+      // the statement text.
+      delete process.env.PUBLISHER_QUERY_METADATA;
+      expect(
+         mergeQueryMetadata({
+            request: { team: "finance" },
+            context: { queryClass: "interactive", correlationId: "corr-1" },
+         }),
+      ).toEqual({ drops: [] });
+   });
+
+   it("attaches nothing when PUBLISHER_QUERY_METADATA=off", () => {
+      process.env.PUBLISHER_QUERY_METADATA = "off";
+      expect(
+         mergeQueryMetadata({
+            request: { team: "finance" },
+            context: { queryClass: "interactive", package: "sales" },
+         }),
+      ).toEqual({ drops: [] });
+   });
+});
+
+describe("parseSuppliedQueryMetadata", () => {
+   it("returns the bag when it conforms, undefined when empty", () => {
+      expect(parseSuppliedQueryMetadata({ team: "finance" })).toEqual({
+         team: "finance",
+      });
+      expect(parseSuppliedQueryMetadata({})).toBeUndefined();
+      expect(parseSuppliedQueryMetadata(undefined)).toBeUndefined();
+   });
+
+   it("throws listing every violation, for the caller's 400", () => {
+      expect(() =>
+         parseSuppliedQueryMetadata({ "team.name": "finance", note: 'a"b' }),
+      ).toThrow(/team.name.*note|note.*team.name/s);
+   });
+});
+
+describe("parseQueryClass", () => {
+   it("accepts the four classes and passes through absence", () => {
+      expect(parseQueryClass("materialize")).toBe("materialize");
+      expect(parseQueryClass(undefined)).toBeUndefined();
+      expect(parseQueryClass(null)).toBeUndefined();
+   });
+
+   it("throws on an unrecognized class rather than ignoring it", () => {
+      expect(() => parseQueryClass("backfill")).toThrow(/queryClass/);
+      expect(() => parseQueryClass(7)).toThrow(/queryClass/);
+   });
+});