@malloy-publisher/server 0.0.225 → 0.0.227

package/src/service/build_plan.ts

@@ -25,11 +25,10 @@ type WirePackageMaterialization =
 const FRESHNESS_FALLBACKS = ["live", "stale_ok", "fail"] as const;
 type FreshnessFallback = (typeof FRESHNESS_FALLBACKS)[number];
 
-/** One layer's contribution to the resolved freshness/schedule (all optional). */
-interface FreshnessScheduleLayer {
+/** One layer's contribution to the resolved freshness (all optional). */
+interface FreshnessLayer {
    window?: string;
    fallback?: FreshnessFallback;
-   schedule?: string;
 }
 
 /** Minimal path-reader over a Malloy `Tag` (see `@malloydata/malloy-tag`). */
@@ -121,16 +120,17 @@ export function deriveAnnotationFields(
 }
 
 /**
- * Read the freshness/schedule keys (`freshness.window`, `freshness.fallback`,
- * `schedule`) from one Malloy tag layer, keeping only recognized values. These
- * are dotted/nested tag properties, so they are NOT captured by the scalar
- * {@link deriveAnnotationFields} loop and must be read by path here.
+ * Read the freshness keys (`freshness.window`, `freshness.fallback`) from one
+ * Malloy tag layer, keeping only recognized values. These are dotted/nested tag
+ * properties, so they are NOT captured by the scalar {@link deriveAnnotationFields}
+ * loop and must be read by path here. (Per-source `sharing`/`schedule` were
+ * retired — scope is package-level and a schedule is package-root-only — so they
+ * are not resolved here; declaring either on a source is a publish-time manifest
+ * error, enforced in Package.persistencePolicyWarnings.)
  */
-function tagFreshnessScheduleLayer(
-   tag: ReadableTag | undefined,
-): FreshnessScheduleLayer {
+function tagFreshnessLayer(tag: ReadableTag | undefined): FreshnessLayer {
    if (!tag || typeof tag.text !== "function") return {};
-   const layer: FreshnessScheduleLayer = {};
+   const layer: FreshnessLayer = {};
    const window = tag.text("freshness", "window");
    if (typeof window === "string") layer.window = window;
    const fallback = tag.text("freshness", "fallback");
@@ -140,24 +140,15 @@ function tagFreshnessScheduleLayer(
    ) {
       layer.fallback = fallback as FreshnessFallback;
    }
-   const schedule = tag.text("schedule");
-   if (typeof schedule === "string") layer.schedule = schedule;
    return layer;
 }
 
-/**
- * The package-level `materialization` config as a freshness resolution layer.
- * Only `freshness` inherits down to a source: the package-level cron
- * (`materialization.schedule`) is a distinct package-grain concept surfaced on
- * `PackageMaterializationConfig.schedule` and gated on its own, so it is NOT
- * folded into a source's effective per-source cron (doing so would double-count
- * against the package cron gate).
- */
+/** The package-level `materialization.freshness` as a resolution layer. */
 function packageFreshnessLayer(
    cfg: WirePackageMaterialization | null | undefined,
-): Pick<FreshnessScheduleLayer, "window" | "fallback"> {
+): FreshnessLayer {
    if (!cfg) return {};
-   const layer: Pick<FreshnessScheduleLayer, "window" | "fallback"> = {};
+   const layer: FreshnessLayer = {};
    if (cfg.freshness?.window) layer.window = cfg.freshness.window;
    const fallback = cfg.freshness?.fallback;
    if (
@@ -192,36 +183,30 @@ function safeModelTag(source: PersistSource): ReadableTag | undefined {
 }
 
 /**
- * Resolve a source's EFFECTIVE freshness + schedule, reported verbatim (unset
- * at every level stays null so the control plane can distinguish "unset" —
- * apply platform default — from an explicit declaration). Invalid `fallback`
- * values are dropped, never defaulted. Precedence, per field, most-specific-wins:
- *
- *  - `freshness`: source annotation > model-file default > package default.
- *  - `schedule`: source annotation > model-file default (the source's OWN cron).
- *    The package-level cron is a package-grain concept, surfaced and gated
- *    separately, so it is not folded into the per-source effective cron.
+ * Resolve a source's EFFECTIVE freshness with most-specific-wins precedence,
+ * per field: source annotation > model-file default > package default. Reported
+ * verbatim (unset at every level stays null so the control plane can
+ * distinguish "unset" — apply platform default — from an explicit declaration).
+ * Invalid `fallback` values are dropped, never defaulted. Freshness is valid in
+ * both scope modes.
  */
-export function resolveFreshnessSchedule(
+export function resolveFreshness(
    source: PersistSource,
    packageMaterialization: WirePackageMaterialization | null | undefined,
-): { freshness: WireFreshness | null; schedule: string | null } {
-   const sourceLayer = tagFreshnessScheduleLayer(safeSourceTag(source));
-   const modelLayer = tagFreshnessScheduleLayer(safeModelTag(source));
+): WireFreshness | null {
+   const sourceLayer = tagFreshnessLayer(safeSourceTag(source));
+   const modelLayer = tagFreshnessLayer(safeModelTag(source));
    const pkgLayer = packageFreshnessLayer(packageMaterialization);
 
    const window = sourceLayer.window ?? modelLayer.window ?? pkgLayer.window;
    const fallback =
       sourceLayer.fallback ?? modelLayer.fallback ?? pkgLayer.fallback;
-   const schedule = sourceLayer.schedule ?? modelLayer.schedule ?? null;
 
-   let freshness: WireFreshness | null = null;
-   if (window !== undefined || fallback !== undefined) {
-      freshness = {};
-      if (window !== undefined) freshness.window = window;
-      if (fallback !== undefined) freshness.fallback = fallback;
-   }
-   return { freshness, schedule };
+   if (window === undefined && fallback === undefined) return null;
+   const freshness: WireFreshness = {};
+   if (window !== undefined) freshness.window = window;
+   if (fallback !== undefined) freshness.fallback = fallback;
+   return freshness;
 }
 
 /** Flatten Malloy's nested BuildNode.dependsOn into a list of sourceIDs. */
@@ -439,15 +424,14 @@ export function deriveBuildPlan(
    for (const [sourceID, source] of Object.entries(sources)) {
       if (include && !include.has(source.name)) continue;
       const annotationFields = deriveAnnotationFields(source);
-      // EFFECTIVE per-source freshness + schedule, resolved most-specific-wins
+      // EFFECTIVE per-source freshness, resolved most-specific-wins
       // (source > model-file > package) and reported verbatim (null = unset at
-      // every level). Unlike `sharing`/`refresh` these are dotted/nested tag
-      // keys, so they come from resolveFreshnessSchedule rather than the scalar
-      // annotationFields map.
-      const { freshness, schedule } = resolveFreshnessSchedule(
-         source,
-         packageMaterialization,
-      );
+      // every level). Freshness is a dotted/nested tag key, so it comes from
+      // resolveFreshness rather than the scalar annotationFields map, and is
+      // valid in both scope modes. Per-source `sharing`/`schedule` are NOT
+      // emitted (retired from the contract); if a source declares either it is
+      // rejected at publish (Package.persistencePolicyWarnings) — the raw keys
+      // still ride `annotationFields` so the validator can detect them.
       wireSources[sourceID] = {
          name: source.name,
          sourceID: source.sourceID,
@@ -455,16 +439,8 @@ export function deriveBuildPlan(
          dialect: source.dialectName,
          sourceEntityId: computeSourceEntityId(source, connectionDigests),
          sql: source.getSQL(),
-         // Declared `#@ persist` scope/refresh knobs, reported VERBATIM (null
-         // = unset). The control plane applies the platform default (unset =>
-         // shared) itself, so the publisher must never substitute it — unset
-         // has to stay distinguishable from an explicit `shared`. The source's
-         // own annotation is the most-specific declaration layer, and the only
-         // one that exists today.
-         sharing: annotationFields.sharing ?? null,
          refresh: annotationFields.refresh ?? null,
-         freshness,
-         schedule,
+         freshness: resolveFreshness(source, packageMaterialization),
          columns: deriveColumns(source),
          annotationFields,
          modelPath: sourceModelPaths?.[sourceID],

package/src/service/environment.ts

@@ -792,7 +792,7 @@ export class Environment {
       // reloadAllModelsForPackage, ...) acquire the lock themselves.
       //
       // INVARIANT: callers that consume the returned Package on the fast
-      // path (notably MCP resource handlers and Model.getModel()) must
+      // path (notably the MCP query tools and Model.getModel()) must
       // remain in-memory only. If any code reachable from a `Package`
       // method ever grows new disk I/O against the canonical tree, that
       // path needs to be bracketed by `withPackageLock`; otherwise a
@@ -1347,6 +1347,10 @@ export class Environment {
             // control plane misread the gap as a schedule removal. It is not a
             // PATCH-editable field, so always preserve the existing value.
             materialization: existing.materialization,
+            // Same rationale for the manifest-derived persist `scope`: not
+            // PATCH-editable, so preserve it rather than dropping it to the
+            // default until the next reload.
+            scope: existing.scope,
          });
 
          // Strict-reject, symmetric with the publish path

package/src/service/materialization_test_fixtures.ts

@@ -75,17 +75,16 @@ export function makeInstruction(
  * build internals touch (name/id, deterministic sourceEntityId, SQL, and the
  * `#@ persist name=` annotation reader, defaulted to "unset").
  */
-/** A freshness/schedule layer for the fake source's `#@` or `##` tag. */
+/** A freshness layer for the fake source's `#@` or `##` tag. */
 interface FakeFreshnessSchedule {
    freshness?: { window?: string; fallback?: string };
-   schedule?: string;
 }
 
 /**
  * Build a fake Malloy `Tag` supporting both readers the build plan uses:
  * `entries()` (scalar `#@ persist` key=value pairs, for deriveAnnotationFields)
- * and the path-based `text(...at)` (dotted `freshness.window` / `schedule`, for
- * resolveFreshnessSchedule).
+ * and the path-based `text(...at)` (dotted `freshness.window`, for
+ * resolveFreshness).
  */
 function fakeTag(
    fields: Record<string, string> | undefined,
@@ -99,7 +98,6 @@ function fakeTag(
       },
       text(...at: string[]): string | undefined {
          if (at.length === 1) {
-            if (at[0] === "schedule") return fs?.schedule;
             return fields?.[at[0]];
          }
          if (at.length === 2 && at[0] === "freshness") {
@@ -116,11 +114,11 @@ export function fakeSource(opts: {
    sql?: string;
    connectionName?: string;
    dialectName?: string;
-   /** key=value fields of the `#@ persist` annotation (e.g. sharing). */
+   /** key=value fields of the `#@ persist` annotation (e.g. name, refresh). */
    annotationFields?: Record<string, string>;
-   /** Source-level (`#@`) freshness/schedule (dotted keys). */
+   /** Source-level (`#@`) freshness (dotted keys). */
    freshnessSchedule?: FakeFreshnessSchedule;
-   /** Model-file-level (`##`) freshness/schedule default. */
+   /** Model-file-level (`##`) freshness default. */
    modelFreshnessSchedule?: FakeFreshnessSchedule;
 }): PersistSource {
    const fields = opts.annotationFields;

package/src/service/package.ts

@@ -29,6 +29,11 @@ import {
 } from "../errors";
 import { formatDuration, logger } from "../logger";
 import { recordBuildPlanComputeDuration } from "../materialization_metrics";
+import {
+   LOAD_DURATION_BUCKETS_MS,
+   recordPackageLoadPhases,
+   type PackageLoadStatus,
+} from "../package_load_metrics";
 import { assertSafeEnvironmentPath, safeJoinUnderRoot } from "../path_safety";
 import {
    BuildManifest,
@@ -73,6 +78,23 @@ function toTableNameManifest(
    return out;
 }
 
+/**
+ * Classify a failed package load into the `status` label shared by the
+ * `malloy_package_load_duration` histogram and the per-phase load metrics, so
+ * both slice failures identically. A real Malloy/model compile error is a 4xx
+ * `compilation_error`; a rewrapped pool-infrastructure failure is a transient
+ * `pool_unavailable`; anything else is a generic `error`.
+ */
+function packageLoadFailureStatus(error: unknown): PackageLoadStatus {
+   if (error instanceof ModelCompilationError || error instanceof MalloyError) {
+      return "compilation_error";
+   }
+   if (error instanceof ServiceUnavailableError) {
+      return "pool_unavailable";
+   }
+   return "error";
+}
+
 export class Package {
    private environmentName: string;
    private packageName: string;
@@ -127,6 +149,10 @@ export class Package {
       {
          description: "Time taken to load a Malloy package",
          unit: "ms",
+         // OTel's default buckets top out at 10s, censoring the slow-load tail.
+         // Use the shared load-duration buckets (→5min) so p95/p99 of large
+         // package loads are resolvable. See LOAD_DURATION_BUCKETS_MS.
+         advice: { explicitBucketBoundaries: LOAD_DURATION_BUCKETS_MS },
       },
    );
 
@@ -248,16 +274,9 @@ export class Package {
          console.error(error);
          const endTime = performance.now();
          const executionTime = endTime - startTime;
-         const status =
-            error instanceof ModelCompilationError ||
-            error instanceof MalloyError
-               ? "compilation_error"
-               : error instanceof ServiceUnavailableError
-                 ? "pool_unavailable"
-                 : "error";
          this.packageLoadHistogram.record(executionTime, {
             malloy_package_name: packageName,
-            status,
+            status: packageLoadFailureStatus(error),
          });
          // Clean up the package directory on failure, but NOT when packagePath
          // is an in-place mount symlink (watch mode). Removing it would unmount
@@ -361,6 +380,10 @@ export class Package {
          workerDurationMs: outcome.loadDurationMs,
          dispatchOverheadMs:
             workerDoneTime - dispatchTime - outcome.loadDurationMs,
+         // Phase split of the worker duration (remainder = setup + extraction).
+         compileDurationMs: outcome.timings.compileDurationMs,
+         schemaFetchDurationMs: outcome.timings.schemaFetchDurationMs,
+         schemaFetchCount: outcome.timings.schemaFetchCount,
          modelCount: outcome.models.length,
          databaseCount: databases.length,
       });
@@ -386,6 +409,10 @@ export class Package {
             schedule: null,
             freshness: null,
          },
+         // Package-level persist scope mode, applied uniformly to every persist
+         // source/index. Defaults to "package" (cross-version reuse) when the
+         // manifest omits it.
+         scope: outcome.packageMetadata.scope ?? "package",
       };
 
       // Build live `Model`s from worker output. Any per-model compile
@@ -396,43 +423,59 @@ export class Package {
       // hydration path.)
       const models = new Map<string, Model>();
       const renderTagWarnings: ApiPackageWarning[] = [];
-      for (const sm of outcome.models) {
-         if (sm.compilationError) {
-            const err = Model.deserializeCompilationError(sm.compilationError);
-            logger.error("Model compilation failed", {
+      try {
+         for (const sm of outcome.models) {
+            if (sm.compilationError) {
+               const err = Model.deserializeCompilationError(
+                  sm.compilationError,
+               );
+               logger.error("Model compilation failed", {
+                  packageName,
+                  modelPath: sm.modelPath,
+                  error: err.message,
+               });
+               // The outer catch in Package.create records the total metric +
+               // cleans the package directory.
+               throw err;
+            }
+            const model = Model.fromSerialized(
                packageName,
-               modelPath: sm.modelPath,
-               error: err.message,
-            });
-            // The outer catch in Package.create records the metric +
-            // cleans the package directory.
-            throw err;
-         }
-         const model = Model.fromSerialized(
-            packageName,
-            packagePath,
-            malloyConfig,
-            sm,
-         );
-         // Validate renderer tags on the main thread (the renderer is too heavy
-         // to load inside the pure-CPU package-load worker). A misconfigured tag
-         // is logged as a warning naming the target; it does not fail the load.
-         // The findings also ride the package response as non-fatal `warnings`.
-         for (const w of await model.validateRenderTags()) {
-            renderTagWarnings.push({ model: sm.modelPath, ...w });
-         }
-         // Reject unquoted `#@ persist name=` annotations the same way: an
-         // unquoted name is dropped from the build plan, so the source would
-         // publish but never materialize. Scan the raw `.malloy` source (the
-         // ground truth for quoting); throws a ModelCompilationError (424).
-         if (sm.modelPath.endsWith(MODEL_FILE_SUFFIX)) {
-            const modelSource = await fs.readFile(
-               path.join(packagePath, sm.modelPath),
-               "utf-8",
+               packagePath,
+               malloyConfig,
+               sm,
             );
-            assertPersistNamesQuoted(modelSource, sm.modelPath);
+            // Validate renderer tags on the main thread (the renderer is too
+            // heavy to load inside the pure-CPU package-load worker). A
+            // misconfigured tag is logged as a warning naming the target; it
+            // does not fail the load. The findings also ride the package
+            // response as non-fatal `warnings`.
+            for (const w of await model.validateRenderTags()) {
+               renderTagWarnings.push({ model: sm.modelPath, ...w });
+            }
+            // Reject unquoted `#@ persist name=` annotations the same way: an
+            // unquoted name is dropped from the build plan, so the source would
+            // publish but never materialize. Scan the raw `.malloy` source (the
+            // ground truth for quoting); throws a ModelCompilationError (424).
+            if (sm.modelPath.endsWith(MODEL_FILE_SUFFIX)) {
+               const modelSource = await fs.readFile(
+                  path.join(packagePath, sm.modelPath),
+                  "utf-8",
+               );
+               assertPersistNamesQuoted(modelSource, sm.modelPath);
+            }
+            models.set(sm.modelPath, model);
          }
-         models.set(sm.modelPath, model);
+      } catch (err) {
+         // Record the load's phase cost tagged with the terminal status before
+         // the error propagates to the outer catch (which records the total).
+         // Only in-band compile failures reach here — the worker already
+         // produced `outcome.timings`; a pool failure throws before `outcome`
+         // exists and carries no timings, so it's simply not recorded.
+         recordPackageLoadPhases(
+            outcome.timings,
+            packageLoadFailureStatus(err),
+         );
+         throw err;
       }
 
       const endTime = performance.now();
@@ -441,6 +484,7 @@ export class Package {
          malloy_package_name: packageName,
          status: "success",
       });
+      recordPackageLoadPhases(outcome.timings, "success");
       logger.info(`Successfully loaded package ${packageName}`, {
          packageName,
          duration: formatDuration(executionTime),
@@ -492,15 +536,19 @@ export class Package {
             detail: invalidMsg,
          });
       }
-      // Same fail-safe split for the materialization cron gate: an existing
-      // package whose manifest violates the private-only cron rule still loads
-      // (warn), but a publish of it is rejected (see package.controller).
-      const invalidSchedule = pkg.formatInvalidSchedule();
-      if (invalidSchedule) {
-         logger.warn(`Package ${packageName} has an invalid cron schedule`, {
-            packageName,
-            detail: invalidSchedule,
-         });
+      // Same fail-safe split for the persistence-policy gate: an existing
+      // package whose manifest violates the scope/schedule/freshness rules
+      // still loads (warn), but a publish of it is rejected (see
+      // package.controller).
+      const invalidPolicy = pkg.formatInvalidPersistencePolicy();
+      if (invalidPolicy) {
+         logger.warn(
+            `Package ${packageName} has an invalid persistence policy`,
+            {
+               packageName,
+               detail: invalidPolicy,
+            },
+         );
       }
       pkg.logEmptyDiscoveryWarnings();
 
@@ -717,56 +765,84 @@ export class Package {
    }
 
    /**
-    * Publish-gate for materialization crons (Phase A carve-out, persistence.md
-    * §9.4). A cron is the power tier of artifact-anchored scheduling and is
-    * valid only over `sharing="private"` artifacts; a cron on a shared (or unset
-    * ⇒ shared) artifact is rejected, pointing at `freshness.window` as the
-    * shared-tier replacement. Two grains, both enforced off the resolved build
-    * plan (per-source `sharing`/`schedule` are effective, most-specific-wins):
+    * Publish-gate for the package's Malloy Persistence policy (persistence.md
+    * §3.1, §9.2–§9.5). Scope is a single package-level mode (`Package.scope`)
+    * and a materialization cron is package-root-only and version-scope-only.
+    * The rules, read off the resolved build plan + manifest:
     *
-    *  - Per-source: a source's own `schedule` is valid only when that source
-    *    resolves to explicit `sharing="private"`.
-    *  - Package: `materialization.schedule` governs every persist source, so it
-    *    is valid only when every governed source resolves to explicit
-    *    `sharing="private"` (a mixed/shared/unset package cannot carry it).
+    *  1. Per-source `#@ persist ... sharing=`/`schedule=` are retired — declaring
+    *     either on a source is an error (scope is package-level; a schedule is
+    *     package-root-only). Detected via the raw `annotationFields`.
+    *  2. `materialization.schedule` is legal only when `scope: version` (a
+    *     package-scoped lineage is reused across versions, so a single
+    *     per-version cadence is meaningless).
+    *  3. `materialization.schedule` and freshness (package `materialization.freshness`
+    *     or any source `freshness`) are mutually exclusive — declare either the
+    *     power tier or the objective tier, never both.
+    *
+    * The cross-package dependency rule (a `scope: version` scheduled package may
+    * not depend on a package-scoped upstream) is not enforced here: scope is
+    * uniform within a package, so an intra-package dependency can never violate
+    * it, and the publisher's build plan is intra-package only — a cross-package
+    * upstream's scope is not resolvable from the single `Package` served. It is
+    * deferred to the scheduler slice (R1–R3), which resolves cross-package scope.
     *
     * Strict at publish (package.controller), warn-only at load/reload
     * (loadViaWorker) — same split as explores.
     */
-   public scheduleWarnings(): string[] {
+   public persistencePolicyWarnings(): string[] {
       const warnings: string[] = [];
       const sources = this.buildPlan?.sources
          ? Object.values(this.buildPlan.sources)
          : [];
+      const materialization = this.packageMetadata.materialization;
+      const packageSchedule = materialization?.schedule ?? null;
+      const packageFreshness = materialization?.freshness ?? null;
+      const scope = this.packageMetadata.scope ?? "package";
 
+      // Rule 1: per-source sharing/schedule are no longer part of the model.
       for (const source of sources) {
-         if (source.schedule && source.sharing !== "private") {
+         const fields = source.annotationFields ?? {};
+         if (fields.sharing !== undefined) {
+            warnings.push(
+               `#@ persist source "${source.name}" declares sharing=... which is ` +
+                  `no longer supported: scope is a single package-level mode. Set ` +
+                  `the root-level "scope": "version" | "package" in ` +
+                  `${PACKAGE_MANIFEST_NAME} instead.`,
+            );
+         }
+         if (fields.schedule !== undefined) {
             warnings.push(
-               `#@ persist source "${source.name}" declares a schedule (cron) but ` +
-                  `resolves to sharing="${
-                     source.sharing ?? "shared (unset default)"
-                  }": a per-source cron is valid only for sharing="private". ` +
-                  `Declare 'freshness.window' instead (the control plane schedules ` +
-                  `refreshes from it).`,
+               `#@ persist source "${source.name}" declares schedule=... which is ` +
+                  `no longer supported: a schedule is package-root-only. Declare ` +
+                  `"materialization.schedule" at the ${PACKAGE_MANIFEST_NAME} root ` +
+                  `(requires "scope": "version") instead.`,
             );
          }
       }
 
-      const packageSchedule = this.packageMetadata.materialization?.schedule;
+      // Rule 2: a package-level cron is legal only with scope: version.
+      if (packageSchedule && scope !== "version") {
+         warnings.push(
+            `materialization.schedule (cron) in ${PACKAGE_MANIFEST_NAME} requires ` +
+               `"scope": "version": a package-scoped lineage is reused across ` +
+               `versions, so a single per-version cadence is meaningless. Set ` +
+               `"scope": "version", or remove the schedule.`,
+         );
+      }
+
+      // Rule 3: schedule and freshness are mutually exclusive.
       if (packageSchedule) {
-         const nonPrivate = sources.filter((s) => s.sharing !== "private");
-         if (sources.length === 0 || nonPrivate.length > 0) {
-            const detail =
-               sources.length === 0
-                  ? "the package declares no persist source for it to govern"
-                  : `sources [${nonPrivate
-                       .map((s) => s.name)
-                       .join(", ")}] resolve to shared/unset`;
+         const freshnessDeclared =
+            !!(
+               packageFreshness &&
+               (packageFreshness.window || packageFreshness.fallback)
+            ) || sources.some((s) => s.freshness != null);
+         if (freshnessDeclared) {
             warnings.push(
-               `materialization.schedule (cron) in ${PACKAGE_MANIFEST_NAME} is valid ` +
-                  `only when every persist source resolves to sharing="private": ` +
-                  `${detail}. Declare 'materialization.freshness.window' instead ` +
-                  `(the control plane schedules refreshes from it).`,
+               `materialization.schedule and freshness are mutually exclusive in ` +
+                  `${PACKAGE_MANIFEST_NAME}: declare either a schedule (power tier) ` +
+                  `or freshness (objective tier), never both.`,
             );
          }
       }
@@ -774,9 +850,12 @@ export class Package {
       return warnings;
    }
 
-   /** The {@link scheduleWarnings} joined into one string, or "" if none. */
-   public formatInvalidSchedule(): string {
-      return this.scheduleWarnings().join("\n");
+   /**
+    * The {@link persistencePolicyWarnings} joined into one string, or "" if the
+    * package's persistence policy is valid.
+    */
+   public formatInvalidPersistencePolicy(): string {
+      return this.persistencePolicyWarnings().join("\n");
    }
 
    /**

package/src/service/package_manifest.spec.ts

@@ -1,7 +1,28 @@
 import { describe, expect, it } from "bun:test";
-import { parsePackageMaterialization } from "./package_manifest";
+import {
+   parsePackageMaterialization,
+   parsePackageScope,
+} from "./package_manifest";
 
 describe("service/package_manifest", () => {
+   describe("parsePackageScope", () => {
+      it("defaults to 'package' when absent", () => {
+         expect(parsePackageScope(undefined)).toBe("package");
+         expect(parsePackageScope(null)).toBe("package");
+      });
+
+      it("accepts the two valid modes verbatim", () => {
+         expect(parsePackageScope("version")).toBe("version");
+         expect(parsePackageScope("package")).toBe("package");
+      });
+
+      it("throws on any other value (no silent default)", () => {
+         expect(() => parsePackageScope("shared")).toThrow(/scope/i);
+         expect(() => parsePackageScope("")).toThrow(/scope/i);
+         expect(() => parsePackageScope(7)).toThrow(/scope/i);
+      });
+   });
+
    describe("parsePackageMaterialization", () => {
       it("extracts a string schedule", () => {
          expect(parsePackageMaterialization({ schedule: "0 6 * * *" })).toEqual(

package/src/service/package_manifest.ts

@@ -7,6 +7,35 @@
 const FRESHNESS_FALLBACKS = ["live", "stale_ok", "fail"] as const;
 export type FreshnessFallback = (typeof FRESHNESS_FALLBACKS)[number];
 
+/**
+ * Package-level Malloy Persistence scope mode, declared once at the manifest
+ * root. `package` (the default) = artifacts are reused across the package's
+ * versions when they satisfy freshness; `version` = each artifact is owned by
+ * one published version (the only mode a `materialization.schedule` is legal
+ * in). Applied uniformly to every persist source and index in the package.
+ */
+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.
+ */
+export function parsePackageScope(raw: unknown): PackageScope {
+   if (raw === undefined || raw === null) {
+      return "package";
+   }
+   if ((PACKAGE_SCOPES as readonly unknown[]).includes(raw)) {
+      return raw as PackageScope;
+   }
+   throw new Error(
+      `Invalid "scope" in the package manifest: ${JSON.stringify(raw)}. ` +
+         `Expected "version" or "package" (default "package").`,
+   );
+}
+
 /**
  * The manifest's `materialization.freshness` block, surfaced verbatim for the
  * control plane (which owns the scheduling and query-time gating logic).