@malloy-publisher/server 0.0.212 → 0.0.214

package/src/query_timeout.ts

@@ -1,4 +1,5 @@
-import { metrics, type Counter } from "@opentelemetry/api";
+import { type Counter } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
 
 import { getQueryTimeoutMs } from "./config";
 import { QueryTimeoutError } from "./errors";
@@ -28,7 +29,7 @@ function ensureTimeoutTelemetry(): Counter {
    if (queryTimeoutCounter && timeoutTelemetryInitialized) {
       return queryTimeoutCounter;
    }
-   const meter = metrics.getMeter("publisher");
+   const meter = publisherMeter();
    if (!queryTimeoutCounter) {
       queryTimeoutCounter = meter.createCounter(
          "publisher_query_timeout_total",

package/src/server.ts

@@ -147,9 +147,7 @@ function parseArgs() {
    // this — the user told us where to look. Skip in NODE_ENV=test as a
    // belt-and-suspenders so any spec that ends up evaluating this
    // module doesn't accidentally pin the EnvironmentStore to the
-   // bundled malloy-samples config; query-param helpers have been
-   // moved to `./query_param_utils` precisely so unit specs no longer
-   // need to import this module at all.
+   // bundled malloy-samples config.
    if (!sawServerRoot && !sawConfig && process.env.NODE_ENV !== "test") {
       process.env.PUBLISHER_USE_BUNDLED_DEFAULT = "true";
    }
@@ -688,12 +686,12 @@ app.post(`${API_PREFIX}/watch-mode/stop`, watchModeController.stopWatchMode);
 // opt-in (`--watch-env <name>` CLI flag, or `POST /api/v0/watch-mode/start`).
 // Instead it reports whether watch mode is currently active for the requested
 // env via a `mode` event and, if so, fans out file-change events to the
-// browser. This avoids two earlier bugs:
-//   - Auto-starting from the request handler made arbitrary fetches reach
-//     in to mutate global watch-mode state (`event traversal — see below).
-//   - The runtime previously had no way to know "watch mode isn't running,
-//     don't expect reloads"; with the `mode` event it can choose to surface
-//     a small dev indicator (today: silent).
+// browser. This avoids two failure modes:
+//   - Auto-starting from the request handler would let arbitrary fetches
+//     reach in to mutate global watch-mode state.
+//   - Without the `mode` event the client cannot tell "watch mode isn't
+//     running, don't expect reloads"; with it the client can choose to
+//     surface a small dev indicator (today: silent).
 //
 // Inputs are validated before any state lookup. Names that don't pass the
 // canonical `assertSafePackageName` allowlist get 400 — preventing requests

package/src/service/build_plan.ts

@@ -103,10 +103,10 @@ export function flattenDependsOn(node: {
  * <p>Malloy's {@code getBuildPlan()} puts only the <em>root</em> persist sources
  * (the terminals nothing else consumes) in {@code graph.nodes}; every transitive
  * persist dependency is nested under a root in its recursive {@code dependsOn}
- * tree (and present in {@code sources}). Walking only {@code graph.nodes} —
- * which this used to do — therefore silently skips every intermediate persist
- * source, so it never gets materialized (it only got a table by coincidence when
- * it shared a buildId with a root). We post-order DFS the {@code dependsOn} tree
+ * tree (and present in {@code sources}). Walking only {@code graph.nodes}
+ * silently skips every intermediate persist source, so it never gets
+ * materialized (it only gets a table by coincidence when it shares a buildId
+ * with a root). We post-order DFS the {@code dependsOn} tree
  * so dependencies are built first (a downstream build can then read its upstream
  * source's freshly materialized table), deduplicating shared (diamond)
  * dependencies by sourceID so each is yielded once. This mirrors the canonical

package/src/service/connection_config.ts

@@ -109,10 +109,10 @@ export function normalizeSnowflakePrivateKey(privateKey: string): string {
 // allowedDirectories, setupSQL, etc.). It is NOT a filesystem isolation
 // boundary: attachedDatabases[].path is not normalized or constrained to stay
 // under the environment root, and DuckDB's local-file access is unchanged.
-// Adversarial filesystem isolation is explicit non-goal of the MalloyConfig
-// adoption — see PR #682 release notes ("DuckDB hardening knobs are not
-// exposed", "no adversarial DuckDB filesystem isolation"). Future work owns
-// any path-traversal/allowlist enforcement.
+// Adversarial filesystem isolation is an explicit non-goal here: DuckDB
+// hardening knobs are not exposed and there is no adversarial DuckDB
+// filesystem isolation. Future work owns any path-traversal/allowlist
+// enforcement.
 export function validateDuckdbApiSurface(connection: ApiConnection): void {
    if (connection.type !== "duckdb" || !connection.duckdbConnection) return;
 

package/src/service/db_utils.spec.ts

@@ -7,8 +7,16 @@ mock.module("@azure/identity", () => ({
 mock.module("@azure/storage-blob", () => ({
    ContainerClient: class {},
 }));
+// Records bigquery.dataset() calls so tests can assert how a (possibly
+// project-qualified) schema name is split into datasetId + projectId.
+const bqDatasetCalls: Array<{ id: string; options?: unknown }> = [];
 mock.module("@google-cloud/bigquery", () => ({
-   BigQuery: class {},
+   BigQuery: class {
+      dataset(id: string, options?: unknown) {
+         bqDatasetCalls.push({ id, options });
+         return { getTables: async () => [[]] };
+      }
+   },
 }));
 
 import { Connection } from "@malloydata/malloy";
@@ -1031,3 +1039,47 @@ describe("publisher proxy introspection", () => {
       );
    });
 });
+
+// ---------------------------------------------------------------------------
+// listTablesForSchema — bigquery (project-qualified dataset)
+// ---------------------------------------------------------------------------
+describe("listTablesForSchema bigquery", () => {
+   const bqConnection = {
+      name: "bq",
+      type: "bigquery",
+      bigqueryConnection: {
+         defaultProjectId: "default-proj",
+         serviceAccountKeyJson: JSON.stringify({ project_id: "default-proj" }),
+      },
+   } as unknown as ApiConnection;
+   const malloyConn = {} as unknown as Connection;
+
+   it("splits a project-qualified schema into a bare dataset id + projectId", async () => {
+      bqDatasetCalls.length = 0;
+      await listTablesForSchema(bqConnection, "myproj.myds", malloyConn);
+      expect(bqDatasetCalls).toHaveLength(1);
+      expect(bqDatasetCalls[0]?.id).toBe("myds");
+      expect(bqDatasetCalls[0]?.options).toEqual({ projectId: "myproj" });
+   });
+
+   it("splits on the last dot so domain-scoped project ids survive", async () => {
+      bqDatasetCalls.length = 0;
+      await listTablesForSchema(
+         bqConnection,
+         "domain.com:proj.myds",
+         malloyConn,
+      );
+      expect(bqDatasetCalls[0]?.id).toBe("myds");
+      expect(bqDatasetCalls[0]?.options).toEqual({
+         projectId: "domain.com:proj",
+      });
+   });
+
+   it("passes a bare dataset name through unqualified", async () => {
+      bqDatasetCalls.length = 0;
+      await listTablesForSchema(bqConnection, "myds", malloyConn);
+      expect(bqDatasetCalls).toHaveLength(1);
+      expect(bqDatasetCalls[0]?.id).toBe("myds");
+      expect(bqDatasetCalls[0]?.options).toBeUndefined();
+   });
+});

package/src/service/db_utils.ts

@@ -1077,7 +1077,20 @@ async function listTablesForBigQuery(
 ): Promise<ApiTable[]> {
    try {
       const bigquery = createBigQueryClient(connection);
-      const dataset = bigquery.dataset(schemaName);
+      // A 3-segment table reference ("project.dataset.table") reaches here with a
+      // project-qualified schema ("project.dataset"). bigquery.dataset() takes a
+      // BARE dataset id plus an optional projectId, so passing "project.dataset" as
+      // the id resolves to a non-existent dataset in the client's default project —
+      // the dataset's tables never list, so the orphan sweep can't see (and reclaim)
+      // those tables. Split the project off the last dot. (Domain-scoped project ids
+      // like "domain.com:project" keep their dots/colon since we split on the last.)
+      const lastDot = schemaName.lastIndexOf(".");
+      const dataset =
+         lastDot === -1
+            ? bigquery.dataset(schemaName)
+            : bigquery.dataset(schemaName.slice(lastDot + 1), {
+                 projectId: schemaName.slice(0, lastDot),
+              });
       const [tables] = await dataset.getTables();
 
       let names = tables

package/src/service/environment.ts

@@ -1,6 +1,6 @@
 import type { GivenValue, LogMessage } from "@malloydata/malloy";
 import { MalloyError, Runtime } from "@malloydata/malloy";
-import { metrics } from "@opentelemetry/api";
+import { publisherMeter } from "../telemetry";
 import { Mutex } from "async-mutex";
 import crypto from "crypto";
 import * as fs from "fs";
@@ -97,24 +97,26 @@ let queryAdmissionRejectionsCounter: Counter | null = null;
 let packageAdmissionRejectionsCounter: Counter | null = null;
 function getQueryAdmissionRejectionsCounter(): Counter {
    if (queryAdmissionRejectionsCounter) return queryAdmissionRejectionsCounter;
-   queryAdmissionRejectionsCounter = metrics
-      .getMeter("publisher")
-      .createCounter("publisher_query_admission_rejections_total", {
+   queryAdmissionRejectionsCounter = publisherMeter().createCounter(
+      "publisher_query_admission_rejections_total",
+      {
          description:
             "Queries rejected with 503 because Environment.assertCanAdmitQuery() observed memory back-pressure",
-      });
+      },
+   );
    return queryAdmissionRejectionsCounter;
 }
 function getPackageAdmissionRejectionsCounter(): Counter {
    if (packageAdmissionRejectionsCounter) {
       return packageAdmissionRejectionsCounter;
    }
-   packageAdmissionRejectionsCounter = metrics
-      .getMeter("publisher")
-      .createCounter("publisher_package_admission_rejections_total", {
+   packageAdmissionRejectionsCounter = publisherMeter().createCounter(
+      "publisher_package_admission_rejections_total",
+      {
          description:
             "Package loads rejected with 503 because Environment.assertCanAdmitNewPackage() observed memory back-pressure",
-      });
+      },
+   );
    return packageAdmissionRejectionsCounter;
 }
 

package/src/service/model.ts

@@ -20,7 +20,7 @@ import {
    MalloySQLStatementType,
 } from "@malloydata/malloy-sql";
 import { DataStyles } from "@malloydata/render";
-import { metrics } from "@opentelemetry/api";
+import { publisherMeter } from "../telemetry";
 import * as fs from "fs/promises";
 import { createRequire } from "module";
 import * as path from "path";
@@ -66,6 +66,7 @@ import {
    assertWithinModelResponseLimits,
    resolveModelQueryRowLimit,
 } from "./model_limits";
+import { buildSourceAliasMap, extractRunTargetSourceName } from "./query_text";
 import {
    extractQueriesFromModelDef,
    extractSourcesFromModelDef,
@@ -151,7 +152,7 @@ export class Model {
       exploresDeclared: boolean;
       isQueryEntryPoint: boolean;
    } = { mode: "all", exploresDeclared: false, isQueryEntryPoint: true };
-   private meter = metrics.getMeter("publisher");
+   private meter = publisherMeter();
    private queryExecutionHistogram = this.meter.createHistogram(
       "malloy_model_query_duration",
       {
@@ -330,7 +331,8 @@ export class Model {
 
    /**
     * Gate ad-hoc compile/query text by the named source it targets. Resolves the
-    * source from surface syntax (`extractSourceName`) and applies the gate. An
+    * source from surface syntax (`extractRunTargetSourceName`) and applies the
+    * gate. An
     * unnamed/inline source resolves to `undefined`, so only the model-wide
     * file-level gate applies — the same top-level-only boundary as the query
     * path's early gate. Used by the `/compile` path, which has no runnable to
@@ -340,7 +342,7 @@ export class Model {
       text: string,
       givens: Record<string, GivenValue>,
    ): Promise<void> {
-      await this.assertAuthorized(this.extractSourceName(text), givens);
+      await this.assertAuthorized(extractRunTargetSourceName(text), givens);
    }
 
    /**
@@ -390,21 +392,6 @@ export class Model {
     * Best-effort extraction of a source name from an ad-hoc Malloy query string.
     * Matches patterns like `run: source_name -> ...` or `source_name -> ...`.
     */
-   private extractSourceName(query?: string): string | undefined {
-      if (!query) return undefined;
-      // Match a bare `\w+` identifier or a backtick-quoted Malloy identifier
-      // (e.g. `gated-source`, which needs quoting for the hyphen). Quoted names
-      // must be recognized here too, or the early schema-oracle gate would miss
-      // a gated source with a quoted name and let a denied caller probe its
-      // columns via a pre-compilation field error. The quoted capture returns
-      // the inner name (no backticks), matching how sources are keyed.
-      const runMatch = query.match(/run\s*:\s*(?:`([^`]+)`|(\w+))\s*->/);
-      const arrowMatch = query.match(/^\s*(?:`([^`]+)`|(\w+))\s*->/m);
-      return (
-         runMatch?.[1] ?? runMatch?.[2] ?? arrowMatch?.[1] ?? arrowMatch?.[2]
-      );
-   }
-
    /**
     * Resolve the run target of an ad-hoc query to the model-defined source
     * whose filters apply, following source-derivation declarations so that a
@@ -414,10 +401,10 @@ export class Model {
     * from a protected source.
     */
    private resolveFilterSource(query?: string): string | undefined {
-      const target = this.extractSourceName(query);
+      const target = extractRunTargetSourceName(query);
       if (!target || !query) return undefined;
 
-      const aliasOf = Model.buildAliasMap(query);
+      const aliasOf = buildSourceAliasMap(query);
 
       // Walk the derivation chain until we hit a protected source or run out.
       let current: string | undefined = target;
@@ -856,7 +843,7 @@ export class Model {
       // schema. Everything else (inline derivations, multi-statement, forms
       // the regex can't read) defers to the compiled backstop.
       if (query) {
-         const target = this.extractSourceName(query);
+         const target = extractRunTargetSourceName(query);
          if (
             target &&
             !curatedSources.has(target) &&
@@ -935,7 +922,7 @@ export class Model {
     *  queryable source is itself queryable. */
    private derivesFromCurated(name: string, query: string): boolean {
       const curated = this.curatedSourceNames();
-      const aliasOf = Model.buildAliasMap(query);
+      const aliasOf = buildSourceAliasMap(query);
       let current: string | undefined = name;
       const seen = new Set<string>();
       while (current && !seen.has(current)) {
@@ -946,27 +933,6 @@ export class Model {
       return false;
    }
 
-   /** Map each ad-hoc source alias to the base it derives from
-    *  (`source: NAME is BASE …` → NAME → BASE). Shared by filter inheritance
-    *  ({@link resolveFilterSource}) and the query boundary, which both walk
-    *  derivation chains in caller-authored query text. */
-   private static buildAliasMap(query: string): Map<string, string> {
-      const aliasOf = new Map<string, string>();
-      // Match a bare `\w+` or a backtick-quoted Malloy identifier on BOTH sides
-      // (a hyphenated source like `customer-orders` needs quoting), same pattern
-      // as `extractSourceName`. The quoted capture returns the inner name (no
-      // backticks), keeping aliases keyed the way `curatedSourceNames()` and the
-      // compiled run target are — otherwise a derivation over a quoted source
-      // wouldn't walk back to the curated set and would be falsely denied.
-      const declRe =
-         /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
-      let match: RegExpExecArray | null;
-      while ((match = declRe.exec(query)) !== null) {
-         aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
-      }
-      return aliasOf;
-   }
-
    /**
     * Compile-time renderer-tag validation, run on the main thread.
     *
@@ -1157,7 +1123,7 @@ export class Model {
          (queryName
             ? this.queries?.find((q) => q.name === queryName)?.sourceName
             : undefined) ||
-         this.extractSourceName(query);
+         extractRunTargetSourceName(query);
       if (earlySource) {
          await this.assertAuthorized(earlySource, givens ?? {});
       }
@@ -1511,7 +1477,7 @@ export class Model {
 
             // If filters need to be applied, rebuild the query with a refinement
             if (!bypassFilters && cell.modelMaterializer) {
-               const effectiveSource = this.extractSourceName(cell.text);
+               const effectiveSource = extractRunTargetSourceName(cell.text);
                if (effectiveSource) {
                   const filters = this.getFilters(effectiveSource);
                   if (filters.length > 0) {

package/src/service/package.ts

@@ -12,7 +12,7 @@ import {
    MalloyError,
    SourceDef,
 } from "@malloydata/malloy";
-import { metrics } from "@opentelemetry/api";
+import { publisherMeter } from "../telemetry";
 import recursive from "recursive-readdir";
 import { components } from "../api";
 import { getPackageLoadPool } from "../package_load/package_load_pool";
@@ -77,7 +77,7 @@ export class Package {
    // no persist source. Surfaced read-only on getPackageMetadata() so a caller
    // can derive build instructions without a separate plan round-trip.
    private buildPlan: BuildPlan | null = null;
-   private static meter = metrics.getMeter("publisher");
+   private static meter = publisherMeter();
    private static packageLoadHistogram = this.meter.createHistogram(
       "malloy_package_load_duration",
       {
@@ -331,6 +331,7 @@ export class Package {
          explores: outcome.packageMetadata.explores,
          queryableSources: outcome.packageMetadata.queryableSources,
          manifestLocation: outcome.packageMetadata.manifestLocation ?? null,
+         materialization: outcome.packageMetadata.materialization ?? null,
       };
 
       // Build live `Model`s from worker output. Any per-model compile

package/src/service/package_manifest.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "bun:test";
+import { parsePackageMaterialization } from "./package_manifest";
+
+describe("service/package_manifest", () => {
+   describe("parsePackageMaterialization", () => {
+      it("extracts a string schedule", () => {
+         expect(parsePackageMaterialization({ schedule: "0 6 * * *" })).toEqual(
+            { schedule: "0 6 * * *" },
+         );
+      });
+
+      it("returns null when the block is absent", () => {
+         expect(parsePackageMaterialization(undefined)).toBeNull();
+         expect(parsePackageMaterialization(null)).toBeNull();
+      });
+
+      it("ignores extra/unknown fields", () => {
+         expect(
+            parsePackageMaterialization({
+               schedule: "*/15 * * * *",
+               freshness: { window: "24h" },
+            }),
+         ).toEqual({ schedule: "*/15 * * * *" });
+      });
+
+      it("degrades a non-string schedule to null", () => {
+         expect(parsePackageMaterialization({ schedule: 42 })).toEqual({
+            schedule: null,
+         });
+         expect(parsePackageMaterialization({})).toEqual({ schedule: null });
+      });
+
+      it("returns null for non-object input", () => {
+         expect(parsePackageMaterialization("0 6 * * *")).toBeNull();
+         expect(parsePackageMaterialization(7)).toBeNull();
+      });
+   });
+});

package/src/service/package_manifest.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure parsing of the package manifest's (publisher.json) `materialization`
+ * block. Kept side-effect free (no fs, no worker bootstrap) so it is unit
+ * testable in isolation from the package-load worker that consumes it.
+ */
+
+export interface PackageMaterializationConfig {
+   /**
+    * 5-field UNIX cron the control plane uses to schedule version-level
+    * re-materialization. Null when absent or not a string.
+    */
+   schedule: string | null;
+}
+
+/**
+ * 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.
+ */
+export function parsePackageMaterialization(
+   raw: unknown,
+): PackageMaterializationConfig | null {
+   if (!raw || typeof raw !== "object") {
+      return null;
+   }
+   const schedule = (raw as { schedule?: unknown }).schedule;
+   return { schedule: typeof schedule === "string" ? schedule : null };
+}

package/src/service/package_memory_governor.ts

@@ -1,4 +1,4 @@
-import { metrics } from "@opentelemetry/api";
+import { publisherMeter } from "../telemetry";
 
 import type { MemoryGovernorConfig } from "../config";
 import { logger } from "../logger";
@@ -58,7 +58,7 @@ export class PackageMemoryGovernor {
    private lastSampledRss = 0;
    private lastSampledAt: number | null = null;
    private readonly backpressureActivationsCounter: ReturnType<
-      ReturnType<typeof metrics.getMeter>["createCounter"]
+      ReturnType<typeof publisherMeter>["createCounter"]
    >;
 
    constructor(config: MemoryGovernorConfig, rssSampler?: RssSampler) {
@@ -71,7 +71,7 @@ export class PackageMemoryGovernor {
          config.maxMemoryBytes * config.lowWaterFraction,
       );
 
-      const meter = metrics.getMeter("publisher");
+      const meter = publisherMeter();
 
       // Periodic gauge: current process RSS in bytes.
       meter

package/src/service/query_text.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "bun:test";
+import { buildSourceAliasMap, extractRunTargetSourceName } from "./query_text";
+
+describe("service/query_text", () => {
+   describe("extractRunTargetSourceName", () => {
+      it("returns undefined for empty/absent text", () => {
+         expect(extractRunTargetSourceName(undefined)).toBeUndefined();
+         expect(extractRunTargetSourceName("")).toBeUndefined();
+      });
+
+      it("reads the source from a `run:` query", () => {
+         expect(extractRunTargetSourceName("run: flights -> { ... }")).toBe(
+            "flights",
+         );
+      });
+
+      it("reads the source from a bare `source -> view` query", () => {
+         expect(extractRunTargetSourceName("flights -> by_carrier")).toBe(
+            "flights",
+         );
+      });
+
+      it("unwraps a backtick-quoted (e.g. hyphenated) source name", () => {
+         expect(
+            extractRunTargetSourceName("run: `customer-orders` -> { ... }"),
+         ).toBe("customer-orders");
+         expect(extractRunTargetSourceName("`gated-source` -> view")).toBe(
+            "gated-source",
+         );
+      });
+
+      it("prefers the `run:` target over a leading arrow line", () => {
+         expect(
+            extractRunTargetSourceName("run: flights -> { aggregate: c }"),
+         ).toBe("flights");
+      });
+
+      it("returns undefined when there is no run target", () => {
+         expect(
+            extractRunTargetSourceName("source: x is y + { dimension: a }"),
+         ).toBeUndefined();
+      });
+   });
+
+   describe("buildSourceAliasMap", () => {
+      it("maps a single derivation declaration", () => {
+         expect(buildSourceAliasMap("source: a is b")).toEqual(
+            new Map([["a", "b"]]),
+         );
+      });
+
+      it("maps multiple declarations", () => {
+         const map = buildSourceAliasMap(
+            "source: a is b\nsource: c is d\nrun: a -> view",
+         );
+         expect(map.get("a")).toBe("b");
+         expect(map.get("c")).toBe("d");
+      });
+
+      it("unwraps backticks on either side of `is`", () => {
+         const map = buildSourceAliasMap(
+            "source: `my-alias` is `customer-orders`",
+         );
+         expect(map.get("my-alias")).toBe("customer-orders");
+      });
+
+      it("keeps the last declaration when an alias is redefined", () => {
+         expect(buildSourceAliasMap("source: a is b\nsource: a is c")).toEqual(
+            new Map([["a", "c"]]),
+         );
+      });
+
+      it("returns an empty map when no declarations are present", () => {
+         expect(buildSourceAliasMap("run: flights -> by_carrier")).toEqual(
+            new Map(),
+         );
+      });
+   });
+});

package/src/service/query_text.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure parsing of caller-authored Malloy query text.
+ *
+ * The authorization gate, filter inheritance, and the query boundary all need
+ * to identify the run target and follow `source: NAME is BASE` derivation
+ * chains *before* the query compiles — a denied caller must never reach
+ * compilation. These helpers are deliberately side-effect free (no model
+ * state) so the regexes that back those security checks can be unit tested in
+ * isolation from the stateful `Model`.
+ *
+ * Both helpers recognize a bare `\w+` identifier and a backtick-quoted Malloy
+ * identifier (e.g. `customer-orders`, which needs quoting for the hyphen), and
+ * return the inner name without backticks so callers can key it the same way
+ * sources are keyed.
+ */
+
+/**
+ * The top-level source a `run:` / `->` query targets, or undefined when the
+ * text has no recognizable run target.
+ */
+export function extractRunTargetSourceName(query?: string): string | undefined {
+   if (!query) return undefined;
+   const runMatch = query.match(/run\s*:\s*(?:`([^`]+)`|(\w+))\s*->/);
+   const arrowMatch = query.match(/^\s*(?:`([^`]+)`|(\w+))\s*->/m);
+   return runMatch?.[1] ?? runMatch?.[2] ?? arrowMatch?.[1] ?? arrowMatch?.[2];
+}
+
+/**
+ * Map each ad-hoc source alias to the base it derives from
+ * (`source: NAME is BASE …` → NAME → BASE). Used to walk derivation chains in
+ * caller-authored text for both filter inheritance and the query boundary —
+ * composition over a queryable source is itself queryable.
+ */
+export function buildSourceAliasMap(query: string): Map<string, string> {
+   const aliasOf = new Map<string, string>();
+   const declRe =
+      /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
+   let match: RegExpExecArray | null;
+   while ((match = declRe.exec(query)) !== null) {
+      aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
+   }
+   return aliasOf;
+}

package/src/service/source_extraction.ts

@@ -5,10 +5,9 @@
  * package-load worker (`package_load/package_load_worker.ts`, which runs in a
  * separate bundle and serializes the result over the worker protocol) need to
  * walk a `ModelDef` and produce the same `sources` / `queries` shapes plus the
- * `#(filter)` `filterMap`. These two call sites used to carry byte-for-byte
- * copies of this logic; keeping them in lockstep by hand was a standing hazard
- * (a change to one silently diverged from the other). This module is the single
- * source of truth — the two callers differ only in how they type the result
+ * `#(filter)` `filterMap`. This module is the single source of truth for that
+ * walk so the two call sites can't drift out of lockstep — the two callers
+ * differ only in how they type the result
  * (generated API types vs. worker wire types — structurally identical, so each
  * casts at its boundary) and in how they report a filter parse failure (the
  * service logs a warning; the worker has no logger and stays silent), which is

package/src/telemetry.ts

@@ -0,0 +1,20 @@
+import { metrics, type Meter } from "@opentelemetry/api";
+
+/**
+ * Single source of truth for the OpenTelemetry meter name. Every
+ * publisher-emitted metric registers under this name so a typo can't
+ * silently split a metric onto a second meter and drop it from the
+ * Prometheus scrape.
+ */
+export const METER_NAME = "publisher";
+
+/**
+ * The shared publisher meter. Resolves lazily through the OTel global
+ * provider (a `ProxyMeter`), so modules may call this at import time;
+ * the real provider can be installed afterward (the production SDK in
+ * `instrumentation.ts`, or the in-memory test harness) and instruments
+ * still route to it.
+ */
+export function publisherMeter(): Meter {
+   return metrics.getMeter(METER_NAME);
+}