@malloy-publisher/server 0.0.234 → 0.0.236

package/src/service/freshness.spec.ts

@@ -1,183 +0,0 @@
-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

@@ -1,112 +0,0 @@
-/**
- * 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 };
-}