@malloy-publisher/server 0.0.224 → 0.0.225

package/src/service/build_plan.spec.ts

@@ -10,6 +10,7 @@ import {
    deriveBuildPlan,
    flattenDependsOn,
    iterGraphSources,
+   resolveFreshnessSchedule,
    resolvePackageConnections,
 } from "./build_plan";
 import { fakeSource } from "./materialization_test_fixtures";
@@ -296,6 +297,124 @@ describe("deriveBuildPlan", () => {
    });
 });
 
+describe("resolveFreshnessSchedule", () => {
+   it("reports source-level freshness + schedule verbatim", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: {
+            freshness: { window: "1h", fallback: "stale_ok" },
+            schedule: "0 */6 * * *",
+         },
+      });
+      expect(resolveFreshnessSchedule(source, null)).toEqual({
+         freshness: { window: "1h", fallback: "stale_ok" },
+         schedule: "0 */6 * * *",
+      });
+   });
+
+   it("returns null for both when unset at every level", () => {
+      const source = fakeSource({ name: "s", sourceEntityId: "bid" });
+      expect(resolveFreshnessSchedule(source, null)).toEqual({
+         freshness: null,
+         schedule: null,
+      });
+   });
+
+   it("falls back to model-file then package per field (most-specific-wins)", () => {
+      // freshness.window from source, freshness.fallback from model-file. The
+      // package-level cron is NOT inherited as the source's effective schedule;
+      // schedule here comes only from the source's own model-file default.
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: { freshness: { window: "1h" } },
+         modelFreshnessSchedule: {
+            freshness: { fallback: "fail" },
+            schedule: "0 3 * * *",
+         },
+      });
+      const pkg = {
+         schedule: "0 0 * * *",
+         freshness: { window: "24h", fallback: "live" as const },
+      };
+      expect(resolveFreshnessSchedule(source, pkg)).toEqual({
+         freshness: { window: "1h", fallback: "fail" },
+         schedule: "0 3 * * *",
+      });
+   });
+
+   it("does not inherit the package-level cron as the source's schedule", () => {
+      const source = fakeSource({ name: "s", sourceEntityId: "bid" });
+      const pkg = { schedule: "0 0 * * *", freshness: { window: "24h" } };
+      // Freshness inherits from the package; schedule stays null (the package
+      // cron is gated separately, not folded into the per-source cron).
+      expect(resolveFreshnessSchedule(source, pkg)).toEqual({
+         freshness: { window: "24h" },
+         schedule: null,
+      });
+   });
+
+   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(resolveFreshnessSchedule(source, pkg)).toEqual({
+         freshness: { window: "24h" },
+         schedule: null,
+      });
+   });
+
+   it("drops an invalid fallback rather than defaulting it", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         freshnessSchedule: { freshness: { window: "1h", fallback: "bogus" } },
+      });
+      expect(resolveFreshnessSchedule(source, null)).toEqual({
+         freshness: { window: "1h" },
+         schedule: null,
+      });
+   });
+});
+
+describe("deriveBuildPlan freshness/schedule", () => {
+   it("projects the resolved per-source freshness + schedule onto the plan", () => {
+      const source = fakeSource({
+         name: "s",
+         sourceEntityId: "bid",
+         annotationFields: { name: "s_table", sharing: "private" },
+         freshnessSchedule: {
+            freshness: { window: "1h" },
+            schedule: "0 */6 * * *",
+         },
+      });
+      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; source schedule reported verbatim.
+      expect(plan.sources["s@m"].freshness).toEqual({
+         window: "1h",
+         fallback: "live",
+      });
+      expect(plan.sources["s@m"].schedule).toBe("0 */6 * * *");
+   });
+});
+
 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,25 @@ 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/schedule (all optional). */
+interface FreshnessScheduleLayer {
+   window?: string;
+   fallback?: FreshnessFallback;
+   schedule?: string;
+}
+
+/** 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 +47,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 +120,110 @@ export function deriveAnnotationFields(
    return out;
 }
 
+/**
+ * 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.
+ */
+function tagFreshnessScheduleLayer(
+   tag: ReadableTag | undefined,
+): FreshnessScheduleLayer {
+   if (!tag || typeof tag.text !== "function") return {};
+   const layer: FreshnessScheduleLayer = {};
+   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;
+   }
+   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).
+ */
+function packageFreshnessLayer(
+   cfg: WirePackageMaterialization | null | undefined,
+): Pick<FreshnessScheduleLayer, "window" | "fallback"> {
+   if (!cfg) return {};
+   const layer: Pick<FreshnessScheduleLayer, "window" | "fallback"> = {};
+   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 + 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.
+ */
+export function resolveFreshnessSchedule(
+   source: PersistSource,
+   packageMaterialization: WirePackageMaterialization | null | undefined,
+): { freshness: WireFreshness | null; schedule: string | null } {
+   const sourceLayer = tagFreshnessScheduleLayer(safeSourceTag(source));
+   const modelLayer = tagFreshnessScheduleLayer(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 };
+}
+
 /** Flatten Malloy's nested BuildNode.dependsOn into a list of sourceIDs. */
 export function flattenDependsOn(node: {
    dependsOn: { sourceID: string }[];
@@ -291,6 +421,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 +439,15 @@ 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
+      // (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,
+      );
       wireSources[sourceID] = {
          name: source.name,
          sourceID: source.sourceID,
@@ -323,6 +463,8 @@ export function deriveBuildPlan(
          // one that exists today.
          sharing: annotationFields.sharing ?? null,
          refresh: annotationFields.refresh ?? null,
+         freshness,
+         schedule,
          columns: deriveColumns(source),
          annotationFields,
          modelPath: sourceModelPaths?.[sourceID],
@@ -351,5 +493,6 @@ export async function computePackageBuildPlan(
       compiled.connectionDigests,
       undefined,
       compiled.sourceModelPaths,
+      pkg.getMaterializationConfig?.() ?? null,
    );
 }

package/src/service/materialization_cron_gate.spec.ts

@@ -7,17 +7,22 @@ import { Environment } from "./environment";
 import type { Package } from "./package";
 
 /**
- * The publish gate for the package-level materialization cron. At Phase B the
- * package-level cron (`materialization.schedule`) is replaced outright by
- * `materialization.freshness.window` (persistence.md §9.4), so ANY declared cron
- * is rejected regardless of the sources' sharing. The `sharing=private`
- * carve-out arrives whole with Phase A (persistence-phase-b-design.md §3.4);
- * until then there is no private artifact for a cron to own, so the B→A rule is
- * reject-all. These tests run a real `Environment` + `Package.create` over temp
- * dirs, so they also prove end-to-end that the pinned compiler ACCEPTS
- * `sharing=` / `refresh=` keys in the `#@ persist` annotation and that the
- * values survive to the wire build plan verbatim (unset stays null — never
- * defaulted to "shared").
+ * The 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 package-level cron (`materialization.schedule`) is valid only when
+ *    EVERY governed persist source resolves to explicit `sharing="private"`;
+ *  - a per-source cron (`#@ persist ... schedule=`) is valid only when THAT
+ *    source resolves to explicit `sharing="private"`;
+ *  - a cron on a shared/unset artifact is rejected, pointing at
+ *    `freshness.window` as the shared-tier replacement.
+ *
+ * These tests run a real `Environment` + `Package.create` over temp dirs, so
+ * they also prove end-to-end that the pinned compiler ACCEPTS `sharing=` /
+ * `refresh=` / `schedule=` / `freshness.*` keys in the `#@ persist` annotation
+ * and that the values survive to the wire build plan verbatim (unset stays null
+ * — never defaulted to "shared").
  */
 describe("materialization cron gate", () => {
    let rootDir: string;
@@ -76,6 +81,20 @@ source: a is duckdb.sql("SELECT 1 as x")
 
 #@ persist name="b_table" sharing=private refresh=full
 source: b is duckdb.sql("SELECT 2 as x")
+`;
+
+   // Per-source crons: valid on the private source, rejected on the shared and
+   // the unset (⇒ shared) sources.
+   const PER_SOURCE_CRON_MODEL = `##! experimental.persistence
+
+#@ persist name="p_table" sharing=private schedule="0 */6 * * *"
+source: p is duckdb.sql("SELECT 1 as x")
+
+#@ persist name="s_table" sharing=shared schedule="0 0 * * *"
+source: s is duckdb.sql("SELECT 2 as x")
+
+#@ persist name="u_table" schedule="0 0 * * *"
+source: u is duckdb.sql("SELECT 3 as x")
 `;
 
    it(
@@ -102,12 +121,13 @@ source: b is duckdb.sql("SELECT 2 as x")
    );
 
    it(
-      "rejects any declared cron, pointing at freshness.window",
+      "rejects a package cron on a mixed package, pointing at freshness.window",
       async () => {
+         // Phase A: a package cron governs every persist source, so it is valid
+         // only when all resolve to explicit private. MIXED has a shared and an
+         // unset source, so the package cron is rejected.
          const pkg = await loadPackage(MIXED_MODEL, "0 6 * * *");
 
-         // One actionable message for the whole package — the B→A rule is
-         // reject-all, not per-source.
          const warnings = pkg.scheduleWarnings();
          expect(warnings).toHaveLength(1);
          const joined = pkg.formatInvalidSchedule();
@@ -118,15 +138,34 @@ source: b is duckdb.sql("SELECT 2 as x")
    );
 
    it(
-      "rejects a declared cron even when every persist source is private",
+      "accepts a package cron when every persist source is private",
       async () => {
-         // The sharing=private carve-out arrives with Phase A; during B→A even
-         // an all-private package's cron is rejected outright.
+         // Phase A carve-out: an all-private package legitimately carries a
+         // package-level cron (the power tier for its own private artifacts).
          const pkg = await loadPackage(ALL_PRIVATE_MODEL, "0 6 * * *");
-         expect(pkg.scheduleWarnings()).toHaveLength(1);
-         expect(pkg.formatInvalidSchedule()).toContain(
-            "materialization.freshness.window",
-         );
+         expect(pkg.scheduleWarnings()).toEqual([]);
+      },
+      { timeout: 30000 },
+   );
+
+   it(
+      "rejects a per-source cron unless that source resolves to private",
+      async () => {
+         // No package cron here — only per-source `schedule=` declarations. The
+         // private source's cron is accepted; the shared and unset sources' are
+         // rejected, each pointing at freshness.window.
+         const pkg = await loadPackage(PER_SOURCE_CRON_MODEL);
+
+         const warnings = pkg.scheduleWarnings();
+         expect(warnings).toHaveLength(2);
+         const joined = warnings.join("\n");
+         expect(joined).toContain('"s"');
+         expect(joined).toContain('"u"');
+         expect(joined).not.toContain('"p"');
+         expect(joined).toContain("freshness.window");
+
+         // The resolved per-source schedule is surfaced verbatim on the plan.
+         expect(sourceByName(pkg, "p").schedule).toBe("0 */6 * * *");
       },
       { timeout: 30000 },
    );

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,6 +75,41 @@ 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. */
+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).
+ */
+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) {
+            if (at[0] === "schedule") return fs?.schedule;
+            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;
@@ -83,6 +118,10 @@ export function fakeSource(opts: {
    dialectName?: string;
    /** key=value fields of the `#@ persist` annotation (e.g. sharing). */
    annotationFields?: Record<string, string>;
+   /** Source-level (`#@`) freshness/schedule (dotted keys). */
+   freshnessSchedule?: FakeFreshnessSchedule;
+   /** Model-file-level (`##`) freshness/schedule default. */
+   modelFreshnessSchedule?: FakeFreshnessSchedule;
 }): PersistSource {
    const fields = opts.annotationFields;
    return {
@@ -93,20 +132,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;
 }