@malloy-publisher/server 0.0.213 → 0.0.214

package/dist/app/api-doc.yaml

@@ -2436,6 +2436,14 @@ components:
             URI (gs:// or s3://) of the externally-computed manifest for this package.
             On (re)load the publisher reads it and binds persist references
             (buildId -> physicalTableName). Null = serve live.
+        materialization:
+          oneOf:
+            - $ref: "#/components/schemas/PackageMaterializationConfig"
+            - type: "null"
+          description: |
+            Package-level Malloy Persistence policy declared in
+            malloy-publisher.json. The control plane reads it to drive scheduled
+            re-materialization. Null/absent = no package-level policy.
         manifestBindingStatus:
           type: string
           readOnly: true
@@ -2485,6 +2493,21 @@ components:
             package is compiled; null only when the package declares no persist
             source.
 
+    PackageMaterializationConfig:
+      type: object
+      description: >-
+        Package-level Malloy Persistence policy from malloy-publisher.json's
+        `materialization` block. Surfaced verbatim so the control plane can drive
+        scheduled version-level re-materialization without re-reading the package
+        files.
+      properties:
+        schedule:
+          type: ["string", "null"]
+          description: >-
+            5-field UNIX cron controlling how often the control plane
+            re-materializes this package's published versions. Null/absent = no
+            scheduled re-materialization (publish / on-demand only).
+
     Model:
       type: object
       description: Malloy model metadata and status information

package/dist/instrumentation.mjs

@@ -115174,7 +115174,6 @@ var init_logger = __esm(() => {
 
 // src/instrumentation.ts
 init_logger();
-var import_api = __toESM(require_src(), 1);
 var import_auto_instrumentations_node = __toESM(require_src59(), 1);
 var import_exporter_logs_otlp_proto = __toESM(require_src66(), 1);
 var import_exporter_prometheus = __toESM(require_src71(), 1);
@@ -115186,6 +115185,15 @@ var import_sdk_node = __toESM(require_src106(), 1);
 var import_sdk_trace_base = __toESM(require_src82(), 1);
 var import_semantic_conventions = __toESM(require_src2(), 1);
 import { monitorEventLoopDelay } from "node:perf_hooks";
+
+// src/telemetry.ts
+var import_api = __toESM(require_src(), 1);
+var METER_NAME = "publisher";
+function publisherMeter() {
+  return import_api.metrics.getMeter(METER_NAME);
+}
+
+// src/instrumentation.ts
 var prometheusExporter = null;
 var sdk = null;
 function getPrometheusMetricsHandler() {
@@ -115243,7 +115251,7 @@ function instrument() {
   }
 }
 instrument();
-var meter = import_api.metrics.getMeter("publisher");
+var meter = publisherMeter();
 var httpRequestDuration = meter.createHistogram("http_server_request_duration_ms", {
   description: "Duration of HTTP requests in milliseconds",
   unit: "ms",

package/dist/package_load_worker.mjs

@@ -11712,6 +11712,15 @@ function unwrapQuotedExpression(body) {
   return expr;
 }
 
+// src/service/package_manifest.ts
+function parsePackageMaterialization(raw) {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const schedule = raw.schedule;
+  return { schedule: typeof schedule === "string" ? schedule : null };
+}
+
 // src/service/source_extraction.ts
 import {
   isSourceDef
@@ -12235,7 +12244,8 @@ async function readPackageMetadata(packagePath) {
     description: parsed.description,
     explores: Array.isArray(parsed.explores) ? parsed.explores.map(normalizeModelPath) : undefined,
     queryableSources: parsed.queryableSources === "all" ? "all" : "declared",
-    manifestLocation: typeof parsed.manifestLocation === "string" ? parsed.manifestLocation : null
+    manifestLocation: typeof parsed.manifestLocation === "string" ? parsed.manifestLocation : null,
+    materialization: parsePackageMaterialization(parsed.materialization)
   };
 }
 async function listPackageFiles(packagePath) {

package/dist/server.mjs

@@ -218980,7 +218980,6 @@ var require_lunr = __commonJS((exports, module) => {
 
 // src/instrumentation.ts
 init_logger();
-var import_api = __toESM(require_src(), 1);
 var import_auto_instrumentations_node = __toESM(require_src59(), 1);
 var import_exporter_logs_otlp_proto = __toESM(require_src66(), 1);
 var import_exporter_prometheus = __toESM(require_src71(), 1);
@@ -218992,6 +218991,15 @@ var import_sdk_node = __toESM(require_src106(), 1);
 var import_sdk_trace_base = __toESM(require_src82(), 1);
 var import_semantic_conventions = __toESM(require_src2(), 1);
 import { monitorEventLoopDelay } from "node:perf_hooks";
+
+// src/telemetry.ts
+var import_api = __toESM(require_src(), 1);
+var METER_NAME = "publisher";
+function publisherMeter() {
+  return import_api.metrics.getMeter(METER_NAME);
+}
+
+// src/instrumentation.ts
 var prometheusExporter = null;
 var sdk = null;
 function getPrometheusMetricsHandler() {
@@ -219049,7 +219057,7 @@ function instrument() {
   }
 }
 instrument();
-var meter = import_api.metrics.getMeter("publisher");
+var meter = publisherMeter();
 var httpRequestDuration = meter.createHistogram("http_server_request_duration_ms", {
   description: "Duration of HTTP requests in milliseconds",
   unit: "ms",
@@ -224473,14 +224481,13 @@ var getProcessedPublisherConfig = (serverRoot) => {
 init_errors();
 
 // src/query_cap_metrics.ts
-var import_api2 = __toESM(require_src(), 1);
 var capExceededCounter = null;
 var configGaugesInstalled = false;
 function ensureCapTelemetry() {
   if (capExceededCounter && configGaugesInstalled) {
     return capExceededCounter;
   }
-  const meter2 = import_api2.metrics.getMeter("publisher");
+  const meter2 = publisherMeter();
   if (!capExceededCounter) {
     capExceededCounter = meter2.createCounter("publisher_query_cap_exceeded_total", {
       description: "Queries rejected with 413 because the row or byte cap was exceeded. Labels: cap_type ('rows'|'bytes'), source ('connection_sql'|'model_query'|'notebook_cell')."
@@ -224518,7 +224525,6 @@ function recordQueryCapExceeded(capType, source) {
 init_logger();
 
 // src/query_timeout.ts
-var import_api3 = __toESM(require_src(), 1);
 init_errors();
 var queryTimeoutCounter = null;
 var timeoutTelemetryInitialized = false;
@@ -224526,7 +224532,7 @@ function ensureTimeoutTelemetry() {
   if (queryTimeoutCounter && timeoutTelemetryInitialized) {
     return queryTimeoutCounter;
   }
-  const meter2 = import_api3.metrics.getMeter("publisher");
+  const meter2 = publisherMeter();
   if (!queryTimeoutCounter) {
     queryTimeoutCounter = meter2.createCounter("publisher_query_timeout_total", {
       description: "Queries aborted because PUBLISHER_QUERY_TIMEOUT_MS elapsed before the underlying SDK call completed"
@@ -237690,7 +237696,6 @@ class StorageManager {
 }
 
 // src/service/environment.ts
-var import_api7 = __toESM(require_src(), 1);
 import { MalloyError as MalloyError4, Runtime as Runtime2 } from "@malloydata/malloy";
 init_constants();
 init_errors();
@@ -237701,17 +237706,19 @@ import * as path8 from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/materialization_metrics.ts
-var import_api4 = __toESM(require_src(), 1);
 var resetHooks = [];
 function lazyCounter(name, description) {
   let instrument2 = null;
   resetHooks.push(() => instrument2 = null);
-  return () => instrument2 ??= import_api4.metrics.getMeter("publisher").createCounter(name, { description });
+  return () => instrument2 ??= publisherMeter().createCounter(name, { description });
 }
 function lazyHistogram(name, description, unit) {
   let instrument2 = null;
   resetHooks.push(() => instrument2 = null);
-  return () => instrument2 ??= import_api4.metrics.getMeter("publisher").createHistogram(name, { description, unit });
+  return () => instrument2 ??= publisherMeter().createHistogram(name, {
+    description,
+    unit
+  });
 }
 var runCounter = lazyCounter("publisher_materialization_runs_total", "Materialization builds completed. Labels: mode ('auto'|'orchestrated'), outcome ('success'|'failed'|'cancelled').");
 var runDuration = lazyHistogram("publisher_materialization_run_duration_ms", "Wall-clock duration of a materialization build. Label: mode ('auto'|'orchestrated').", "ms");
@@ -237831,12 +237838,6 @@ async function fetchManifestEntries(uri) {
 }
 
 // src/service/package.ts
-init_package_load_pool();
-init_constants();
-init_errors();
-init_logger();
-var import_api6 = __toESM(require_src(), 1);
-var import_recursive_readdir = __toESM(require_recursive_readdir(), 1);
 import * as fs6 from "fs/promises";
 import * as path7 from "path";
 import"@malloydata/db-duckdb/native";
@@ -237848,13 +237849,17 @@ import {
   MalloyConfig as MalloyConfig3,
   MalloyError as MalloyError3
 } from "@malloydata/malloy";
+init_package_load_pool();
+init_constants();
+init_errors();
+init_logger();
+var import_recursive_readdir = __toESM(require_recursive_readdir(), 1);
 
 // src/service/build_plan.ts
 init_constants();
 init_logger();
 
 // src/service/model.ts
-var import_api5 = __toESM(require_src(), 1);
 import {
   Annotations as Annotations2,
   API,
@@ -238291,6 +238296,24 @@ function assertWithinModelResponseLimits(rowCount, serializedBytes, { maxRows, m
   }
 }
 
+// src/service/query_text.ts
+function extractRunTargetSourceName(query) {
+  if (!query)
+    return;
+  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];
+}
+function buildSourceAliasMap(query) {
+  const aliasOf = new Map;
+  const declRe = /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
+  let match;
+  while ((match = declRe.exec(query)) !== null) {
+    aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
+  }
+  return aliasOf;
+}
+
 // src/service/source_extraction.ts
 import {
   isSourceDef
@@ -238393,7 +238416,7 @@ class Model {
   fileLevelAuthorize = [];
   discoveryCurationEnabled = false;
   queryBoundary = { mode: "all", exploresDeclared: false, isQueryEntryPoint: true };
-  meter = import_api5.metrics.getMeter("publisher");
+  meter = publisherMeter();
   queryExecutionHistogram = this.meter.createHistogram("malloy_model_query_duration", {
     description: "How long it takes to execute a Malloy model query",
     unit: "ms"
@@ -238466,7 +238489,7 @@ class Model {
       deny();
   }
   async assertAuthorizedForText(text, givens) {
-    await this.assertAuthorized(this.extractSourceName(text), givens);
+    await this.assertAuthorized(extractRunTargetSourceName(text), givens);
   }
   async assertAuthorizedForRunnable(runnable, givens) {
     await this.assertAuthorized(await this.resolveAuthorizeSourceFromRunnable(runnable), givens);
@@ -238484,18 +238507,11 @@ class Model {
     } catch {}
     return;
   }
-  extractSourceName(query) {
-    if (!query)
-      return;
-    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];
-  }
   resolveFilterSource(query) {
-    const target = this.extractSourceName(query);
+    const target = extractRunTargetSourceName(query);
     if (!target || !query)
       return;
-    const aliasOf = Model.buildAliasMap(query);
+    const aliasOf = buildSourceAliasMap(query);
     let current = target;
     const seen = new Set;
     while (current && !seen.has(current)) {
@@ -238658,7 +238674,7 @@ class Model {
       throw new NotQueryableError(`No queryable source "${sourceName}".`);
     }
     if (query) {
-      const target = this.extractSourceName(query);
+      const target = extractRunTargetSourceName(query);
       if (target && !curatedSources.has(target) && !this.derivesFromCurated(target, query) && this.sources?.some((s) => s.name === target)) {
         throw new NotQueryableError(`No queryable source "${target}".`);
       }
@@ -238693,7 +238709,7 @@ class Model {
   }
   derivesFromCurated(name, query) {
     const curated = this.curatedSourceNames();
-    const aliasOf = Model.buildAliasMap(query);
+    const aliasOf = buildSourceAliasMap(query);
     let current = name;
     const seen = new Set;
     while (current && !seen.has(current)) {
@@ -238704,15 +238720,6 @@ class Model {
     }
     return false;
   }
-  static buildAliasMap(query) {
-    const aliasOf = new Map;
-    const declRe = /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
-    let match;
-    while ((match = declRe.exec(query)) !== null) {
-      aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
-    }
-    return aliasOf;
-  }
   async validateRenderTags() {
     const mm = this.modelMaterializer;
     if (!mm) {
@@ -238789,7 +238796,7 @@ class Model {
     if (!this.modelMaterializer || !this.modelDef || !this.modelInfo)
       throw new BadRequestError("Model has no queryable entities.");
     const boundary = this.assertQueryBoundaryEarly(sourceName, queryName, query);
-    const earlySource = sourceName || (queryName ? this.queries?.find((q) => q.name === queryName)?.sourceName : undefined) || this.extractSourceName(query);
+    const earlySource = sourceName || (queryName ? this.queries?.find((q) => q.name === queryName)?.sourceName : undefined) || extractRunTargetSourceName(query);
     if (earlySource) {
       await this.assertAuthorized(earlySource, givens ?? {});
     }
@@ -238974,7 +238981,7 @@ run: ${sourceName ? sourceName + "->" : ""}${queryName}`;
       try {
         let runnableToExecute = cell.runnable;
         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) {
@@ -239444,7 +239451,7 @@ class Package {
   manifestEntryCount = 0;
   boundManifestUri = null;
   buildPlan = null;
-  static meter = import_api6.metrics.getMeter("publisher");
+  static meter = publisherMeter();
   static packageLoadHistogram = this.meter.createHistogram("malloy_package_load_duration", {
     description: "Time taken to load a Malloy package",
     unit: "ms"
@@ -239558,7 +239565,8 @@ class Package {
       resource: `${API_PREFIX}/environments/${environmentName}/packages/${packageName}`,
       explores: outcome.packageMetadata.explores,
       queryableSources: outcome.packageMetadata.queryableSources,
-      manifestLocation: outcome.packageMetadata.manifestLocation ?? null
+      manifestLocation: outcome.packageMetadata.manifestLocation ?? null,
+      materialization: outcome.packageMetadata.materialization ?? null
     };
     const models = new Map;
     for (const sm of outcome.models) {
@@ -239922,7 +239930,7 @@ var packageAdmissionRejectionsCounter = null;
 function getQueryAdmissionRejectionsCounter() {
   if (queryAdmissionRejectionsCounter)
     return queryAdmissionRejectionsCounter;
-  queryAdmissionRejectionsCounter = import_api7.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;
@@ -239931,7 +239939,7 @@ function getPackageAdmissionRejectionsCounter() {
   if (packageAdmissionRejectionsCounter) {
     return packageAdmissionRejectionsCounter;
   }
-  packageAdmissionRejectionsCounter = import_api7.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;
@@ -241856,14 +241864,13 @@ var setFilterDeprecationHeaders = (res, options) => {
 
 // src/heap_check.ts
 init_logger();
-var import_api8 = __toESM(require_src(), 1);
 import * as v8 from "v8";
 var heapGaugesInstalled = false;
 function installHeapGauges() {
   if (heapGaugesInstalled)
     return;
   heapGaugesInstalled = true;
-  const meter2 = import_api8.metrics.getMeter("publisher");
+  const meter2 = publisherMeter();
   meter2.createObservableGauge("publisher_heap_size_limit_bytes", {
     description: "V8 heap_size_limit (--max-old-space-size). Compare with PUBLISHER_MAX_MEMORY_BYTES.",
     unit: "By"
@@ -241898,7 +241905,6 @@ function checkHeapConfiguration(options = {}) {
 }
 
 // src/query_concurrency.ts
-var import_api9 = __toESM(require_src(), 1);
 init_errors();
 init_logger();
 var active = 0;
@@ -241908,7 +241914,7 @@ function ensureConcurrencyTelemetry() {
   if (queryConcurrencyRejectionsCounter && concurrencyTelemetryInitialized) {
     return queryConcurrencyRejectionsCounter;
   }
-  const meter2 = import_api9.metrics.getMeter("publisher");
+  const meter2 = publisherMeter();
   queryConcurrencyRejectionsCounter = meter2.createCounter("publisher_query_concurrency_rejections_total", {
     description: "Queries rejected with 503 because the per-pod PUBLISHER_MAX_CONCURRENT_QUERIES cap was reached"
   });
@@ -249057,7 +249063,6 @@ class MaterializationService {
 
 // src/service/package_memory_governor.ts
 init_logger();
-var import_api10 = __toESM(require_src(), 1);
 var DEFAULT_RSS_SAMPLER = () => process.memoryUsage().rss;
 
 class PackageMemoryGovernor {
@@ -249075,7 +249080,7 @@ class PackageMemoryGovernor {
     this.rssSampler = rssSampler ?? DEFAULT_RSS_SAMPLER;
     this.highWaterBytes = Math.floor(config.maxMemoryBytes * config.highWaterFraction);
     this.lowWaterBytes = Math.floor(config.maxMemoryBytes * config.lowWaterFraction);
-    const meter2 = import_api10.metrics.getMeter("publisher");
+    const meter2 = publisherMeter();
     meter2.createObservableGauge("publisher_process_rss_bytes", {
       description: "Current resident set size of the publisher process in bytes",
       unit: "By"

package/package.json

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

package/src/controller/package.controller.ts

@@ -195,9 +195,9 @@ export class PackageController {
 
    /**
     * Run the right downloader for the given location into `targetPath`.
-    * This used to point at the canonical package directory, but the
-    * install pipeline now passes a sibling staging dir so the long-running
-    * download doesn't hold the per-package mutex.
+    * Callers pass a sibling staging dir (not the canonical package
+    * directory) so the long-running download doesn't hold the per-package
+    * mutex.
     */
    private async downloadInto(
       environmentName: string,

package/src/heap_check.ts

@@ -1,4 +1,4 @@
-import { metrics } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
 import * as v8 from "v8";
 
 import { logger } from "./logger";
@@ -32,7 +32,7 @@ let heapGaugesInstalled = false;
 function installHeapGauges(): void {
    if (heapGaugesInstalled) return;
    heapGaugesInstalled = true;
-   const meter = metrics.getMeter("publisher");
+   const meter = publisherMeter();
    meter
       .createObservableGauge("publisher_heap_size_limit_bytes", {
          description:

package/src/instrumentation.ts

@@ -1,5 +1,4 @@
 import { monitorEventLoopDelay } from "node:perf_hooks";
-import { metrics } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
 import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
@@ -18,6 +17,7 @@ import {
 } from "@opentelemetry/semantic-conventions";
 import type { NextFunction, Request, Response } from "express";
 import { logger } from "./logger";
+import { publisherMeter } from "./telemetry";
 
 let prometheusExporter: PrometheusExporter | null = null;
 let sdk: NodeSDK | null = null;
@@ -98,7 +98,7 @@ instrument();
 
 // --- HTTP metrics middleware ---
 
-const meter = metrics.getMeter("publisher");
+const meter = publisherMeter();
 
 const httpRequestDuration = meter.createHistogram(
    "http_server_request_duration_ms",

package/src/materialization_metrics.ts

@@ -12,7 +12,8 @@
  * (https://github.com/open-telemetry/opentelemetry-js/issues/3505).
  */
 
-import { metrics, type Counter, type Histogram } from "@opentelemetry/api";
+import { type Counter, type Histogram } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
 
 export type MaterializationMode = "auto" | "orchestrated";
 export type MaterializationOutcome = "success" | "failed" | "cancelled";
@@ -30,9 +31,7 @@ function lazyCounter(name: string, description: string): () => Counter {
    let instrument: Counter | null = null;
    resetHooks.push(() => (instrument = null));
    return () =>
-      (instrument ??= metrics
-         .getMeter("publisher")
-         .createCounter(name, { description }));
+      (instrument ??= publisherMeter().createCounter(name, { description }));
 }
 
 function lazyHistogram(
@@ -43,9 +42,10 @@ function lazyHistogram(
    let instrument: Histogram | null = null;
    resetHooks.push(() => (instrument = null));
    return () =>
-      (instrument ??= metrics
-         .getMeter("publisher")
-         .createHistogram(name, { description, unit }));
+      (instrument ??= publisherMeter().createHistogram(name, {
+         description,
+         unit,
+      }));
 }
 
 const runCounter = lazyCounter(

package/src/package_load/package_load_pool.ts

@@ -54,8 +54,7 @@
  *   - **Job timeout.** `PACKAGE_LOAD_JOB_TIMEOUT_MS` (default 120s) caps a
  *     single package load. On timeout we **terminate the worker** and
  *     reject the caller — we do not silently fall back, and we do not
- *     leave a zombie compile burning CPU on the worker (that's the
- *     exact scenario PR-#767's job-timeout-without-terminate had).
+ *     leave a zombie compile burning CPU on the worker.
  *
  * Schema-fetch RPC routing
  * ------------------------
@@ -234,6 +233,7 @@ export interface LoadPackageOutcome {
       explores?: string[];
       queryableSources?: "declared" | "all";
       manifestLocation?: string | null;
+      materialization?: { schedule: string | null } | null;
    };
    models: Array<
       Omit<SerializedModel, "modelDef" | "sourceInfos"> & {

package/src/package_load/package_load_worker.ts

@@ -16,7 +16,7 @@
  * duplicates the in-memory DB state and adds native-module load
  * latency to every worker spawn. Database probing (`readDatabases`)
  * stays on the main thread where it can reuse the package's existing
- * DuckDB connection (see PR #772).
+ * DuckDB connection.
  *
  * Boundary
  * --------
@@ -83,6 +83,7 @@ import { HackyDataStylesAccumulator } from "../data_styles";
 import { ModelCompilationError } from "../errors";
 import { validateAuthorizeProbes } from "../service/authorize";
 import { type FilterDefinition } from "../service/filter";
+import { parsePackageMaterialization } from "../service/package_manifest";
 import {
    extractQueriesFromModelDef,
    extractSourcesFromModelDef,
@@ -382,6 +383,7 @@ async function readPackageMetadata(packagePath: string): Promise<{
    explores?: string[];
    queryableSources?: "declared" | "all";
    manifestLocation?: string | null;
+   materialization?: { schedule: string | null } | null;
 }> {
    const manifestPath = path.join(packagePath, PACKAGE_MANIFEST_NAME);
    const contents = await fs.promises.readFile(manifestPath, "utf8");
@@ -391,6 +393,7 @@ async function readPackageMetadata(packagePath: string): Promise<{
       explores?: string[];
       queryableSources?: unknown;
       manifestLocation?: unknown;
+      materialization?: unknown;
    };
    return {
       name: parsed.name,
@@ -407,6 +410,9 @@ async function readPackageMetadata(packagePath: string): Promise<{
          typeof parsed.manifestLocation === "string"
             ? parsed.manifestLocation
             : null,
+      // Package-level Malloy Persistence policy; surfaced to the control plane,
+      // which owns scheduling. Only `schedule` is read today.
+      materialization: parsePackageMaterialization(parsed.materialization),
    };
 }
 

package/src/package_load/protocol.ts

@@ -17,7 +17,7 @@
  *
  * Embedded database probing (`.parquet` / `.csv` schema + row count)
  * stays on the main thread — it reuses the package's existing DuckDB
- * connection (PR #772) and the probe queries are async-IO-bound, not
+ * connection and the probe queries are async-IO-bound, not
  * CPU-bound. Keeping all native-DB handles on the main thread also
  * sidesteps Bun crash 0x20131 where duckdb-native cannot be loaded
  * into more than one isolate of the same process.
@@ -27,8 +27,8 @@
  *     (live native handles can't cross the worker boundary).
  *   - Lazy-hydrating each model's `ModelMaterializer` from `modelDef`
  *     via `Runtime._loadModelFromModelDef` on first query — NO
- *     recompile. This is what closes the loop on PR #767's original
- *     "first-query recompile on main thread" gap.
+ *     recompile, so the first query never re-runs the compiler on
+ *     the main thread.
  *
  * Per-model compile failures are returned in-band on
  * `SerializedModel.compilationError` so a single bad model doesn't
@@ -179,6 +179,7 @@ export interface LoadPackageResult {
       explores?: string[];
       queryableSources?: "declared" | "all";
       manifestLocation?: string | null;
+      materialization?: { schedule: string | null } | null;
    };
    models: SerializedModel[];
    /** Wall-clock ms inside the worker for the full package load. */

package/src/query_cap_metrics.ts

@@ -25,7 +25,8 @@
  * is one boolean check after the first 413.
  */
 
-import { metrics, type Counter } from "@opentelemetry/api";
+import { type Counter } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
 
 import { getMaxQueryRows, getMaxResponseBytes } from "./config";
 
@@ -39,7 +40,7 @@ function ensureCapTelemetry(): Counter {
    if (capExceededCounter && configGaugesInstalled) {
       return capExceededCounter;
    }
-   const meter = metrics.getMeter("publisher");
+   const meter = publisherMeter();
    if (!capExceededCounter) {
       capExceededCounter = meter.createCounter(
          "publisher_query_cap_exceeded_total",

package/src/query_concurrency.ts

@@ -1,4 +1,5 @@
-import { metrics, type Counter } from "@opentelemetry/api";
+import { type Counter } from "@opentelemetry/api";
+import { publisherMeter } from "./telemetry";
 import type { NextFunction, Request, RequestHandler, Response } from "express";
 
 import { getMaxConcurrentQueries } from "./config";
@@ -30,7 +31,7 @@ function ensureConcurrencyTelemetry(): Counter {
    if (queryConcurrencyRejectionsCounter && concurrencyTelemetryInitialized) {
       return queryConcurrencyRejectionsCounter;
    }
-   const meter = metrics.getMeter("publisher");
+   const meter = publisherMeter();
    queryConcurrencyRejectionsCounter = meter.createCounter(
       "publisher_query_concurrency_rejections_total",
       {

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/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);
+}