@malloy-publisher/server 0.0.228 → 0.0.229

package/src/service/quoting.ts

@@ -43,3 +43,36 @@ export function quoteTablePath(tableName: string, dialect: string): string {
       .map((segment) => quoteIdentifier(segment, dialect))
       .join(".");
 }
+
+/**
+ * Whether a table path already carries a dialect quote character, in which case
+ * it is treated as canonical SQL that must not be re-quoted. The single
+ * definition of "already quoted" shared by every bind site.
+ */
+export function isQuotedIdentifierPath(tableName: string): boolean {
+   return tableName.includes('"') || tableName.includes("`");
+}
+
+/**
+ * Quote a physical table path for a manifest entry so a Malloy `FROM` resolves
+ * it correctly, unless it is already canonical SQL (passed through unchanged).
+ * This is the single quoting authority for the two places a physical name is
+ * bound into a `FROM`: the serve-side bind ({@link Package.quoteBoundTableNames})
+ * and the build-side manifest that stitches chained persist sources together
+ * (materialization_service). Both must mirror the CREATE side's
+ * {@link quoteTablePath} so a case-folding engine (Snowflake uppercases
+ * unquoted identifiers) can resolve the case-preserved table the builder wrote.
+ *
+ * Passing an already-quoted name through is safe for the names this handles:
+ * control-plane physical names are logical/unquoted (never contain a quote),
+ * and a self-assigned `#@ persist name=` value is the author's own canonical
+ * SQL (they own quoting it for the dialect).
+ */
+export function quoteManifestTablePath(
+   tableName: string,
+   dialect: string,
+): string {
+   return isQuotedIdentifierPath(tableName)
+      ? tableName
+      : quoteTablePath(tableName, dialect);
+}

package/src/storage/DatabaseInterface.ts

@@ -59,6 +59,14 @@ export interface ResourceRepository {
       packageName: string,
       options?: { limit?: number; offset?: number },
    ): Promise<Materialization[]>;
+   listMaterializationsByEnvironment(
+      environmentId: string,
+      options?: { limit?: number; offset?: number },
+   ): Promise<Materialization[]>;
+   getLatestScheduledFireAt(
+      environmentId: string,
+      packageName: string,
+   ): Promise<Date | null>;
    getMaterializationById(id: string): Promise<Materialization | null>;
    getActiveMaterialization(
       environmentId: string,
@@ -174,6 +182,13 @@ export interface BuildManifest {
  */
 export interface FreshnessAwareManifestEntry {
    tableName: string;
+   /**
+    * The connection the physical table lives on, carried from the wire
+    * manifest so the bind step can quote `tableName` for that connection's
+    * dialect (see Package.quoteBoundTableNames). Absent on entries whose
+    * producer didn't record it; those bind verbatim.
+    */
+   connectionName?: string;
    dataAsOf?: string;
    freshnessWindowSeconds?: number;
    freshnessFallback?: "live" | "stale_ok" | "fail";

package/src/storage/duckdb/DuckDBRepository.ts

@@ -153,6 +153,23 @@ export class DuckDBRepository implements ResourceRepository {
       return this.materializationRepo.list(environmentId, packageName, options);
    }
 
+   async listMaterializationsByEnvironment(
+      environmentId: string,
+      options?: { limit?: number; offset?: number },
+   ): Promise<Materialization[]> {
+      return this.materializationRepo.listByEnvironment(environmentId, options);
+   }
+
+   async getLatestScheduledFireAt(
+      environmentId: string,
+      packageName: string,
+   ): Promise<Date | null> {
+      return this.materializationRepo.getLatestScheduledFireAt(
+         environmentId,
+         packageName,
+      );
+   }
+
    async getMaterializationById(id: string): Promise<Materialization | null> {
       return this.materializationRepo.getById(id);
    }

package/src/storage/duckdb/MaterializationRepository.spec.ts

@@ -0,0 +1,154 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { DuckDBConnection } from "./DuckDBConnection";
+import { MaterializationRepository } from "./MaterializationRepository";
+import { initializeSchema } from "./schema";
+
+// Capture the SQL + params of the last query without touching a real DuckDB.
+function fakeRepo() {
+   const calls: Array<{ sql: string; params: unknown[] }> = [];
+   const db = {
+      all: async (sql: string, params: unknown[]) => {
+         calls.push({ sql, params });
+         return [];
+      },
+   } as unknown as DuckDBConnection;
+   return { repo: new MaterializationRepository(db), calls };
+}
+
+describe("MaterializationRepository list bounds", () => {
+   it("per-package list is unbounded when no limit is given (no LIMIT clause)", async () => {
+      const { repo, calls } = fakeRepo();
+      await repo.list("env-1", "pkg-a");
+      expect(calls[0].sql).not.toContain("LIMIT");
+      expect(calls[0].sql).not.toContain("OFFSET");
+      expect(calls[0].params).toEqual(["env-1", "pkg-a"]);
+   });
+
+   it("per-package list honors an explicit limit/offset", async () => {
+      const { repo, calls } = fakeRepo();
+      await repo.list("env-1", "pkg-a", { limit: 5, offset: 10 });
+      expect(calls[0].sql).toContain("LIMIT ?");
+      expect(calls[0].sql).toContain("OFFSET ?");
+      expect(calls[0].params).toEqual(["env-1", "pkg-a", 5, 10]);
+   });
+
+   it("environment-scoped list always applies a default cap (500)", async () => {
+      const { repo, calls } = fakeRepo();
+      await repo.listByEnvironment("env-1");
+      expect(calls[0].sql).toContain("LIMIT ?");
+      expect(calls[0].params).toEqual(["env-1", 500]);
+   });
+
+   it("environment-scoped list honors an explicit limit over the default", async () => {
+      const { repo, calls } = fakeRepo();
+      await repo.listByEnvironment("env-1", { limit: 25 });
+      expect(calls[0].params).toEqual(["env-1", 25]);
+   });
+});
+
+// The restart-recovery anchor (MaterializationScheduler.recoveryAnchor) hangs on
+// getLatestScheduledFireAt's `json_extract_string(metadata,'$.trigger')` filter,
+// which a fake db can't exercise. Drive the real query against an in-memory
+// DuckDB so the trigger filter and ORDER BY are covered, not just the SQL shape.
+describe("MaterializationRepository.getLatestScheduledFireAt (real DuckDB)", () => {
+   const ENV_ID = "env-sched";
+   const PKG = "pkg-a";
+   const dbs: DuckDBConnection[] = [];
+
+   afterEach(async () => {
+      while (dbs.length) await dbs.pop()!.close();
+   });
+
+   async function freshRepo(): Promise<{
+      db: DuckDBConnection;
+      repo: MaterializationRepository;
+   }> {
+      const db = new DuckDBConnection(":memory:");
+      dbs.push(db);
+      await db.initialize();
+      await initializeSchema(db);
+      // materializations.environment_id is a FK to environments(id).
+      await db.run(
+         `INSERT INTO environments (id, name, path, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?)`,
+         [
+            ENV_ID,
+            "sched-env",
+            "/tmp/sched-env",
+            "2026-01-01T00:00:00.000Z",
+            "2026-01-01T00:00:00.000Z",
+         ],
+      );
+      return { db, repo: new MaterializationRepository(db) };
+   }
+
+   // Insert a terminal run directly (active_key NULL so repeated inserts for the
+   // same package don't trip the unique active-key index). `trigger === undefined`
+   // stores metadata NULL; `null` stores a trigger-less object; a string stores
+   // that trigger.
+   async function insertRun(
+      db: DuckDBConnection,
+      id: string,
+      createdAt: string,
+      trigger: string | null | undefined,
+   ): Promise<void> {
+      const metadata =
+         trigger === undefined
+            ? null
+            : JSON.stringify(
+                 trigger === null ? { note: "manual" } : { trigger },
+              );
+      await db.run(
+         `INSERT INTO materializations
+            (id, environment_id, package_name, status, active_key, metadata, manifest, created_at, updated_at)
+          VALUES (?, ?, ?, 'MANIFEST_FILE_READY', NULL, ?, NULL, ?, ?)`,
+         [id, ENV_ID, PKG, metadata, createdAt, createdAt],
+      );
+   }
+
+   const day = (d: string) => `2026-${d}T12:00:00.000Z`;
+
+   it("returns the created_at of the newest SCHEDULER run", async () => {
+      const { db, repo } = await freshRepo();
+      await insertRun(db, "s1", day("01-15"), "SCHEDULER");
+      await insertRun(db, "s2", day("03-15"), "SCHEDULER");
+      const at = await repo.getLatestScheduledFireAt(ENV_ID, PKG);
+      expect(at).not.toBeNull();
+      expect(at!.toISOString().slice(0, 10)).toBe("2026-03-15");
+   });
+
+   it("ignores ON_DEMAND and trigger-less runs even when they are newer", async () => {
+      const { db, repo } = await freshRepo();
+      await insertRun(db, "s1", day("02-01"), "SCHEDULER"); // the only match
+      await insertRun(db, "d1", day("06-01"), "ON_DEMAND"); // newer, wrong trigger
+      await insertRun(db, "n1", day("07-01"), null); // newer, no trigger key
+      await insertRun(db, "m1", day("08-01"), undefined); // newer, metadata NULL
+      const at = await repo.getLatestScheduledFireAt(ENV_ID, PKG);
+      expect(at).not.toBeNull();
+      expect(at!.toISOString().slice(0, 10)).toBe("2026-02-01");
+   });
+
+   it("returns null when the package has no SCHEDULER run", async () => {
+      const { db, repo } = await freshRepo();
+      await insertRun(db, "d1", day("06-01"), "ON_DEMAND");
+      await insertRun(db, "m1", day("07-01"), undefined);
+      expect(await repo.getLatestScheduledFireAt(ENV_ID, PKG)).toBeNull();
+   });
+
+   it("scopes to the requested package (ignores another package's SCHEDULER run)", async () => {
+      const { db, repo } = await freshRepo();
+      await db.run(
+         `INSERT INTO materializations
+            (id, environment_id, package_name, status, active_key, metadata, manifest, created_at, updated_at)
+          VALUES (?, ?, 'other-pkg', 'MANIFEST_FILE_READY', NULL, ?, NULL, ?, ?)`,
+         [
+            "x1",
+            ENV_ID,
+            JSON.stringify({ trigger: "SCHEDULER" }),
+            day("09-01"),
+            day("09-01"),
+         ],
+      );
+      expect(await repo.getLatestScheduledFireAt(ENV_ID, PKG)).toBeNull();
+   });
+});

package/src/storage/duckdb/MaterializationRepository.ts

@@ -22,6 +22,15 @@ function activeKeyFor(environmentId: string, packageName: string): string {
    return `${environmentId}|${packageName}`;
 }
 
+/**
+ * Default cap for the environment-wide materialization list. That query spans
+ * every package in the environment, so on a busy env (e.g. a frequent schedule)
+ * the history grows without bound; when a caller passes no explicit limit, fall
+ * back to this bound rather than loading and serializing every row. Callers that
+ * page (the SDK "show more") always pass their own limit and are unaffected.
+ */
+const DEFAULT_ENVIRONMENT_LIST_LIMIT = 500;
+
 /**
  * Thrown when an atomic insert loses a race on (environment, package) active
  * materialization. Surfaced separately from a generic DB error so the service
@@ -53,6 +62,10 @@ export class MaterializationRepository {
       return new Date();
    }
 
+   // Per-package list: intentionally UNBOUNDED when no limit is passed —
+   // existing callers may rely on the full history for a single package. Only
+   // the environment-wide `listByEnvironment` (which spans every package)
+   // applies a default cap; do not add one here.
    async list(
       environmentId: string,
       packageName: string,
@@ -73,6 +86,49 @@ export class MaterializationRepository {
       return rows.map(this.mapRow);
    }
 
+   /** All materializations across every package in an environment, newest first. */
+   async listByEnvironment(
+      environmentId: string,
+      options?: { limit?: number; offset?: number },
+   ): Promise<Materialization[]> {
+      let sql =
+         "SELECT * FROM materializations WHERE environment_id = ? ORDER BY created_at DESC";
+      const params: unknown[] = [environmentId];
+      // Always bound the result: an uncapped env-wide fetch is unbounded.
+      sql += " LIMIT ?";
+      params.push(options?.limit ?? DEFAULT_ENVIRONMENT_LIST_LIMIT);
+      if (options?.offset !== undefined) {
+         sql += " OFFSET ?";
+         params.push(options.offset);
+      }
+      const rows = await this.db.all<Record<string, unknown>>(sql, params);
+      return rows.map(this.mapRow);
+   }
+
+   /**
+    * `created_at` of the newest scheduler-fired (metadata.trigger=SCHEDULER)
+    * materialization for (env, package), or null if none. The standalone
+    * scheduler uses this to recover a missed occurrence across a restart:
+    * re-anchoring `nextFireAt` to `nextAfter(lastScheduledFire)` fires exactly
+    * one catch-up after downtime (then jumps forward), rather than skipping the
+    * occurrence entirely. `metadata` is a JSON column, so the trigger is read
+    * with `json_extract_string`.
+    */
+   async getLatestScheduledFireAt(
+      environmentId: string,
+      packageName: string,
+   ): Promise<Date | null> {
+      const row = await this.db.get<{ created_at: unknown }>(
+         `SELECT created_at FROM materializations
+           WHERE environment_id = ? AND package_name = ?
+             AND json_extract_string(metadata, '$.trigger') = 'SCHEDULER'
+           ORDER BY created_at DESC
+           LIMIT 1`,
+         [environmentId, packageName],
+      );
+      return row?.created_at ? new Date(row.created_at as string) : null;
+   }
+
    async getById(id: string): Promise<Materialization | null> {
       const row = await this.db.get<Record<string, unknown>>(
          "SELECT * FROM materializations WHERE id = ?",

package/tests/fixtures/persist-schedule-test/data/orders.csv

@@ -0,0 +1,5 @@
+category,amount
+electronics,100
+clothing,50
+electronics,200
+clothing,75

package/tests/fixtures/persist-schedule-test/persist_schedule_test.malloy

@@ -0,0 +1,11 @@
+##! experimental.persistence
+
+source: raw_orders is duckdb.table('data/orders.csv')
+
+#@ persist name="order_summary"
+source: order_summary is raw_orders -> {
+  group_by: category
+  aggregate:
+    total_orders is count()
+    total_revenue is amount.sum()
+}

package/tests/fixtures/persist-schedule-test/publisher.json

@@ -0,0 +1,7 @@
+{
+  "name": "persist-schedule-test",
+  "version": "1.0.0",
+  "description": "DuckDB persist fixture with a version-scoped materialization schedule",
+  "scope": "version",
+  "materialization": { "schedule": "0 6 * * *" }
+}

package/tests/fixtures/persist-schedule-warn-test/data/orders.csv

@@ -0,0 +1,5 @@
+category,amount
+electronics,100
+clothing,50
+electronics,200
+clothing,75

package/tests/fixtures/persist-schedule-warn-test/persist_warn_test.malloy

@@ -0,0 +1,11 @@
+##! experimental.persistence
+
+source: raw_orders is duckdb.table('data/orders.csv')
+
+#@ persist name="order_summary"
+source: order_summary is raw_orders -> {
+  group_by: category
+  aggregate:
+    total_orders is count()
+    total_revenue is amount.sum()
+}

package/tests/fixtures/persist-schedule-warn-test/publisher.json

@@ -0,0 +1,6 @@
+{
+   "name": "persist-schedule-warn-test",
+   "version": "1.0.0",
+   "description": "DuckDB persist fixture with a schedule but no version scope — a load-tolerated persistence-policy warning (schedule requires scope: version)",
+   "materialization": { "schedule": "0 6 * * *" }
+}

package/tests/integration/materialization/environment_list.integration.spec.ts

@@ -0,0 +1,133 @@
+/// <reference types="bun-types" />
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import path from "path";
+import { fileURLToPath } from "url";
+import { RestE2EEnv, startRestE2E } from "../../harness/rest_e2e";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PROJECT = "env-mat-list-project";
+const PKG_A = "persist-test";
+const PKG_B = "persist-schedule-test";
+const ENV_MATS_PATH = `/api/v0/environments/${PROJECT}/packages/materializations`;
+
+// Verifies the environment-scoped list:
+// GET /environments/{env}/packages/materializations returns runs from every
+// package in the env, newest-first, each labeled with its packageName.
+describe("Environment-scoped materialization list", () => {
+   let env: (RestE2EEnv & { stop(): Promise<void> }) | null = null;
+   let baseUrl: string;
+
+   const fixture = (name: string) =>
+      path.resolve(__dirname, `../../fixtures/${name}`);
+
+   async function createAndFinish(pkg: string): Promise<string> {
+      const res = await fetch(
+         `${baseUrl}/api/v0/environments/${PROJECT}/packages/${pkg}/materializations`,
+         {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ forceRefresh: true }),
+         },
+      );
+      expect(res.status).toBe(201);
+      const created = (await res.json()) as { id: string };
+      const deadline = Date.now() + 60_000;
+      while (Date.now() < deadline) {
+         const poll = await fetch(
+            `${baseUrl}/api/v0/environments/${PROJECT}/packages/${pkg}/materializations/${created.id}`,
+         );
+         const m = (await poll.json()) as { status: string };
+         if (
+            ["MANIFEST_FILE_READY", "FAILED", "CANCELLED"].includes(m.status)
+         ) {
+            break;
+         }
+         await new Promise((r) => setTimeout(r, 250));
+      }
+      return created.id;
+   }
+
+   beforeAll(async () => {
+      env = await startRestE2E();
+      baseUrl = env.baseUrl;
+
+      const createRes = await fetch(`${baseUrl}/api/v0/environments`, {
+         method: "POST",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({
+            name: PROJECT,
+            packages: [
+               { name: PKG_A, location: fixture(PKG_A) },
+               { name: PKG_B, location: fixture(PKG_B) },
+            ],
+            connections: [],
+         }),
+      });
+      if (!createRes.ok) {
+         throw new Error(
+            `Failed to create project (${createRes.status}): ${await createRes.text()}`,
+         );
+      }
+
+      // Wait for both packages to load.
+      for (const pkg of [PKG_A, PKG_B]) {
+         const deadline = Date.now() + 30_000;
+         while (Date.now() < deadline) {
+            const res = await fetch(
+               `${baseUrl}/api/v0/environments/${PROJECT}/packages/${pkg}`,
+            );
+            if (res.ok) break;
+            await new Promise((r) => setTimeout(r, 500));
+         }
+      }
+   });
+
+   afterAll(async () => {
+      if (baseUrl) {
+         try {
+            await fetch(`${baseUrl}/api/v0/environments/${PROJECT}`, {
+               method: "DELETE",
+            });
+         } catch {
+            // best-effort
+         }
+      }
+      await env?.stop();
+      env = null;
+   });
+
+   it("returns materializations from every package in the environment", async () => {
+      await createAndFinish(PKG_A);
+      await createAndFinish(PKG_B);
+
+      const res = await fetch(`${baseUrl}${ENV_MATS_PATH}`);
+      expect(res.status).toBe(200);
+      const rows = (await res.json()) as Array<{
+         packageName: string;
+         createdAt?: string;
+      }>;
+
+      const packages = new Set(rows.map((r) => r.packageName));
+      expect(packages.has(PKG_A)).toBe(true);
+      expect(packages.has(PKG_B)).toBe(true);
+
+      // Newest-first ordering.
+      const times = rows
+         .map((r) => (r.createdAt ? new Date(r.createdAt).getTime() : 0))
+         .filter((t) => t > 0);
+      const sorted = [...times].sort((a, b) => b - a);
+      expect(times).toEqual(sorted);
+   });
+
+   it("does not shadow the per-package list route", async () => {
+      const res = await fetch(
+         `${baseUrl}/api/v0/environments/${PROJECT}/packages/${PKG_A}/materializations`,
+      );
+      expect(res.status).toBe(200);
+      const rows = (await res.json()) as Array<{ packageName: string }>;
+      expect(rows.every((r) => r.packageName === PKG_A)).toBe(true);
+   });
+});

package/tests/integration/materialization/materialization_lifecycle.integration.spec.ts

@@ -346,9 +346,14 @@ describe("Materialization REST API: single-call (E2E)", () => {
             const routedExecuted = await executedSql();
             const routedCompiled = await compiledSql();
             expect(routedExecuted).not.toContain("data/orders.csv");
-            expect(routedExecuted).toContain("order_summary");
             expect(routedCompiled).not.toContain("data/orders.csv");
-            expect(routedCompiled).toContain("order_summary");
+            // The bound table is referenced QUOTED for the connection's dialect,
+            // byte-compatible with the CREATE side's quoteTablePath: a
+            // case-folding engine (Snowflake uppercases unquoted identifiers)
+            // can only resolve the case-preserved created table through the
+            // same quoting (Package.quoteBoundTableNames).
+            expect(routedExecuted).toContain('"order_summary"');
+            expect(routedCompiled).toContain('"order_summary"');
 
             // Cleanup: drop the table + record, then reload back to live so the
             // dangling binding doesn't leak into later groups.

package/tests/integration/materialization/orchestrated_rebind.integration.spec.ts

@@ -0,0 +1,150 @@
+/// <reference types="bun-types" />
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import fsp from "fs/promises";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { RestE2EEnv, startRestE2E } from "../../harness/rest_e2e";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const PROJECT_NAME = "rebind-safety-project";
+const PACKAGE_NAME = "persist-schedule-warn-test";
+const API = `/api/v0/environments/${PROJECT_NAME}/packages/${PACKAGE_NAME}`;
+
+// Guards the orchestrated control plane's post-build rebind PATCH against the
+// editable-policy gate added in this PR. The fixture loads with a pre-existing,
+// load-tolerated persistence-policy warning (a schedule without scope: version),
+// so if the policy gate ran on a rebind PATCH it would reject and fail the
+// orchestrated run. These tests assert it does not: a manifestLocation-only
+// PATCH, and a PATCH carrying explicit scope: null / materialization: null, both
+// succeed and leave scope/materialization untouched (null == absent, not a wipe).
+describe("Orchestrated rebind PATCH safety", () => {
+   let env: (RestE2EEnv & { stop(): Promise<void> }) | null = null;
+   let baseUrl: string;
+
+   beforeAll(async () => {
+      env = await startRestE2E();
+      baseUrl = env.baseUrl;
+
+      const fixtureDir = path.resolve(
+         __dirname,
+         "../../fixtures/persist-schedule-warn-test",
+      );
+      const createRes = await fetch(`${baseUrl}/api/v0/environments`, {
+         method: "POST",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({
+            name: PROJECT_NAME,
+            packages: [{ name: PACKAGE_NAME, location: fixtureDir }],
+            connections: [],
+         }),
+      });
+      if (!createRes.ok) {
+         throw new Error(
+            `Failed to create test project (${createRes.status}): ${await createRes.text()}`,
+         );
+      }
+
+      const deadline = Date.now() + 30_000;
+      while (Date.now() < deadline) {
+         const res = await fetch(`${baseUrl}${API}`);
+         if (res.ok) break;
+         await new Promise((r) => setTimeout(r, 500));
+      }
+   });
+
+   afterAll(async () => {
+      if (baseUrl) {
+         try {
+            await fetch(`${baseUrl}/api/v0/environments/${PROJECT_NAME}`, {
+               method: "DELETE",
+            });
+         } catch {
+            // best-effort
+         }
+      }
+      await env?.stop();
+      env = null;
+   });
+
+   async function getPackage(): Promise<Record<string, unknown>> {
+      const res = await fetch(`${baseUrl}${API}`);
+      expect(res.status).toBe(200);
+      return (await res.json()) as Record<string, unknown>;
+   }
+
+   function scheduleOf(
+      pkg: Record<string, unknown>,
+   ): string | null | undefined {
+      return (pkg.materialization as { schedule?: string | null } | null)
+         ?.schedule;
+   }
+
+   it("loads the fixture despite its load-tolerated policy warning", async () => {
+      // scope defaults to "package" (no scope in the fixture), and the schedule
+      // is present — the exact combination that warns but is load-tolerated.
+      const pkg = await getPackage();
+      expect(pkg.scope ?? "package").toBe("package");
+      expect(scheduleOf(pkg)).toBe("0 6 * * *");
+   });
+
+   it("a manifestLocation-only rebind PATCH succeeds and preserves scope/materialization", async () => {
+      const manifestFile = path.join(
+         os.tmpdir(),
+         `rebind-empty-manifest-${PROJECT_NAME}.json`,
+      );
+      await fsp.writeFile(
+         manifestFile,
+         JSON.stringify({
+            builtAt: new Date(0).toISOString(),
+            strict: false,
+            entries: {},
+         }),
+         "utf8",
+      );
+
+      // The control plane's finalize PATCH: name/manifestLocation only, no
+      // scope/materialization keys. Must not run the policy gate.
+      const res = await fetch(`${baseUrl}${API}`, {
+         method: "PATCH",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({
+            name: PACKAGE_NAME,
+            manifestLocation: manifestFile,
+         }),
+      });
+      expect(res.ok).toBe(true);
+
+      const pkg = await getPackage();
+      expect(pkg.scope ?? "package").toBe("package");
+      expect(scheduleOf(pkg)).toBe("0 6 * * *");
+
+      // Reset the binding so the next test starts from the live package.
+      await fetch(`${baseUrl}${API}`, {
+         method: "PATCH",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({ name: PACKAGE_NAME, manifestLocation: null }),
+      });
+   });
+
+   it("a PATCH with explicit scope: null / materialization: null preserves both (null == absent, no wipe, no reject)", async () => {
+      const res = await fetch(`${baseUrl}${API}`, {
+         method: "PATCH",
+         headers: { "Content-Type": "application/json" },
+         body: JSON.stringify({
+            name: PACKAGE_NAME,
+            scope: null,
+            materialization: null,
+         }),
+      });
+      // The gate must treat null as absent: not rejected by the warning...
+      expect(res.ok).toBe(true);
+      // ...and the persisted policy is preserved, not wiped.
+      const pkg = await getPackage();
+      expect(pkg.scope ?? "package").toBe("package");
+      expect(scheduleOf(pkg)).toBe("0 6 * * *");
+   });
+});