@malloy-publisher/server 0.0.219 → 0.0.221

package/src/controller/package.controller.ts

@@ -5,6 +5,30 @@ import { EnvironmentStore } from "../service/environment_store";
 
 type ApiPackage = components["schemas"]["Package"];
 
+/**
+ * Everything that is strict-at-publish, joined into one 400 message (or
+ * undefined when the package is publishable): invalid explores entries plus
+ * the materialization cron gate (a package-level `schedule` requires every
+ * persist source to resolve to explicit `sharing=private` — see
+ * Package.scheduleWarnings). At startup/reload both are warn-only instead
+ * (fail-safe; see Package.loadViaWorker).
+ */
+function formatPublishRejections(
+   pkg: {
+      formatInvalidExplores(exploresOverride?: string[]): string;
+      formatInvalidSchedule(): string;
+   },
+   exploresOverride?: string[],
+): string | undefined {
+   const message = [
+      pkg.formatInvalidExplores(exploresOverride),
+      pkg.formatInvalidSchedule(),
+   ]
+      .filter(Boolean)
+      .join("\n");
+   return message || undefined;
+}
+
 export class PackageController {
    private environmentStore: EnvironmentStore;
 
@@ -100,7 +124,7 @@ export class PackageController {
                   bodyLocation,
                   stagingPath,
                ),
-            (pkg) => pkg.formatInvalidExplores(),
+            (pkg) => formatPublishRejections(pkg),
          );
       } else {
          result = await environment.addPackage(packageName);
@@ -114,7 +138,7 @@ export class PackageController {
       }
 
       if (!body.location) {
-         const invalidMsg = result.formatInvalidExplores();
+         const invalidMsg = formatPublishRejections(result);
          if (invalidMsg) {
             await environment.unloadPackage(packageName).catch(() => {
                /* best-effort; the package is not persisted below */
@@ -177,7 +201,8 @@ export class PackageController {
                   stagingPath,
                ),
             (pkg) =>
-               pkg.formatInvalidExplores(
+               formatPublishRejections(
+                  pkg,
                   body.explores?.map(normalizeModelPath),
                ),
          );

package/src/controller/theme.controller.ts

@@ -0,0 +1,83 @@
+import { components } from "../api";
+import { sanitizeTheme, Theme } from "../config";
+import { BadRequestError, FrozenConfigError } from "../errors";
+import { isPublisherConfigFrozen } from "../config";
+import { ThemeStore } from "../service/theme_store";
+
+type ApiTheme = components["schemas"]["Theme"];
+
+/**
+ * Handlers for the in-app Theme Editor.
+ *
+ *   GET  /api/v0/theme  → current saved theme (or built-in default)
+ *   PUT  /api/v0/theme  → save the supplied theme
+ *   DELETE /api/v0/theme → reset to boot seed / built-in default
+ */
+export class ThemeController {
+   constructor(
+      private themeStore: ThemeStore,
+      private serverRoot: string,
+   ) {}
+
+   getTheme = async (): Promise<ApiTheme> => {
+      const theme = await this.themeStore.get();
+      // Always return an object so the client never has to deal with the
+      // null/undefined ambiguity. An empty object means "no overrides yet,
+      // use SDK defaults."
+      return theme ?? {};
+   };
+
+   /**
+    * PUT persists the supplied theme verbatim, including a literal `{}`.
+    * An empty `{}` is an intentional "clear all overrides" save: it writes
+    * an (empty) row so the boot seed from publisher.config.json's `theme`
+    * block is suppressed on subsequent loads. This deliberately differs
+    * from DELETE (resetTheme), which drops the row and lets that config
+    * seed re-apply. Note the persisted `"{}"` sanitizes back to `undefined`
+    * on reload (sanitizeTheme returns undefined for `{}`), but the row
+    * still exists, so the seed stays suppressed. This PUT-`{}` path is not
+    * reachable from the Theme Editor UI today (its clear affordance is the
+    * Reset button, which calls DELETE); it exists only via the API.
+    */
+   putTheme = async (body: unknown): Promise<ApiTheme> => {
+      if (isPublisherConfigFrozen(this.serverRoot)) {
+         throw new FrozenConfigError(
+            'Cannot edit theme: publisher.config.json has "frozenConfig": true.',
+         );
+      }
+      // Treat a literal `{}` as an intentional "clear all overrides" PUT
+      // (the only other clear path is DELETE, which re-seeds from the
+      // config file). sanitizeTheme returns undefined for both `{}` and
+      // garbage, so we have to disambiguate here.
+      const isEmptyObject =
+         typeof body === "object" &&
+         body !== null &&
+         !Array.isArray(body) &&
+         Object.keys(body as Record<string, unknown>).length === 0;
+      const sanitized = sanitizeTheme(body, "PUT /api/v0/theme");
+      if (!sanitized && !isEmptyObject) {
+         throw new BadRequestError(
+            "Theme payload was malformed (expected an object).",
+         );
+      }
+      const saved: Theme = await this.themeStore.set(sanitized ?? {});
+      return saved;
+   };
+
+   /**
+    * DELETE drops the persisted row so the next load re-seeds from
+    * publisher.config.json's `theme` block (or ends up unthemed if the
+    * config defines none). Contrast with PUT `{}`, which persists an empty
+    * row and thereby suppresses that seed instead of restoring it. See
+    * putTheme for the full divergence.
+    */
+   resetTheme = async (): Promise<ApiTheme> => {
+      if (isPublisherConfigFrozen(this.serverRoot)) {
+         throw new FrozenConfigError(
+            'Cannot reset theme: publisher.config.json has "frozenConfig": true.',
+         );
+      }
+      const reseeded = await this.themeStore.reset();
+      return reseeded ?? {};
+   };
+}

package/src/dto/connection.dto.ts

@@ -265,6 +265,12 @@ export class ConnectionDto implements ApiConnection {
       | "motherduck"
       | "ducklake";
 
+   // Opaque, secret-free data-identity token; carried verbatim (never parsed
+   // or re-hashed) into content-addressed source ids. See api-doc.yaml.
+   @IsOptional()
+   @IsString()
+   fingerprint?: string;
+
    @IsOptional()
    @ValidateNested()
    @Type(() => PostgresConnectionDto)

package/src/materialization_metrics.ts

@@ -131,7 +131,7 @@ export function recordAutoLoadOutcome(outcome: "success" | "failure"): void {
 
 /**
  * Record that a connection digest could not be computed during build-plan
- * compilation because the connection failed to resolve. The resulting buildIds
+ * compilation because the connection failed to resolve. The resulting sourceEntityIds
  * are computed without a digest, so this is a correctness signal, not just noise.
  */
 export function recordConnectionDigestSkipped(): void {

package/src/package_load/package_load_pool.ts

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

package/src/package_load/package_load_worker.ts

@@ -83,7 +83,10 @@ import { HackyDataStylesAccumulator } from "../data_styles";
 import { ModelCompilationError } from "../errors";
 import { validateAuthorizeProbes } from "../service/authorize";
 import { type FilterDefinition } from "../service/filter";
-import { parsePackageMaterialization } from "../service/package_manifest";
+import {
+   PackageMaterializationConfig,
+   parsePackageMaterialization,
+} from "../service/package_manifest";
 import {
    extractQueriesFromModelDef,
    extractSourcesFromModelDef,
@@ -383,7 +386,7 @@ async function readPackageMetadata(packagePath: string): Promise<{
    explores?: string[];
    queryableSources?: "declared" | "all";
    manifestLocation?: string | null;
-   materialization?: { schedule: string | null } | null;
+   materialization?: PackageMaterializationConfig | null;
 }> {
    const manifestPath = path.join(packagePath, PACKAGE_MANIFEST_NAME);
    const contents = await fs.promises.readFile(manifestPath, "utf8");

package/src/package_load/protocol.ts

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

package/src/runtime/publisher.js

@@ -79,7 +79,12 @@
          "/packages/" +
          encodeURIComponent(target.pkg) +
          "/models/" +
-         modelPath.split("/").map(encodeURIComponent).join("/") +
+         // Encode the whole model path as ONE path segment (slashes -> %2F). A model
+         // in a subfolder ("model/x.malloy") must not become two URL segments: some
+         // servers only match a single-segment {path} and would 405 a multi-segment
+         // path. This matches the typed SDK (encodeURIComponent) and the server's
+         // encoded-slash handling.
+         encodeURIComponent(modelPath) +
          "/query";
       var body = { compactJson: compactJson };
       if (malloyQuery) body.query = malloyQuery;

package/src/server.ts

@@ -20,6 +20,7 @@ import {
    BadRequestError,
    internalErrorToHttpError,
    NotImplementedError,
+   ServiceUnavailableError,
 } from "./errors";
 import {
    drainingGuard,
@@ -38,6 +39,7 @@ import { setFilterDeprecationHeaders } from "./filter_deprecation";
 import { checkHeapConfiguration } from "./heap_check";
 import { queryConcurrency } from "./query_concurrency";
 import { MaterializationController } from "./controller/materialization.controller";
+import { ThemeController } from "./controller/theme.controller";
 import { initializeMcpServer } from "./mcp/server";
 import { startAgentMcpServer } from "./mcp/agent_server";
 import { registerLegacyRoutes } from "./server-old";
@@ -45,6 +47,7 @@ import { EnvironmentStore } from "./service/environment_store";
 import { MaterializationService } from "./service/materialization_service";
 import { normalizeQueryArray } from "./query_param_utils";
 import { PackageMemoryGovernor } from "./service/package_memory_governor";
+import { ThemeStore } from "./service/theme_store";
 import { assertSafePackageName, safeJoinUnderRoot } from "./path_safety";
 
 export { normalizeQueryArray } from "./query_param_utils";
@@ -207,6 +210,8 @@ const materializationService = new MaterializationService(environmentStore);
 const materializationController = new MaterializationController(
    materializationService,
 );
+const themeStore = new ThemeStore(environmentStore.storageManager, SERVER_ROOT);
+const themeController = new ThemeController(themeStore, SERVER_ROOT);
 
 export const mcpApp = express();
 
@@ -722,7 +727,20 @@ app.get(
 app.get(`${API_PREFIX}/status`, async (_req, res) => {
    try {
       const status = await environmentStore.getStatus();
-      res.status(200).json(status);
+      // Compose theme onto the status response so the SDK can read both
+      // in one round trip on app boot. ThemeStore is the source of truth;
+      // publisher.config.json is only a boot seed (see ThemeStore). The
+      // field is always present (an empty object means "no overrides
+      // yet"), so the OpenAPI shape and the runtime payload agree.
+      // The theme here is cosmetic, so during the brief window before storage
+      // initializes report no overrides rather than 500 an endpoint the
+      // control plane polls for serving state (themeStore.get() throws until
+      // storage is ready). GET /theme, the editor's authoritative load, is
+      // answered with 503 during that window instead.
+      const theme = environmentStore.storageManager.isInitialized()
+         ? await themeStore.get()
+         : undefined;
+      res.status(200).json({ ...status, theme: theme ?? {} });
    } catch (error) {
       logger.error("Error getting status", { error });
       const { json, status } = internalErrorToHttpError(error as Error);
@@ -730,6 +748,45 @@ app.get(`${API_PREFIX}/status`, async (_req, res) => {
    }
 });
 
+app.get(`${API_PREFIX}/theme`, async (_req, res) => {
+   try {
+      if (!environmentStore.storageManager.isInitialized()) {
+         // Storage is still initializing. Answer 503 (not 200 with an empty
+         // theme) so the Theme Editor's load stays in an error state and
+         // never adopts {} as the authoritative saved baseline, which would
+         // let a subsequent edit auto-save {} over the real persisted theme.
+         throw new ServiceUnavailableError(
+            "Theme storage is still initializing. Retry shortly.",
+         );
+      }
+      res.status(200).json(await themeController.getTheme());
+   } catch (error) {
+      logger.error("Error getting theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
+app.put(`${API_PREFIX}/theme`, async (req, res) => {
+   try {
+      res.status(200).json(await themeController.putTheme(req.body));
+   } catch (error) {
+      logger.error("Error saving theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
+app.delete(`${API_PREFIX}/theme`, async (_req, res) => {
+   try {
+      res.status(200).json(await themeController.resetTheme());
+   } catch (error) {
+      logger.error("Error resetting theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
 app.get(`${API_PREFIX}/watch-mode/status`, watchModeController.getWatchStatus);
 app.post(`${API_PREFIX}/watch-mode/start`, watchModeController.startWatching);
 app.post(`${API_PREFIX}/watch-mode/stop`, watchModeController.stopWatchMode);

package/src/service/build_plan.spec.ts

@@ -4,7 +4,7 @@ import * as sinon from "sinon";
 import type { BuildGraph as MalloyBuildGraph } from "@malloydata/malloy";
 import {
    compilePackageBuildPlan,
-   computeBuildId,
+   computeSourceEntityId,
    computePackageBuildPlan,
    deriveAnnotationFields,
    deriveBuildPlan,
@@ -27,8 +27,8 @@ describe("flattenDependsOn", () => {
 
 describe("iterGraphSources", () => {
    it("yields resolvable sources in dependency order, skipping missing ones", () => {
-      const a = fakeSource({ name: "a", buildId: "ba" });
-      const b = fakeSource({ name: "b", buildId: "bb" });
+      const a = fakeSource({ name: "a", sourceEntityId: "ba" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bb" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -52,9 +52,9 @@ describe("iterGraphSources", () => {
       // and every transitive persist dependency is nested in dependsOn. All
       // three must be yielded (so all get built), leaf-first so a downstream
       // build reads its upstream's freshly materialized table.
-      const root = fakeSource({ name: "root", buildId: "br" });
-      const mid = fakeSource({ name: "mid", buildId: "bm" });
-      const leaf = fakeSource({ name: "leaf", buildId: "bl" });
+      const root = fakeSource({ name: "root", sourceEntityId: "br" });
+      const mid = fakeSource({ name: "mid", sourceEntityId: "bm" });
+      const leaf = fakeSource({ name: "leaf", sourceEntityId: "bl" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -85,9 +85,9 @@ describe("iterGraphSources", () => {
    it("deduplicates a shared (diamond) dependency across roots", () => {
       // r1 and r2 both depend on `shared`; it must be yielded exactly once and
       // before both dependents.
-      const r1 = fakeSource({ name: "r1", buildId: "b1" });
-      const r2 = fakeSource({ name: "r2", buildId: "b2" });
-      const shared = fakeSource({ name: "shared", buildId: "bs" });
+      const r1 = fakeSource({ name: "r1", sourceEntityId: "b1" });
+      const r2 = fakeSource({ name: "r2", sourceEntityId: "b2" });
+      const shared = fakeSource({ name: "shared", sourceEntityId: "bs" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -149,7 +149,7 @@ describe("deriveAnnotationFields", () => {
    });
 });
 
-describe("computeBuildId", () => {
+describe("computeSourceEntityId", () => {
    it("delegates to PersistSource.makeBuildId with the connection digest and SQL", () => {
       const makeBuildId = sinon.stub().returns("computed-id");
       const source = {
@@ -158,7 +158,7 @@ describe("computeBuildId", () => {
          getSQL: () => "SELECT 7",
       } as unknown as PersistSource;
 
-      const id = computeBuildId(source, { duckdb: "dig-1" });
+      const id = computeSourceEntityId(source, { duckdb: "dig-1" });
 
       expect(id).toBe("computed-id");
       expect(makeBuildId.calledOnceWithExactly("dig-1", "SELECT 7")).toBe(true);
@@ -188,7 +188,7 @@ describe("deriveBuildPlan", () => {
    it("projects graphs and sources into the wire build plan", () => {
       const orders = fakeSource({
          name: "orders",
-         buildId: "bid-orders",
+         sourceEntityId: "bid-orders",
          sql: "SELECT 1",
       });
       const plan = deriveBuildPlan(
@@ -206,15 +206,59 @@ describe("deriveBuildPlan", () => {
       expect(plan.sources["orders@m"]).toMatchObject({
          name: "orders",
          connectionName: "duckdb",
-         buildId: "bid-orders",
+         sourceEntityId: "bid-orders",
          sql: "SELECT 1",
          columns: [],
       });
    });
 
+   it("reports declared sharing/refresh verbatim and null when unset", () => {
+      // The control plane distinguishes unset from an explicit `shared` (it
+      // applies the platform default itself), so the publisher must report
+      // the declared value verbatim — never substitute the default.
+      const declared = fakeSource({
+         name: "declared",
+         sourceEntityId: "bid-d",
+         annotationFields: {
+            name: "d_table",
+            sharing: "private",
+            refresh: "incremental",
+         },
+      });
+      const unset = fakeSource({ name: "unset", sourceEntityId: "bid-u" });
+      const plan = deriveBuildPlan(
+         [
+            {
+               connectionName: "duckdb",
+               nodes: [
+                  [
+                     { sourceID: "declared@m", dependsOn: [] },
+                     { sourceID: "unset@m", dependsOn: [] },
+                  ],
+               ],
+            },
+         ] as unknown as Parameters<typeof deriveBuildPlan>[0],
+         { "declared@m": declared, "unset@m": unset },
+         { duckdb: "dig" },
+      );
+
+      expect(plan.sources["declared@m"].sharing).toBe("private");
+      expect(plan.sources["declared@m"].refresh).toBe("incremental");
+      // The raw annotation map still carries every field alongside the typed
+      // projections.
+      expect(plan.sources["declared@m"].annotationFields).toEqual({
+         name: "d_table",
+         sharing: "private",
+         refresh: "incremental",
+      });
+      // Unset is null — not "shared" — on the wire.
+      expect(plan.sources["unset@m"].sharing).toBeNull();
+      expect(plan.sources["unset@m"].refresh).toBeNull();
+   });
+
    it("honors the sourceNames filter", () => {
-      const a = fakeSource({ name: "a", buildId: "bid-a" });
-      const b = fakeSource({ name: "b", buildId: "bid-b" });
+      const a = fakeSource({ name: "a", sourceEntityId: "bid-a" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bid-b" });
       const plan = deriveBuildPlan(
          [
             {
@@ -231,8 +275,8 @@ describe("deriveBuildPlan", () => {
    });
 
    it("carries the per-source package-relative modelPath", () => {
-      const a = fakeSource({ name: "a", buildId: "bid-a" });
-      const b = fakeSource({ name: "b", buildId: "bid-b" });
+      const a = fakeSource({ name: "a", sourceEntityId: "bid-a" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bid-b" });
       const plan = deriveBuildPlan(
          [
             {

package/src/service/build_plan.ts

@@ -112,8 +112,8 @@ export function flattenDependsOn(node: {
  * persist dependency is nested under a root in its recursive {@code dependsOn}
  * tree (and present in {@code sources}). Walking only {@code graph.nodes}
  * silently skips every intermediate persist source, so it never gets
- * materialized (it only gets a table by coincidence when it shares a buildId
- * with a root). We post-order DFS the {@code dependsOn} tree
+ * materialized (it only gets a table by coincidence when it shares a
+ * sourceEntityId with a root). We post-order DFS the {@code dependsOn} tree
  * so dependencies are built first (a downstream build can then read its upstream
  * source's freshly materialized table), deduplicating shared (diamond)
  * dependencies by sourceID so each is yielded once. This mirrors the canonical
@@ -147,11 +147,23 @@ export function* iterGraphSources(
 }
 
 /**
- * The buildId for a persist source: a stable digest of its connection identity
- * and canonical SQL. Centralizes the (source, connectionDigests) call shape so
- * planning, self-instruction, and build all agree on the same id.
+ * The sourceEntityId for a persist source: a stable content address of its
+ * connection identity and canonical SQL. Centralizes the
+ * (source, connectionDigests) call shape so planning, self-instruction, build,
+ * and serve-time manifest resolution all agree on the same id.
+ *
+ * <p>This is the single seam between the publisher and the Malloy compiler's
+ * source-identity recipe. Today it delegates to
+ * {@code PersistSource.makeBuildId(connectionDigest, sql)} — the compiler's
+ * current hex content hash. The connection's contribution is already
+ * fingerprint-aware: when a connection carries an API `fingerprint`, its
+ * digest IS that fingerprint verbatim (see applyConnectionFingerprint in
+ * connection.ts), so ids stay stable across credential rotation. When the
+ * compiler ships the scoped UUID5 sourceEntityId recipe (scope + connection
+ * fingerprint + canonical SQL), swap the delegation below to the new compiler
+ * API — this function is the only place the publisher derives the id.
  */
-export function computeBuildId(
+export function computeSourceEntityId(
    source: PersistSource,
    connectionDigests: Record<string, string>,
 ): string {
@@ -246,9 +258,9 @@ export async function compilePackageBuildPlan(
       const conn = connections.get(graph.connectionName);
       if (!conn) {
          // The connection failed to resolve (already warned in
-         // resolvePackageConnections). Its buildIds will be computed without a
-         // digest, so surface it as a discrete correctness signal rather than
-         // skipping silently.
+         // resolvePackageConnections). Its sourceEntityIds will be computed
+         // without a digest, so surface it as a discrete correctness signal
+         // rather than skipping silently.
          recordConnectionDigestSkipped();
          logger.warn("Skipping connection digest; connection did not resolve", {
             connectionName: graph.connectionName,
@@ -256,6 +268,9 @@ export async function compilePackageBuildPlan(
          continue;
       }
       if (!connectionDigests[graph.connectionName]) {
+         // getDigest() is fingerprint-aware: a connection configured with an
+         // API `fingerprint` returns it verbatim (applyConnectionFingerprint),
+         // so a credential rotation does not re-address its sources.
          connectionDigests[graph.connectionName] = await conn.getDigest();
       }
    }
@@ -292,15 +307,24 @@ export function deriveBuildPlan(
    const wireSources: Record<string, WirePersistSourcePlan> = {};
    for (const [sourceID, source] of Object.entries(sources)) {
       if (include && !include.has(source.name)) continue;
+      const annotationFields = deriveAnnotationFields(source);
       wireSources[sourceID] = {
          name: source.name,
          sourceID: source.sourceID,
          connectionName: source.connectionName,
          dialect: source.dialectName,
-         buildId: computeBuildId(source, connectionDigests),
+         sourceEntityId: computeSourceEntityId(source, connectionDigests),
          sql: source.getSQL(),
+         // Declared `#@ persist` scope/refresh knobs, reported VERBATIM (null
+         // = unset). The control plane applies the platform default (unset =>
+         // shared) itself, so the publisher must never substitute it — unset
+         // has to stay distinguishable from an explicit `shared`. The source's
+         // own annotation is the most-specific declaration layer, and the only
+         // one that exists today.
+         sharing: annotationFields.sharing ?? null,
+         refresh: annotationFields.refresh ?? null,
          columns: deriveColumns(source),
-         annotationFields: deriveAnnotationFields(source),
+         annotationFields,
          modelPath: sourceModelPaths?.[sourceID],
       };
    }

package/src/service/connection.ts

@@ -1028,6 +1028,38 @@ function getMetadataForLookup(
    return name ? metadata.get(name) : undefined;
 }
 
+/**
+ * Make a connection's digest the caller-supplied API `fingerprint`, verbatim.
+ *
+ * The fingerprint is the connection's data identity as declared by the caller
+ * (secret-free, stable across credential rotation). When set, it replaces the
+ * locally derived `getDigest()` so it becomes the connection's contribution to
+ * content-addressed source ids everywhere a digest is read:
+ *
+ *  - build planning (`compilePackageBuildPlan` -> `conn.getDigest()`),
+ *  - the package-load worker's connection-metadata RPC, and
+ *  - Malloy's own serve-time manifest resolution (the runtime calls
+ *    `conn.getDigest()` internally when a build manifest is bound).
+ *
+ * Overriding the method on the resolved instance — inside the one
+ * `lookupConnection` wrapper every resolution passes through — is what keeps
+ * build-time and serve-time ids identical; applying it per call site would
+ * invite divergence and a silent live-serving fallback. The value is used
+ * verbatim (never re-hashed or combined with local details) and treated as an
+ * opaque token: it is not a secret, but it is never logged or parsed.
+ * Without a fingerprint the connection keeps its locally derived digest.
+ */
+function applyConnectionFingerprint(
+   connection: Connection,
+   metadata: EnvironmentConnectionMetadata | undefined,
+): Connection {
+   const fingerprint = metadata?.apiConnection.fingerprint;
+   if (fingerprint) {
+      connection.getDigest = () => fingerprint;
+   }
+   return connection;
+}
+
 function isDuckDBConnection(
    connection: Connection,
 ): connection is DuckDBConnection {
@@ -1095,10 +1127,11 @@ export function buildEnvironmentMalloyConfig(
    }
 
    malloyConfig.wrapConnections(
-      (base: LookupConnection<Connection>): LookupConnection<Connection> => ({
-         lookupConnection: async (name?: string): Promise<Connection> => {
-            const metadata = getMetadataForLookup(assembled.metadata, name);
-
+      (base: LookupConnection<Connection>): LookupConnection<Connection> => {
+         const resolveConnection = async (
+            name: string | undefined,
+            metadata: EnvironmentConnectionMetadata | undefined,
+         ): Promise<Connection> => {
             if (metadata?.isDuckLake) {
                let connectionPromise = duckLakeCache.get(name!);
                if (!connectionPromise) {
@@ -1210,8 +1243,21 @@ export function buildEnvironmentMalloyConfig(
                await attachOnce(connection, metadata);
             }
             return connection;
-         },
-      }),
+         };
+
+         return {
+            lookupConnection: async (name?: string): Promise<Connection> => {
+               const metadata = getMetadataForLookup(assembled.metadata, name);
+               // Every resolution branch funnels through this one exit so a
+               // configured fingerprint is applied no matter which wrapper
+               // produced the connection (see applyConnectionFingerprint).
+               return applyConnectionFingerprint(
+                  await resolveConnection(name, metadata),
+                  metadata,
+               );
+            },
+         };
+      },
    );
 
    return {