@malloy-publisher/server 0.0.223 → 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/environment.ts

@@ -28,7 +28,7 @@ import {
    assertSafeRelativeModelPath,
    safeJoinUnderRoot,
 } from "../path_safety";
-import { BuildManifest } from "../storage/DatabaseInterface";
+import { FreshnessManifest } from "../storage/DatabaseInterface";
 import { URL_READER } from "../utils";
 import {
    buildEnvironmentMalloyConfig,
@@ -1119,7 +1119,7 @@ export class Environment {
     */
    public async reloadAllModelsForPackage(
       packageName: string,
-      manifest: BuildManifest["entries"],
+      manifest: FreshnessManifest,
    ): Promise<void> {
       assertSafePackageName(packageName);
       return this.withPackageLock(packageName, async () => {
@@ -1193,7 +1193,7 @@ export class Environment {
     */
    private async fetchManifestEntriesWithTimeout(
       manifestLocation: string,
-   ): Promise<BuildManifest["entries"]> {
+   ): Promise<FreshnessManifest> {
       let timer: ReturnType<typeof setTimeout> | undefined;
       const timeout = new Promise<never>((_, reject) => {
          timer = setTimeout(

package/src/service/freshness.spec.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "bun:test";
+
+import type {
+   FreshnessAwareManifestEntry,
+   FreshnessManifest,
+} from "../storage/DatabaseInterface";
+import { evaluateManifestFreshness, filterFreshManifest } from "./freshness";
+
+// A fixed "now" so age math is deterministic.
+const NOW = new Date("2026-07-07T12:00:00.000Z");
+const NOW_MS = NOW.getTime();
+
+/** dataAsOf `ageSeconds` before NOW. */
+function asOf(ageSeconds: number): string {
+   return new Date(NOW_MS - ageSeconds * 1000).toISOString();
+}
+
+describe("evaluateManifestFreshness", () => {
+   it("serves the table when un-gated (no window)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(1_000_000),
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_table");
+   });
+
+   it("serves the table when a window is declared but no dataAsOf anchor", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "live",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_table");
+   });
+
+   it("serves the table when fresh (age within window)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(1800),
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "live",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_table");
+   });
+
+   it("serves the table at the exact window boundary (age == window)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(3600),
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "live",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_table");
+   });
+
+   it("drops a stale entry with fallback live (=> serve live)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(7200),
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "live",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_live");
+   });
+
+   it("keeps a stale entry with fallback stale_ok (=> serve the stale table)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(7200),
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "stale_ok",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_table");
+   });
+
+   it("drops a stale entry with fallback fail (interim: serve live in v1)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(7200),
+         freshnessWindowSeconds: 3600,
+         freshnessFallback: "fail",
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_live");
+   });
+
+   it("drops a stale entry with no declared fallback (=> serve live)", () => {
+      const entry: FreshnessAwareManifestEntry = {
+         tableName: "t",
+         dataAsOf: asOf(7200),
+         freshnessWindowSeconds: 3600,
+      };
+      expect(evaluateManifestFreshness(entry, NOW)).toBe("serve_live");
+   });
+});
+
+describe("filterFreshManifest", () => {
+   it("includes fresh/un-gated/stale_ok and drops stale live/fail", () => {
+      const entries: FreshnessManifest = {
+         fresh: {
+            tableName: "fresh_t",
+            dataAsOf: asOf(1800),
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "live",
+         },
+         ungated: { tableName: "ungated_t", dataAsOf: asOf(999999) },
+         staleLive: {
+            tableName: "stale_live_t",
+            dataAsOf: asOf(7200),
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "live",
+         },
+         staleOk: {
+            tableName: "stale_ok_t",
+            dataAsOf: asOf(7200),
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "stale_ok",
+         },
+         staleFail: {
+            tableName: "stale_fail_t",
+            dataAsOf: asOf(7200),
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "fail",
+         },
+      };
+
+      const { manifest } = filterFreshManifest(entries, NOW);
+      expect(Object.keys(manifest).sort()).toEqual([
+         "fresh",
+         "staleOk",
+         "ungated",
+      ]);
+      expect(manifest.fresh).toEqual({ tableName: "fresh_t" });
+      expect(manifest.staleOk).toEqual({ tableName: "stale_ok_t" });
+      expect(manifest.ungated).toEqual({ tableName: "ungated_t" });
+   });
+
+   it("reports the earliest future window-crossing as nextStaleSince", () => {
+      const entries: FreshnessManifest = {
+         a: {
+            tableName: "a_t",
+            dataAsOf: asOf(1800), // window 3600 => flips at NOW + 1800s
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "live",
+         },
+         b: {
+            tableName: "b_t",
+            dataAsOf: asOf(1000), // window 3600 => flips at NOW + 2600s (later)
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "live",
+         },
+      };
+
+      const { nextStaleSince } = filterFreshManifest(entries, NOW);
+      // Earliest flip is entry a: dataAsOf(a) + window.
+      expect(nextStaleSince).toBe(NOW_MS - 1800 * 1000 + 3600 * 1000);
+   });
+
+   it("kept stale_ok entries do not set a future nextStaleSince", () => {
+      const entries: FreshnessManifest = {
+         staleOk: {
+            tableName: "stale_ok_t",
+            dataAsOf: asOf(7200),
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "stale_ok",
+         },
+      };
+      const { manifest, nextStaleSince } = filterFreshManifest(entries, NOW);
+      expect(Object.keys(manifest)).toEqual(["staleOk"]);
+      // Its window crossing is already in the past, so nothing schedules a
+      // future recompute.
+      expect(nextStaleSince).toBeNull();
+   });
+
+   it("returns null nextStaleSince when nothing is gated", () => {
+      const entries: FreshnessManifest = {
+         a: { tableName: "a_t" },
+         b: { tableName: "b_t", dataAsOf: asOf(10) },
+      };
+      const { manifest, nextStaleSince } = filterFreshManifest(entries, NOW);
+      expect(Object.keys(manifest).sort()).toEqual(["a", "b"]);
+      expect(nextStaleSince).toBeNull();
+   });
+});

package/src/service/freshness.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-query freshness gate for persisted sources (persistence.md §9.3, §14
+ * Phase B). A query on a `#@ persist` source may use its materialized table
+ * only while that table is within its declared freshness window; otherwise the
+ * query does what the source's `fallback` says.
+ *
+ * Two settled design principles anchor this (do not re-derive them the easy
+ * way):
+ *
+ *  1. Enforce per query, not at bind. Filtering stale entries once when the
+ *     manifest is bound would let a table that crosses its window while the
+ *     package stays loaded keep serving stale. The serve path re-evaluates
+ *     freshness on every query.
+ *  2. Clock on `dataAsOf`, not build completion. The window is a deadline on
+ *     *data* age; the anchor is the artifact's data-as-of instant (snapshot
+ *     start) supplied by the control plane. `age = now - dataAsOf`.
+ *
+ * Scope: `live`/`stale_ok` are fully publisher-side. `fail` degrades to
+ * serve-live in this first cut (the entry is dropped like `live`); the airtight
+ * `fail` path — which must *error* a query that joins a stale persist source —
+ * is a gated forked-malloy follow-up and is not built here.
+ */
+
+import {
+   BuildManifest,
+   FreshnessAwareManifestEntry,
+   FreshnessManifest,
+} from "../storage/DatabaseInterface";
+
+/**
+ * What to do with a single manifest entry at query time.
+ *  - `serve_table`: substitute the materialized table (include `{ tableName }`).
+ *  - `serve_live`:  drop the entry so `strict:false` falls through to live SQL.
+ *
+ * `fail` collapses to `serve_live` in v1 (see module note).
+ */
+export type FreshnessDecision = "serve_table" | "serve_live";
+
+/**
+ * Evaluate one entry against `now`. An entry with no `freshnessWindowSeconds`
+ * is un-gated (always serve the table). A fresh entry (age within window) is
+ * served. A stale entry serves its table only under `stale_ok`; `live` and
+ * `fail` both drop to live in this first cut.
+ */
+export function evaluateManifestFreshness(
+   entry: FreshnessAwareManifestEntry,
+   now: Date,
+): FreshnessDecision {
+   // Un-gated: no declared window ⇒ never stale. Also the rollout-safe default
+   // before the control plane starts stamping the freshness fields.
+   if (entry.freshnessWindowSeconds == null) return "serve_table";
+   // A window without an anchor can't be evaluated; treat as un-gated rather
+   // than tripping every query (matches "absent ⇒ never stale").
+   if (entry.dataAsOf == null) return "serve_table";
+   const dataAsOfMs = Date.parse(entry.dataAsOf);
+   if (Number.isNaN(dataAsOfMs)) return "serve_table";
+   const ageSeconds = (now.getTime() - dataAsOfMs) / 1000;
+   const stale = ageSeconds > entry.freshnessWindowSeconds;
+   if (!stale) return "serve_table";
+   return entry.freshnessFallback === "stale_ok" ? "serve_table" : "serve_live";
+}
+
+/**
+ * The instant a currently-fresh, gated entry will cross its window
+ * (`dataAsOf + window`), or `null` when the entry has no evaluable window
+ * (un-gated). Used to compute the next memo-invalidation instant.
+ */
+function staleSinceMs(entry: FreshnessAwareManifestEntry): number | null {
+   if (entry.freshnessWindowSeconds == null || entry.dataAsOf == null) {
+      return null;
+   }
+   const dataAsOfMs = Date.parse(entry.dataAsOf);
+   if (Number.isNaN(dataAsOfMs)) return null;
+   return dataAsOfMs + entry.freshnessWindowSeconds * 1000;
+}
+
+/**
+ * Compute the freshness-filtered Malloy build manifest for `now` from the full
+ * retained wire entries.
+ *
+ * Returns the `sourceEntityId -> { tableName }` map of entries that should
+ * substitute their materialized table (fresh, un-gated, or stale-`stale_ok`),
+ * plus `nextStaleSince`: the earliest future instant a currently-included,
+ * gated entry will cross its window. Because age only ever grows, the
+ * fresh→stale transition is one-way, so a single `nextStaleSince` instant is a
+ * sufficient memo-invalidation deadline — no per-entry heap is needed. `null`
+ * means no included entry has an evaluable window, so the result never changes
+ * until the entries are replaced (rebind).
+ */
+export function filterFreshManifest(
+   entries: FreshnessManifest,
+   now: Date,
+): { manifest: BuildManifest["entries"]; nextStaleSince: number | null } {
+   const manifest: BuildManifest["entries"] = {};
+   let nextStaleSince: number | null = null;
+   const nowMs = now.getTime();
+
+   for (const [sourceEntityId, entry] of Object.entries(entries)) {
+      if (evaluateManifestFreshness(entry, now) === "serve_live") continue;
+      manifest[sourceEntityId] = { tableName: entry.tableName };
+
+      // Only currently-fresh gated entries can flip later; a kept stale
+      // `stale_ok` entry (staleSince already in the past) never changes again.
+      const flipAt = staleSinceMs(entry);
+      if (flipAt != null && flipAt > nowMs) {
+         nextStaleSince =
+            nextStaleSince == null ? flipAt : Math.min(nextStaleSince, flipAt);
+      }
+   }
+
+   return { manifest, nextStaleSince };
+}

package/src/service/manifest_loader.spec.ts

@@ -46,6 +46,39 @@ describe("fetchManifestEntries", () => {
       });
    });
 
+   it("carries the control-plane freshness fields verbatim", async () => {
+      const dataAsOf = "2026-07-07T00:00:00.000Z";
+      const file = await writeManifest({
+         entries: {
+            gated: {
+               sourceEntityId: "gated",
+               physicalTableName: "schema.gated_mz",
+               dataAsOf,
+               freshnessWindowSeconds: 3600,
+               freshnessFallback: "stale_ok",
+            },
+            ungated: {
+               sourceEntityId: "ungated",
+               physicalTableName: "schema.ungated_mz",
+            },
+         },
+      });
+
+      const entries = await fetchManifestEntries(file);
+
+      // Filter-free: freshness fields are retained for the serve-path gate; a
+      // window-less entry is left un-gated.
+      expect(entries).toEqual({
+         gated: {
+            tableName: "schema.gated_mz",
+            dataAsOf,
+            freshnessWindowSeconds: 3600,
+            freshnessFallback: "stale_ok",
+         },
+         ungated: { tableName: "schema.ungated_mz" },
+      });
+   });
+
    it("reads via a file:// URI", async () => {
       const file = await writeManifest({
          entries: { b1: { sourceEntityId: "b1", physicalTableName: "t1" } },