@malloy-publisher/server 0.0.224 → 0.0.226

package/src/package_load/package_load_pool.ts

@@ -81,7 +81,10 @@ import { fileURLToPath, pathToFileURL } from "url";
 
 import { ModelCompilationError } from "../errors";
 import { logger } from "../logger";
-import type { PackageMaterializationConfig } from "../service/package_manifest";
+import type {
+   PackageMaterializationConfig,
+   PackageScope,
+} from "../service/package_manifest";
 import type {
    ConnectionMetadataRequest,
    ConnectionMetadataResponse,
@@ -235,6 +238,7 @@ export interface LoadPackageOutcome {
       queryableSources?: "declared" | "all";
       manifestLocation?: string | null;
       materialization?: PackageMaterializationConfig | null;
+      scope?: PackageScope;
    };
    models: Array<
       Omit<SerializedModel, "modelDef" | "sourceInfos"> & {

package/src/package_load/package_load_worker.ts

@@ -85,7 +85,9 @@ import { validateAuthorizeProbes } from "../service/authorize";
 import { type FilterDefinition } from "../service/filter";
 import {
    PackageMaterializationConfig,
+   PackageScope,
    parsePackageMaterialization,
+   parsePackageScope,
 } from "../service/package_manifest";
 import {
    extractQueriesFromModelDef,
@@ -387,6 +389,7 @@ async function readPackageMetadata(packagePath: string): Promise<{
    queryableSources?: "declared" | "all";
    manifestLocation?: string | null;
    materialization?: PackageMaterializationConfig | null;
+   scope?: PackageScope;
 }> {
    const manifestPath = path.join(packagePath, PACKAGE_MANIFEST_NAME);
    const contents = await fs.promises.readFile(manifestPath, "utf8");
@@ -397,6 +400,7 @@ async function readPackageMetadata(packagePath: string): Promise<{
       queryableSources?: unknown;
       manifestLocation?: unknown;
       materialization?: unknown;
+      scope?: unknown;
    };
    return {
       name: parsed.name,
@@ -416,6 +420,9 @@ async function readPackageMetadata(packagePath: string): Promise<{
       // Package-level Malloy Persistence policy; surfaced to the control plane,
       // which owns scheduling. Only `schedule` is read today.
       materialization: parsePackageMaterialization(parsed.materialization),
+      // Package-level persist scope mode; defaults to "package". An invalid
+      // value throws here and fails the load (scope is load-bearing).
+      scope: parsePackageScope(parsed.scope),
    };
 }
 

package/src/package_load/protocol.ts

@@ -65,7 +65,10 @@
  */
 
 import type { SQLSourceDef, TableSourceDef } from "@malloydata/malloy";
-import type { PackageMaterializationConfig } from "../service/package_manifest";
+import type {
+   PackageMaterializationConfig,
+   PackageScope,
+} from "../service/package_manifest";
 
 // ──────────────────────────────────────────────────────────────────────
 // Direction: main ──▶ worker (load-package job)
@@ -181,6 +184,7 @@ export interface LoadPackageResult {
       queryableSources?: "declared" | "all";
       manifestLocation?: string | null;
       materialization?: PackageMaterializationConfig | null;
+      scope?: PackageScope;
    };
    models: SerializedModel[];
    /** Wall-clock ms inside the worker for the full package load. */

package/src/service/build_plan.spec.ts

@@ -10,6 +10,7 @@ import {
    deriveBuildPlan,
    flattenDependsOn,
    iterGraphSources,
+   resolveFreshness,
    resolvePackageConnections,
 } from "./build_plan";
 import { fakeSource } from "./materialization_test_fixtures";
@@ -212,10 +213,10 @@ describe("deriveBuildPlan", () => {
       });
    });
 
-   it("reports declared sharing/refresh verbatim and null when unset", () => {
-      // The control plane distinguishes unset from an explicit `shared` (it
-      // applies the platform default itself), so the publisher must report
-      // the declared value verbatim — never substitute the default.
+   it("reports declared refresh verbatim (null when unset) and does not emit sharing/schedule", () => {
+      // `refresh` is a metadata pass-through; `sharing`/`schedule` were retired
+      // from the contract and must not be emitted as typed fields (they stay in
+      // the raw annotationFields for the publish-time validator to detect).
       const declared = fakeSource({
          name: "declared",
          sourceEntityId: "bid-d",
@@ -242,17 +243,22 @@ describe("deriveBuildPlan", () => {
          { duckdb: "dig" },
       );
 
-      expect(plan.sources["declared@m"].sharing).toBe("private");
       expect(plan.sources["declared@m"].refresh).toBe("incremental");
-      // The raw annotation map still carries every field alongside the typed
-      // projections.
+      // Retired typed fields are absent from the wire projection.
+      expect(
+         (plan.sources["declared@m"] as Record<string, unknown>).sharing,
+      ).toBeUndefined();
+      expect(
+         (plan.sources["declared@m"] as Record<string, unknown>).schedule,
+      ).toBeUndefined();
+      // The raw annotation map still carries every field (so the validator can
+      // reject a source-level sharing/schedule at publish).
       expect(plan.sources["declared@m"].annotationFields).toEqual({
          name: "d_table",
          sharing: "private",
          refresh: "incremental",
       });
-      // Unset is null — not "shared" — on the wire.
-      expect(plan.sources["unset@m"].sharing).toBeNull();
+      // Unset refresh is null on the wire.
       expect(plan.sources["unset@m"].refresh).toBeNull();
    });
 
@@ -296,6 +302,101 @@ describe("deriveBuildPlan", () => {
    });
 });
 
+describe("resolveFreshness", () => {
+   it("reports source-level freshness verbatim", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: {
+            freshness: { window: "1h", fallback: "stale_ok" },
+         },
+      });
+      expect(resolveFreshness(source, null)).toEqual({
+         window: "1h",
+         fallback: "stale_ok",
+      });
+   });
+
+   it("returns null when unset at every level", () => {
+      const source = fakeSource({ name: "s", sourceEntityId: "bid" });
+      expect(resolveFreshness(source, null)).toBeNull();
+   });
+
+   it("falls back to model-file then package per field (most-specific-wins)", () => {
+      // freshness.window from source, freshness.fallback from model-file.
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: { freshness: { window: "1h" } },
+         modelFreshnessSchedule: { freshness: { fallback: "fail" } },
+      });
+      const pkg = {
+         schedule: null,
+         freshness: { window: "24h", fallback: "live" as const },
+      };
+      expect(resolveFreshness(source, pkg)).toEqual({
+         window: "1h",
+         fallback: "fail",
+      });
+   });
+
+   it("inherits the package freshness when the source and model are unset", () => {
+      const source = fakeSource({ name: "s", sourceEntityId: "bid" });
+      const pkg = { schedule: null, freshness: { window: "24h" } };
+      expect(resolveFreshness(source, pkg)).toEqual({ window: "24h" });
+   });
+
+   it("drops an invalid fallback rather than defaulting it", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: { freshness: { window: "1h", fallback: "bogus" } },
+      });
+      expect(resolveFreshness(source, null)).toEqual({ window: "1h" });
+   });
+});
+
+describe("deriveBuildPlan freshness", () => {
+   it("projects the resolved per-source freshness onto the plan (no schedule/sharing)", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         annotationFields: { name: "s_table" },
+         freshnessSchedule: { freshness: { window: "1h" } },
+      });
+      const plan = deriveBuildPlan(
+         [
+            {
+               connectionName: "duckdb",
+               nodes: [[{ sourceID: "s@m", dependsOn: [] }]],
+            },
+         ] as unknown as Parameters<typeof deriveBuildPlan>[0],
+         { "s@m": source },
+         { duckdb: "dig" },
+         undefined,
+         undefined,
+         {
+            schedule: null,
+            freshness: { window: "24h", fallback: "live" as const },
+         },
+      );
+
+      // Source window wins over the package default; package fallback fills the
+      // unset source fallback.
+      expect(plan.sources["s@m"].freshness).toEqual({
+         window: "1h",
+         fallback: "live",
+      });
+      // Retired fields are not emitted.
+      expect(
+         (plan.sources["s@m"] as Record<string, unknown>).schedule,
+      ).toBeUndefined();
+      expect(
+         (plan.sources["s@m"] as Record<string, unknown>).sharing,
+      ).toBeUndefined();
+   });
+});
+
 describe("compilePackageBuildPlan", () => {
    it("skips .malloynb notebooks without compiling them", async () => {
       // A notebook would throw on its `>>>` cell delimiter if compiled as a

package/src/service/build_plan.ts

@@ -17,6 +17,24 @@ type WireBuildGraph = components["schemas"]["BuildGraph"];
 type WirePersistSourcePlan = components["schemas"]["PersistSourcePlan"];
 type WireColumn = components["schemas"]["Column"];
 type BuildPlan = components["schemas"]["BuildPlan"];
+type WireFreshness = components["schemas"]["Freshness"];
+type WirePackageMaterialization =
+   components["schemas"]["PackageMaterializationConfig"];
+
+/** The freshness `fallback` values the publisher recognizes; others are dropped. */
+const FRESHNESS_FALLBACKS = ["live", "stale_ok", "fail"] as const;
+type FreshnessFallback = (typeof FRESHNESS_FALLBACKS)[number];
+
+/** One layer's contribution to the resolved freshness (all optional). */
+interface FreshnessLayer {
+   window?: string;
+   fallback?: FreshnessFallback;
+}
+
+/** Minimal path-reader over a Malloy `Tag` (see `@malloydata/malloy-tag`). */
+interface ReadableTag {
+   text(...path: string[]): string | undefined;
+}
 
 /**
  * Minimal surface a package must expose to compile its build plan. Both
@@ -28,6 +46,13 @@ export interface BuildPlanPackage {
    getPackagePath(): string;
    getMalloyConfig(): MalloyConfig;
    getMalloyConnection(name: string): Promise<MalloyConnection>;
+   /**
+    * The package-level `materialization` config (from malloy-publisher.json),
+    * used as the least-specific layer when resolving per-source freshness /
+    * schedule. Optional so existing fixtures/callers that don't track it still
+    * typecheck (they resolve without a package default).
+    */
+   getMaterializationConfig?(): WirePackageMaterialization | null;
 }
 
 /**
@@ -94,6 +119,96 @@ export function deriveAnnotationFields(
    return out;
 }
 
+/**
+ * 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 tagFreshnessLayer(tag: ReadableTag | undefined): FreshnessLayer {
+   if (!tag || typeof tag.text !== "function") return {};
+   const layer: FreshnessLayer = {};
+   const window = tag.text("freshness", "window");
+   if (typeof window === "string") layer.window = window;
+   const fallback = tag.text("freshness", "fallback");
+   if (
+      typeof fallback === "string" &&
+      (FRESHNESS_FALLBACKS as readonly string[]).includes(fallback)
+   ) {
+      layer.fallback = fallback as FreshnessFallback;
+   }
+   return layer;
+}
+
+/** The package-level `materialization.freshness` as a resolution layer. */
+function packageFreshnessLayer(
+   cfg: WirePackageMaterialization | null | undefined,
+): FreshnessLayer {
+   if (!cfg) return {};
+   const layer: FreshnessLayer = {};
+   if (cfg.freshness?.window) layer.window = cfg.freshness.window;
+   const fallback = cfg.freshness?.fallback;
+   if (
+      typeof fallback === "string" &&
+      (FRESHNESS_FALLBACKS as readonly string[]).includes(fallback)
+   ) {
+      layer.fallback = fallback as FreshnessFallback;
+   }
+   return layer;
+}
+
+/** The source's `#@` tag, or undefined if it fails to parse (degrade to unset). */
+function safeSourceTag(source: PersistSource): ReadableTag | undefined {
+   try {
+      return source.annotations.parseAsTag("@").tag as ReadableTag;
+   } catch {
+      return undefined;
+   }
+}
+
+/**
+ * The model-file-level (`##`) tag resolved for the source, or undefined on a
+ * parse failure. The model-file layer sits between the source annotation and
+ * the package default in most-specific-wins resolution.
+ */
+function safeModelTag(source: PersistSource): ReadableTag | undefined {
+   try {
+      return source.modelAnnotations.parseAsTag().tag as ReadableTag;
+   } catch {
+      return undefined;
+   }
+}
+
+/**
+ * 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 resolveFreshness(
+   source: PersistSource,
+   packageMaterialization: WirePackageMaterialization | null | undefined,
+): 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;
+
+   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. */
 export function flattenDependsOn(node: {
    dependsOn: { sourceID: string }[];
@@ -291,6 +406,7 @@ export function deriveBuildPlan(
    connectionDigests: Record<string, string>,
    sourceNames?: string[],
    sourceModelPaths?: Record<string, string>,
+   packageMaterialization?: WirePackageMaterialization | null,
 ): BuildPlan {
    const include = sourceNames ? new Set(sourceNames) : null;
 
@@ -308,6 +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, resolved most-specific-wins
+      // (source > model-file > package) and reported verbatim (null = unset at
+      // 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,
@@ -315,14 +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: resolveFreshness(source, packageMaterialization),
          columns: deriveColumns(source),
          annotationFields,
          modelPath: sourceModelPaths?.[sourceID],
@@ -351,5 +469,6 @@ export async function computePackageBuildPlan(
       compiled.connectionDigests,
       undefined,
       compiled.sourceModelPaths,
+      pkg.getMaterializationConfig?.() ?? null,
    );
 }

package/src/service/environment.ts

@@ -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_service.spec.ts

@@ -921,6 +921,10 @@ describe("runBuild (branch behavior)", () => {
             sourceNames: string[] | undefined;
             forceRefresh: boolean;
             buildInstructions: BuildInstruction[] | undefined;
+            referenceManifest?:
+               | { sourceEntityId: string; physicalTableName: string }[]
+               | undefined;
+            strictUpstreams?: boolean | undefined;
          },
          signal: AbortSignal,
       ) => Promise<void>;
@@ -972,6 +976,44 @@ describe("runBuild (branch behavior)", () => {
       expect(svc.autoLoadManifest.called).toBe(false);
    });
 
+   it("orchestrated: seeds the build from referenceManifest and honors strictUpstreams", async () => {
+      const svc = stubEngine();
+      const instructions = [makeInstruction()];
+
+      await svc.runBuild(
+         "mat-1",
+         "my-env",
+         "pkg",
+         {
+            sourceNames: undefined,
+            forceRefresh: false,
+            buildInstructions: instructions,
+            referenceManifest: [
+               { sourceEntityId: "up-1", physicalTableName: "upstream_tbl" },
+            ],
+            strictUpstreams: true,
+         },
+         new AbortController().signal,
+      );
+
+      // The reference manifest becomes the seed (carried) entries so a
+      // downstream build resolves its upstream to the existing physical table.
+      expect(svc.executeInstructedBuild.firstCall.args[2]).toEqual({
+         "up-1": {
+            sourceEntityId: "up-1",
+            physicalTableName: "upstream_tbl",
+         },
+      });
+      // strictUpstreams flows through as the strict flag (5th arg).
+      expect(svc.executeInstructedBuild.firstCall.args[4]).toBe(true);
+      // Reused upstreams are counted as carried, not built.
+      expect(svc.commitManifest.firstCall.args[2]).toMatchObject({
+         mode: "orchestrated",
+         sourcesBuilt: 1,
+         sourcesReused: 1,
+      });
+   });
+
    it("auto-run: derives instructions and auto-loads the manifest", async () => {
       const svc = stubEngine();
 

package/src/service/materialization_service.ts

@@ -28,6 +28,7 @@ import {
    MaterializationStatus,
    MaterializationUpdate,
    ManifestEntry,
+   ManifestReference,
    ResourceRepository,
 } from "../storage/DatabaseInterface";
 import { DuplicateActiveMaterializationError } from "../storage/duckdb/MaterializationRepository";
@@ -216,6 +217,8 @@ export class MaterializationService {
          forceRefresh?: boolean;
          sourceNames?: string[];
          buildInstructions?: BuildInstruction[];
+         referenceManifest?: ManifestReference[];
+         strictUpstreams?: boolean;
       } = {},
    ): Promise<Materialization> {
       const environmentId = await this.resolveEnvironmentId(environmentName);
@@ -275,6 +278,8 @@ export class MaterializationService {
                sourceNames: options.sourceNames,
                forceRefresh,
                buildInstructions,
+               referenceManifest: options.referenceManifest,
+               strictUpstreams: options.strictUpstreams,
             },
             signal,
          ),
@@ -299,6 +304,8 @@ export class MaterializationService {
          sourceNames: string[] | undefined;
          forceRefresh: boolean;
          buildInstructions: BuildInstruction[] | undefined;
+         referenceManifest: ManifestReference[] | undefined;
+         strictUpstreams: boolean | undefined;
       },
       signal: AbortSignal,
    ): Promise<void> {
@@ -333,7 +340,12 @@ export class MaterializationService {
          let carried: Record<string, ManifestEntry>;
          if (orchestrated) {
             instructions = opts.buildInstructions!;
-            carried = {};
+            // Seed the build Manifest with the caller-supplied upstream
+            // references so a downstream source's persist upstream (built in a
+            // prior run, not rebuilt here) resolves to its existing physical
+            // table instead of recomputing live. The reference key is the
+            // compiler's manifest-lookup sourceEntityId (see ManifestReference).
+            carried = this.referenceManifestToEntries(opts.referenceManifest);
          } else {
             // Skip-if-unchanged: reuse tables from the most recent successful
             // manifest for sources whose sourceEntityId is unchanged, unless
@@ -357,6 +369,7 @@ export class MaterializationService {
             instructions,
             carried,
             signal,
+            opts.strictUpstreams ?? false,
          );
 
          const sourcesBuilt = instructions.length;
@@ -450,6 +463,26 @@ export class MaterializationService {
       return { instructions, carried };
    }
 
+   /**
+    * Project the caller-supplied upstream reference manifest into the seed
+    * entry map `executeInstructedBuild` consumes. Each reference is keyed by the
+    * compiler's manifest-lookup sourceEntityId and carries only the physical
+    * table name — enough for the build Manifest to resolve a downstream persist
+    * reference to the existing table without rebuilding the upstream.
+    */
+   private referenceManifestToEntries(
+      referenceManifest: ManifestReference[] | undefined,
+   ): Record<string, ManifestEntry> {
+      const entries: Record<string, ManifestEntry> = {};
+      for (const ref of referenceManifest ?? []) {
+         entries[ref.sourceEntityId] = {
+            sourceEntityId: ref.sourceEntityId,
+            physicalTableName: ref.physicalTableName,
+         };
+      }
+      return entries;
+   }
+
    /**
     * Entries of the most recent successful (MANIFEST_FILE_READY) materialization
     * for this package, used for skip-if-unchanged. Excludes the in-flight run.
@@ -565,6 +598,7 @@ export class MaterializationService {
       instructions: BuildInstruction[],
       seedEntries: Record<string, ManifestEntry>,
       signal: AbortSignal,
+      strict = false,
    ): Promise<Record<string, ManifestEntry>> {
       const { graphs, sources, connectionDigests, connections } = compiled;
 
@@ -587,8 +621,12 @@ export class MaterializationService {
 
       // Accumulates physical names as sources are built so downstream sources
       // resolve their upstream references to the freshly-assigned tables. Seed
-      // it with carried-forward entries so reused upstreams resolve too.
+      // it with carried-forward entries so reused upstreams resolve too. In
+      // strict mode, an upstream persist reference that is neither built here
+      // nor seeded fails the compile (runtime-manifest-strict-miss) instead of
+      // silently recomputing live.
       const manifest = new Manifest();
+      manifest.strict = strict;
       const entries: Record<string, ManifestEntry> = {};
       for (const [sourceEntityId, entry] of Object.entries(seedEntries)) {
          if (entry.physicalTableName) {

package/src/service/materialization_test_fixtures.ts

@@ -75,14 +75,51 @@ export function makeInstruction(
  * build internals touch (name/id, deterministic sourceEntityId, SQL, and the
  * `#@ persist name=` annotation reader, defaulted to "unset").
  */
+/** A freshness layer for the fake source's `#@` or `##` tag. */
+interface FakeFreshnessSchedule {
+   freshness?: { window?: string; fallback?: 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`, for
+ * resolveFreshness).
+ */
+function fakeTag(
+   fields: Record<string, string> | undefined,
+   fs: FakeFreshnessSchedule | undefined,
+) {
+   return {
+      *entries() {
+         for (const [key, value] of Object.entries(fields ?? {})) {
+            yield [key, { text: () => value }];
+         }
+      },
+      text(...at: string[]): string | undefined {
+         if (at.length === 1) {
+            return fields?.[at[0]];
+         }
+         if (at.length === 2 && at[0] === "freshness") {
+            return fs?.freshness?.[at[1] as "window" | "fallback"];
+         }
+         return undefined;
+      },
+   };
+}
+
 export function fakeSource(opts: {
    name: string;
    sourceEntityId: string;
    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 (dotted keys). */
+   freshnessSchedule?: FakeFreshnessSchedule;
+   /** Model-file-level (`##`) freshness default. */
+   modelFreshnessSchedule?: FakeFreshnessSchedule;
 }): PersistSource {
    const fields = opts.annotationFields;
    return {
@@ -93,20 +130,14 @@ export function fakeSource(opts: {
       makeBuildId: () => opts.sourceEntityId,
       getSQL: () => opts.sql ?? "SELECT 1",
       annotations: {
-         parseAsTag: () =>
-            fields
-               ? {
-                    tag: {
-                       *entries() {
-                          for (const [key, value] of Object.entries(fields)) {
-                             yield [key, { text: () => value }];
-                          }
-                       },
-                    },
-                 }
-               : // No annotation fields: entries() is absent, and
-                 // deriveAnnotationFields degrades to {}.
-                 { tag: { text: () => undefined } },
+         parseAsTag: () => ({
+            tag: fakeTag(fields, opts.freshnessSchedule),
+         }),
+      },
+      modelAnnotations: {
+         parseAsTag: () => ({
+            tag: fakeTag(undefined, opts.modelFreshnessSchedule),
+         }),
       },
    } as unknown as PersistSource;
 }