@malloy-publisher/server 0.0.219 → 0.0.220

package/src/service/materialization_service.spec.ts

@@ -236,13 +236,15 @@ describe("MaterializationService", () => {
          ).toMatchObject({ mode: "orchestrated" });
       });
 
-      it("rejects instructions referencing an unknown buildId before creating", async () => {
+      it("rejects instructions referencing an unknown sourceEntityId before creating", async () => {
          setPackage(ctx.environmentStore, {
             getBuildPlan: () => makeBuildPlan(),
          });
          await expect(
             ctx.service.createMaterialization("my-env", "pkg", {
-               buildInstructions: [makeInstruction({ buildId: "ghost" })],
+               buildInstructions: [
+                  makeInstruction({ sourceEntityId: "ghost" }),
+               ],
             }),
          ).rejects.toThrow(BadRequestError);
          expect(ctx.repository.createMaterialization.called).toBe(false);
@@ -347,7 +349,7 @@ describe("MaterializationService", () => {
                   strict: false,
                   entries: {
                      b1: {
-                        buildId: "b1",
+                        sourceEntityId: "b1",
                         physicalTableName: "orders_mz",
                         connectionName: "duckdb",
                      },
@@ -383,7 +385,7 @@ describe("MaterializationService", () => {
                   strict: false,
                   entries: {
                      b1: {
-                        buildId: "b1",
+                        sourceEntityId: "b1",
                         physicalTableName: "orders_mz",
                         connectionName: "duckdb",
                      },
@@ -423,7 +425,7 @@ describe("MaterializationService", () => {
                   strict: false,
                   entries: {
                      b1: {
-                        buildId: "b1",
+                        sourceEntityId: "b1",
                         // Container path on a hyphenated BigQuery project: each
                         // segment must be backtick-quoted independently.
                         physicalTableName: "my-proj.ds.engaged",
@@ -460,7 +462,7 @@ describe("MaterializationService", () => {
                   strict: false,
                   entries: {
                      b1: {
-                        buildId: "b1",
+                        sourceEntityId: "b1",
                         physicalTableName: "orders_mz",
                         connectionName: "duckdb",
                      },
@@ -481,7 +483,7 @@ describe("MaterializationService", () => {
 });
 
 describe("stagingSuffix", () => {
-   it("derives a short, stable suffix from the buildId", () => {
+   it("derives a short, stable suffix from the sourceEntityId", () => {
       expect(stagingSuffix("abcdef1234567890")).toBe("_abcdef123456");
    });
 });
@@ -492,17 +494,17 @@ describe("deriveSelfInstructions", () => {
       ctx = createMocks();
    });
 
-   it("carries forward unchanged buildIds and builds the rest (deduping repeats)", () => {
+   it("carries forward unchanged sourceEntityIds and builds the rest (deduping repeats)", () => {
       const compiled = compiledWith(
          {
-            s1: fakeSource({ name: "s1", buildId: "b1aaaaaaaaaaaaaa" }),
-            s2: fakeSource({ name: "s2", buildId: "b2bbbbbbbbbbbbbb" }),
+            s1: fakeSource({ name: "s1", sourceEntityId: "b1aaaaaaaaaaaaaa" }),
+            s2: fakeSource({ name: "s2", sourceEntityId: "b2bbbbbbbbbbbbbb" }),
          },
          [["s1", "s2"], ["s2"]],
       );
       const priorEntries = {
          b1aaaaaaaaaaaaaa: {
-            buildId: "b1aaaaaaaaaaaaaa",
+            sourceEntityId: "b1aaaaaaaaaaaaaa",
             physicalTableName: "s1_prev",
             connectionName: "duckdb",
          },
@@ -519,7 +521,7 @@ describe("deriveSelfInstructions", () => {
       ).deriveSelfInstructions(compiled, undefined, priorEntries);
 
       expect(instructions).toHaveLength(1);
-      expect(instructions[0].buildId).toBe("b2bbbbbbbbbbbbbb");
+      expect(instructions[0].sourceEntityId).toBe("b2bbbbbbbbbbbbbb");
       expect(instructions[0].physicalTableName).toBe("s2");
       expect(instructions[0].realization).toBe("COPY");
       expect(instructions[0].materializedTableId).toBe("local-b2bbbbbbbbbb");
@@ -531,8 +533,8 @@ describe("deriveSelfInstructions", () => {
    it("honors the sourceNames filter (excluded sources are neither built nor carried)", () => {
       const compiled = compiledWith(
          {
-            s1: fakeSource({ name: "s1", buildId: "b1aaaaaaaaaaaaaa" }),
-            s2: fakeSource({ name: "s2", buildId: "b2bbbbbbbbbbbbbb" }),
+            s1: fakeSource({ name: "s1", sourceEntityId: "b1aaaaaaaaaaaaaa" }),
+            s2: fakeSource({ name: "s2", sourceEntityId: "b2bbbbbbbbbbbbbb" }),
          },
          [["s1", "s2"]],
       );
@@ -547,7 +549,7 @@ describe("deriveSelfInstructions", () => {
       ).deriveSelfInstructions(compiled, ["s2"], {});
 
       expect(instructions).toHaveLength(1);
-      expect(instructions[0].buildId).toBe("b2bbbbbbbbbbbbbb");
+      expect(instructions[0].sourceEntityId).toBe("b2bbbbbbbbbbbbbb");
       expect(Object.keys(carried as Record<string, unknown>)).toHaveLength(0);
    });
 });
@@ -561,7 +563,7 @@ describe("getMostRecentManifestEntries (skip-if-unchanged)", () => {
    it("returns entries from the most recent successful run, excluding the in-flight one", async () => {
       const entries = {
          b1: {
-            buildId: "b1",
+            sourceEntityId: "b1",
             physicalTableName: "orders_v1",
             connectionName: "duckdb",
          },
@@ -599,7 +601,9 @@ describe("getMostRecentManifestEntries (skip-if-unchanged)", () => {
             manifest: {
                builtAt: "t",
                strict: false,
-               entries: { b1: { buildId: "b1", physicalTableName: "t1" } },
+               entries: {
+                  b1: { sourceEntityId: "b1", physicalTableName: "t1" },
+               },
             },
          }),
       ]);
@@ -679,8 +683,8 @@ describe("executeInstructedBuild", () => {
    it("builds instructed sources in dependency order and seeds carried entries", async () => {
       const runSQL = sinon.stub().resolves();
       const connection = { runSQL } as unknown as MalloyConnection;
-      const s1 = fakeSource({ name: "s1", buildId: "b1aaaaaaaaaaaaaa" });
-      const s2 = fakeSource({ name: "s2", buildId: "b2bbbbbbbbbbbbbb" });
+      const s1 = fakeSource({ name: "s1", sourceEntityId: "b1aaaaaaaaaaaaaa" });
+      const s2 = fakeSource({ name: "s2", sourceEntityId: "b2bbbbbbbbbbbbbb" });
       const compiled = compiledWith(
          { s1, s2 },
          [["s1"], ["s2"]],
@@ -691,13 +695,13 @@ describe("executeInstructedBuild", () => {
          compiled,
          [
             {
-               buildId: "b1aaaaaaaaaaaaaa",
+               sourceEntityId: "b1aaaaaaaaaaaaaa",
                materializedTableId: "mt-1",
                physicalTableName: "s1_v1",
                realization: "COPY",
             },
             {
-               buildId: "b2bbbbbbbbbbbbbb",
+               sourceEntityId: "b2bbbbbbbbbbbbbb",
                materializedTableId: "mt-2",
                physicalTableName: "s2_v1",
                realization: "COPY",
@@ -705,7 +709,7 @@ describe("executeInstructedBuild", () => {
          ],
          {
             carried0: {
-               buildId: "carried0",
+               sourceEntityId: "carried0",
                physicalTableName: "carried_tbl",
                connectionName: "duckdb",
             },
@@ -725,8 +729,14 @@ describe("executeInstructedBuild", () => {
       // though the caller instructed it. Both must now build, `mid` first.
       const runSQL = sinon.stub().resolves();
       const connection = { runSQL } as unknown as MalloyConnection;
-      const root = fakeSource({ name: "root", buildId: "brootaaaaaaaaaa" });
-      const mid = fakeSource({ name: "mid", buildId: "bmidbbbbbbbbbbb" });
+      const root = fakeSource({
+         name: "root",
+         sourceEntityId: "brootaaaaaaaaaa",
+      });
+      const mid = fakeSource({
+         name: "mid",
+         sourceEntityId: "bmidbbbbbbbbbbb",
+      });
       const compiled = {
          graphs: [
             {
@@ -750,13 +760,13 @@ describe("executeInstructedBuild", () => {
          compiled,
          [
             {
-               buildId: "brootaaaaaaaaaa",
+               sourceEntityId: "brootaaaaaaaaaa",
                materializedTableId: "mt-r",
                physicalTableName: "root_v1",
                realization: "COPY",
             },
             {
-               buildId: "bmidbbbbbbbbbbb",
+               sourceEntityId: "bmidbbbbbbbbbbb",
                materializedTableId: "mt-m",
                physicalTableName: "mid_v1",
                realization: "COPY",
@@ -779,7 +789,7 @@ describe("executeInstructedBuild", () => {
    });
 
    it("throws when an instructed graph's connection is missing", async () => {
-      const s1 = fakeSource({ name: "s1", buildId: "b1aaaaaaaaaaaaaa" });
+      const s1 = fakeSource({ name: "s1", sourceEntityId: "b1aaaaaaaaaaaaaa" });
       const compiled = compiledWith({ s1 }, [["s1"]], new Map());
 
       await expect(
@@ -787,7 +797,7 @@ describe("executeInstructedBuild", () => {
             compiled,
             [
                {
-                  buildId: "b1aaaaaaaaaaaaaa",
+                  sourceEntityId: "b1aaaaaaaaaaaaaa",
                   materializedTableId: "mt-1",
                   physicalTableName: "s1_v1",
                   realization: "COPY",
@@ -809,15 +819,15 @@ describe("buildOneSource", () => {
       connection: { runSQL: sinon.SinonStub },
       physicalTableName: string,
       dialectName?: string,
-   ): Promise<{ buildId: string; physicalTableName: string }> {
+   ): Promise<{ sourceEntityId: string; physicalTableName: string }> {
       const source = fakeSource({
          name: "orders",
-         buildId: "abcdef1234567890",
+         sourceEntityId: "abcdef1234567890",
          sql: "SELECT * FROM t",
          dialectName,
       });
       const instruction: BuildInstruction = {
-         buildId: "abcdef1234567890",
+         sourceEntityId: "abcdef1234567890",
          materializedTableId: "mt-1",
          physicalTableName,
          realization: "COPY",
@@ -830,7 +840,7 @@ describe("buildOneSource", () => {
                c: unknown,
                d: Record<string, string>,
                m: Manifest,
-            ) => Promise<{ buildId: string; physicalTableName: string }>;
+            ) => Promise<{ sourceEntityId: string; physicalTableName: string }>;
          }
       ).buildOneSource(
          source,
@@ -853,7 +863,7 @@ describe("buildOneSource", () => {
          'ALTER TABLE "orders_v1_abcdef123456" RENAME TO "orders_v1"',
       ]);
       expect(entry.physicalTableName).toBe("orders_v1");
-      expect(entry.buildId).toBe("abcdef1234567890");
+      expect(entry.sourceEntityId).toBe("abcdef1234567890");
    });
 
    it("drops the staging table and rethrows when the build SQL fails", async () => {
@@ -919,7 +929,7 @@ describe("runBuild (branch behavior)", () => {
    function stubEngine(): RunBuildInternals {
       const entries = {
          "build-orders": {
-            buildId: "build-orders",
+            sourceEntityId: "build-orders",
             physicalTableName: '"orders_v1"',
             connectionName: "duckdb",
          },
@@ -995,11 +1005,11 @@ describe("autoLoadManifest", () => {
       const reloadAllModelsForPackage = sinon.stub().resolves();
       const entries = {
          b1: {
-            buildId: "b1",
+            sourceEntityId: "b1",
             physicalTableName: "orders_v1",
             connectionName: "duckdb",
          },
-         b2: { buildId: "b2", physicalTableName: undefined },
+         b2: { sourceEntityId: "b2", physicalTableName: undefined },
       };
 
       await (
@@ -1033,7 +1043,7 @@ describe("autoLoadManifest", () => {
                ) => Promise<void>;
             }
          ).autoLoadManifest({ reloadAllModelsForPackage }, "pkg", {
-            b1: { buildId: "b1", physicalTableName: "t" },
+            b1: { sourceEntityId: "b1", physicalTableName: "t" },
          }),
       ).resolves.toBeUndefined();
    });

package/src/service/materialization_service.ts

@@ -34,7 +34,7 @@ import { errMessage } from "../utils";
 import {
    CompiledBuildPlan,
    compilePackageBuildPlan,
-   computeBuildId,
+   computeSourceEntityId,
    deriveAnnotationFields,
    iterGraphSources,
 } from "./build_plan";
@@ -43,16 +43,17 @@ import { bareTableName, quoteIdentifier, quoteTablePath } from "./quoting";
 import { resolveEnvironmentId } from "./resolve_environment";
 
 /**
- * Length of the buildId prefix used when synthesizing staging table names.
- * buildId is a 64-char SHA-256 hex string; 12 hex chars is 48 bits of
- * entropy, well inside every dialect's identifier limit (Postgres is the
- * tightest at 63).
+ * Length of the sourceEntityId prefix used when synthesizing staging table
+ * names. 12 hex chars is 48 bits of entropy, well inside every dialect's
+ * identifier limit (Postgres is the tightest at 63).
  */
-const STAGING_BUILD_ID_LEN = 12;
+const STAGING_ID_LEN = 12;
 
 /** Staging suffix appended to a table name while it is being built. */
-export function stagingSuffix(buildId: string): string {
-   return `_${buildId.substring(0, STAGING_BUILD_ID_LEN)}`;
+export function stagingSuffix(sourceEntityId: string): string {
+   // Drop hyphens so the suffix stays a bare identifier fragment when the id
+   // becomes a UUID5 (a no-op for the current hex ids).
+   return `_${sourceEntityId.replace(/-/g, "").substring(0, STAGING_ID_LEN)}`;
 }
 
 /**
@@ -334,7 +335,7 @@ export class MaterializationService {
             carried = {};
          } else {
             // Skip-if-unchanged: reuse tables from the most recent successful
-            // manifest for sources whose buildId is unchanged, unless
+            // manifest for sources whose sourceEntityId is unchanged, unless
             // forceRefresh.
             const priorEntries = opts.forceRefresh
                ? {}
@@ -396,7 +397,7 @@ export class MaterializationService {
    /**
     * Derive the publisher's own build instructions for auto-run. Each persist
     * source (respecting the optional sourceNames filter) gets a self-assigned
-    * physical table name and COPY realization, unless its buildId is unchanged
+    * physical table name and COPY realization, unless its sourceEntityId is unchanged
     * since `priorEntries` — those are carried forward (reused) instead of
     * rebuilt.
     */
@@ -420,24 +421,24 @@ export class MaterializationService {
          )) {
             if (include && !include.has(persistSource.name)) continue;
 
-            const buildId = computeBuildId(
+            const sourceEntityId = computeSourceEntityId(
                persistSource,
                compiled.connectionDigests,
             );
-            if (seen.has(buildId)) continue;
-            seen.add(buildId);
+            if (seen.has(sourceEntityId)) continue;
+            seen.add(sourceEntityId);
 
-            const prior = priorEntries[buildId];
+            const prior = priorEntries[sourceEntityId];
             if (prior && prior.physicalTableName) {
-               carried[buildId] = prior;
+               carried[sourceEntityId] = prior;
                continue;
             }
 
             instructions.push({
-               buildId,
-               materializedTableId: `local-${buildId.substring(
+               sourceEntityId,
+               materializedTableId: `local-${sourceEntityId.substring(
                   0,
-                  STAGING_BUILD_ID_LEN,
+                  STAGING_ID_LEN,
                )}`,
                physicalTableName: selfAssignTableName(persistSource),
                realization: "COPY",
@@ -486,9 +487,11 @@ export class MaterializationService {
       entries: Record<string, ManifestEntry>,
    ): Promise<void> {
       const manifestEntries: BuildManifest["entries"] = {};
-      for (const [buildId, entry] of Object.entries(entries)) {
+      for (const [sourceEntityId, entry] of Object.entries(entries)) {
          if (entry.physicalTableName) {
-            manifestEntries[buildId] = { tableName: entry.physicalTableName };
+            manifestEntries[sourceEntityId] = {
+               tableName: entry.physicalTableName,
+            };
          }
       }
       try {
@@ -512,7 +515,7 @@ export class MaterializationService {
 
    /**
     * Validate caller-supplied build instructions against the package's compiled
-    * build plan: every instructed buildId must be a planned source, and only
+    * build plan: every instructed sourceEntityId must be a planned source, and only
     * COPY realization is supported. Throws when the package declares no persist
     * source (no plan to build against).
     */
@@ -525,15 +528,15 @@ export class MaterializationService {
             "Package has no persist sources; buildInstructions cannot be applied",
          );
       }
-      const plannedBuildIds = new Set<string>();
+      const plannedSourceEntityIds = new Set<string>();
       for (const source of Object.values(plan.sources)) {
-         plannedBuildIds.add(source.buildId);
+         plannedSourceEntityIds.add(source.sourceEntityId);
       }
 
       for (const instruction of instructions) {
-         if (!plannedBuildIds.has(instruction.buildId)) {
+         if (!plannedSourceEntityIds.has(instruction.sourceEntityId)) {
             throw new BadRequestError(
-               `Instruction references unknown buildId '${instruction.buildId}'`,
+               `Instruction references unknown sourceEntityId '${instruction.sourceEntityId}'`,
             );
          }
          // COPY-only for now; SNAPSHOT lands once clone semantics are defined.
@@ -561,20 +564,20 @@ export class MaterializationService {
       const { graphs, sources, connectionDigests, connections } = compiled;
 
       // Index instructions by sourceID (the stable per-source handle) so the
-      // build no longer recomputes the buildId to find an instruction.
-      // Recomputing it here forced a caller's buildId to equal the publisher's
-      // content hash, so a caller that derives buildIds by any other scheme
-      // would have its sources silently skipped (the recomputed buildId would
-      // not match the instruction). buildId is treated as opaque, caller-assigned
-      // identity. A buildId index is kept as a fallback for instructions without
+      // build no longer recomputes the sourceEntityId to find an instruction.
+      // Recomputing it here forced a caller's sourceEntityId to equal the publisher's
+      // content hash, so a caller that derives sourceEntityIds by any other scheme
+      // would have its sources silently skipped (the recomputed sourceEntityId would
+      // not match the instruction). sourceEntityId is treated as opaque, caller-assigned
+      // identity. A sourceEntityId index is kept as a fallback for instructions without
       // a sourceID (e.g. standalone auto-run).
       const bySourceID = new Map<string, BuildInstruction>();
-      const byBuildId = new Map<string, BuildInstruction>();
+      const bySourceEntityId = new Map<string, BuildInstruction>();
       for (const instruction of instructions) {
          if (instruction.sourceID) {
             bySourceID.set(instruction.sourceID, instruction);
          }
-         byBuildId.set(instruction.buildId, instruction);
+         bySourceEntityId.set(instruction.sourceEntityId, instruction);
       }
 
       // Accumulates physical names as sources are built so downstream sources
@@ -582,11 +585,13 @@ export class MaterializationService {
       // it with carried-forward entries so reused upstreams resolve too.
       const manifest = new Manifest();
       const entries: Record<string, ManifestEntry> = {};
-      for (const [buildId, entry] of Object.entries(seedEntries)) {
+      for (const [sourceEntityId, entry] of Object.entries(seedEntries)) {
          if (entry.physicalTableName) {
-            manifest.update(buildId, { tableName: entry.physicalTableName });
+            manifest.update(sourceEntityId, {
+               tableName: entry.physicalTableName,
+            });
          }
-         entries[buildId] = entry;
+         entries[sourceEntityId] = entry;
       }
 
       for (const graph of graphs) {
@@ -599,15 +604,19 @@ export class MaterializationService {
          for (const persistSource of iterGraphSources(graph, sources)) {
             if (signal.aborted) throw new Error("Build cancelled");
 
-            // The manifest is keyed by the content buildId — what Malloy
+            // The manifest is keyed by the content sourceEntityId — what Malloy
             // recomputes to resolve upstream persist references during SQL
-            // generation — independent of the instruction's identity buildId.
-            const buildId = computeBuildId(persistSource, connectionDigests);
-            // Prefer sourceID matching (so the caller's buildId scheme stays
-            // opaque to the build); fall back to buildId for instructions
+            // generation — independent of the instruction's identity sourceEntityId.
+            const sourceEntityId = computeSourceEntityId(
+               persistSource,
+               connectionDigests,
+            );
+            // Prefer sourceID matching (so the caller's sourceEntityId scheme stays
+            // opaque to the build); fall back to sourceEntityId for instructions
             // without a sourceID (auto-run).
             const instruction =
-               bySourceID.get(persistSource.sourceID) ?? byBuildId.get(buildId);
+               bySourceID.get(persistSource.sourceID) ??
+               bySourceEntityId.get(sourceEntityId);
             if (!instruction) continue;
 
             const entry = await this.buildOneSource(
@@ -617,7 +626,7 @@ export class MaterializationService {
                connectionDigests,
                manifest,
             );
-            entries[buildId] = entry;
+            entries[sourceEntityId] = entry;
          }
       }
 
@@ -627,7 +636,7 @@ export class MaterializationService {
    /**
     * Build a single instructed source into its assigned physical table.
     * COPY uses a staging table + atomic rename for crash-safety; the staging
-    * name derives from the buildId. Records and returns the manifest entry.
+    * name derives from the sourceEntityId. Records and returns the manifest entry.
     */
    private async buildOneSource(
       persistSource: PersistSource,
@@ -636,7 +645,7 @@ export class MaterializationService {
       connectionDigests: Record<string, string>,
       manifest: Manifest,
    ): Promise<ManifestEntry> {
-      const buildId = instruction.buildId;
+      const sourceEntityId = instruction.sourceEntityId;
       const physicalTableName = instruction.physicalTableName;
       const buildSQL = persistSource.getSQL({
          buildManifest: manifest.buildManifest,
@@ -644,7 +653,7 @@ export class MaterializationService {
       });
 
       const bareName = bareTableName(physicalTableName);
-      const stagingTableName = `${physicalTableName}${stagingSuffix(buildId)}`;
+      const stagingTableName = `${physicalTableName}${stagingSuffix(sourceEntityId)}`;
       // The control plane sends the logical (unquoted) physical name; dialect-
       // quote each identifier here so a container path or quote-requiring name
       // (e.g. a hyphenated BigQuery project id) produces valid DDL. The manifest
@@ -681,7 +690,7 @@ export class MaterializationService {
       }
 
       // Make this table visible to downstream sources built later in this run.
-      manifest.update(buildId, { tableName: physicalTableName });
+      manifest.update(sourceEntityId, { tableName: physicalTableName });
 
       const durationMs = Math.round(performance.now() - startTime);
       recordSourceBuildDuration(durationMs);
@@ -691,7 +700,7 @@ export class MaterializationService {
       });
 
       return {
-         buildId,
+         sourceEntityId,
          sourceName: persistSource.name,
          materializedTableId: instruction.materializedTableId,
          physicalTableName,
@@ -799,7 +808,7 @@ export class MaterializationService {
          if (!connectionName || !physicalTableName) {
             logger.warn("Skipping manifest entry with no connection/table", {
                materializationId: m.id,
-               buildId: entry.buildId,
+               sourceEntityId: entry.sourceEntityId,
             });
             continue;
          }
@@ -825,7 +834,7 @@ export class MaterializationService {
             // table behind; clean it up too while we hold the connection.
             await connection.runSQL(
                `DROP TABLE IF EXISTS ${quoteTablePath(
-                  `${physicalTableName}${stagingSuffix(entry.buildId)}`,
+                  `${physicalTableName}${stagingSuffix(entry.sourceEntityId)}`,
                   dialect,
                )}`,
             );

package/src/service/materialization_test_fixtures.ts

@@ -48,7 +48,7 @@ export function makeBuildPlan(overrides: Partial<BuildPlan> = {}): BuildPlan {
             sourceID: "orders@m.malloy",
             connectionName: "duckdb",
             dialect: "duckdb",
-            buildId: "build-orders",
+            sourceEntityId: "build-orders",
             sql: "SELECT 1",
             columns: [],
          },
@@ -62,7 +62,7 @@ export function makeInstruction(
    overrides: Partial<BuildInstruction> = {},
 ): BuildInstruction {
    return {
-      buildId: "build-orders",
+      sourceEntityId: "build-orders",
       materializedTableId: "mt-1",
       physicalTableName: '"orders_v1"',
       realization: "COPY",
@@ -72,12 +72,12 @@ export function makeInstruction(
 
 /**
  * A minimal stand-in for a Malloy {@link PersistSource} exposing only what the
- * build internals touch (name/id, deterministic buildId, SQL, and the
+ * build internals touch (name/id, deterministic sourceEntityId, SQL, and the
  * `#@ persist name=` annotation reader, defaulted to "unset").
  */
 export function fakeSource(opts: {
    name: string;
-   buildId: string;
+   sourceEntityId: string;
    sql?: string;
    connectionName?: string;
    dialectName?: string;
@@ -87,7 +87,7 @@ export function fakeSource(opts: {
       sourceID: opts.name,
       connectionName: opts.connectionName ?? "duckdb",
       dialectName: opts.dialectName ?? "duckdb",
-      makeBuildId: () => opts.buildId,
+      makeBuildId: () => opts.sourceEntityId,
       getSQL: () => opts.sql ?? "SELECT 1",
       annotations: {
          parseAsTag: () => ({ tag: { text: () => undefined } }),

package/src/service/model.ts

@@ -1931,7 +1931,7 @@ function makeHydrationRuntime(
    // (getSQL) time, gated on `prepareResultOptions.buildManifest`; without this
    // the hydrated model always recomputes from the base tables even though the
    // manifest was bound at load. `strict: false` keeps serving live for any
-   // source whose buildId is absent from the manifest.
+   // source whose sourceEntityId is absent from the manifest.
    return new Runtime({
       urlReader,
       config,

package/src/service/package.ts

@@ -61,7 +61,7 @@ export class Package {
    private packagePath: string;
    private malloyConfig: MalloyConfig;
    // Build-manifest binding state (Malloy Persistence v0). When bound, these
-   // entries (buildId -> { tableName }) are what served queries use to route
+   // entries (sourceEntityId -> { tableName }) are what served queries use to route
    // persist sources to their materialized physical tables; they are also reused
    // by the /compile preview so previewed SQL matches executed SQL. Surfaced on
    // /status (via getPackageMetadata) so the control plane can confirm a worker
@@ -72,7 +72,7 @@ export class Package {
    private manifestEntryCount = 0;
    private boundManifestUri: string | null = null;
    // The package's persist build plan: a deterministic property of the compiled
-   // package (per-source buildId, columns, build SQL, dependency graphs),
+   // package (per-source sourceEntityId, columns, build SQL, dependency graphs),
    // computed once at load from the live (unbound) models so it is stable for a
    // given (package version, connection config). Null when the package declares
    // no persist source. Surfaced read-only on getPackageMetadata() so a caller
@@ -460,7 +460,7 @@ export class Package {
    }
 
    /**
-    * The package's persist build plan (per-source buildId, columns, build SQL,
+    * The package's persist build plan (per-source sourceEntityId, columns, build SQL,
     * dependency graphs), or null when the package declares no persist source.
     * A deterministic property of the compiled package; callers derive build
     * instructions from it for an orchestrated materialization.
@@ -503,7 +503,7 @@ export class Package {
    }
 
    /**
-    * The currently-bound build-manifest entries (buildId -> { tableName }), or
+    * The currently-bound build-manifest entries (sourceEntityId -> { tableName }), or
     * undefined when the package is serving live. Reused by the /compile preview
     * so previewed SQL gets the same persist-source -> physical-table routing as
     * execution.