@finos/legend-cube-builder 0.0.2 → 0.0.4

package/src/graph-manager/CubeIngest.ts

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ModelContext } from '@finos/legend-cube';
+import { CubeDataProductEnvironmentType } from './CubeDataProduct.js';
+
+// An ingest cube (PLAN §6.7) saves, as its model, what Data Cube's producer
+// source picks before a definition: the class (production or production
+// parallel), the producer deployment and, once picked, the warehouse. Its
+// sources save each definition's URN, path and data set. The engine's
+// implementation builds, for each call, a model of the definitions the call
+// reads, as the ingest server serves them, and for a run a lakehouse runtime
+// at a fixed path, which the saved runtime names
+
+export const CUBE_INGEST_MODEL_TYPE = 'cubeIngest';
+
+export const CUBE_INGEST_RUNTIME_PATH = 'cube::ingest::Runtime';
+
+/** What an ingest cube runs on, as its model saves it */
+export interface CubeIngestSettings {
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** The producer deployment whose definitions the cube reads, as text */
+  readonly producerDeploymentId: string;
+  /** The warehouse the cube runs on; none until one is picked */
+  readonly warehouse?: string | undefined;
+}
+
+const ENVIRONMENT_TYPES = Object.values(
+  CubeDataProductEnvironmentType,
+) as string[];
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+export const createCubeIngestModel = (
+  settings: CubeIngestSettings,
+): ModelContext =>
+  ({
+    _type: CUBE_INGEST_MODEL_TYPE,
+    environmentType: settings.environmentType,
+    producerDeploymentId: settings.producerDeploymentId,
+    ...(settings.warehouse !== undefined
+      ? { warehouse: settings.warehouse }
+      : {}),
+  }) as ModelContext;
+
+export const isCubeIngestModel = (model: ModelContext): boolean =>
+  model._type === CUBE_INGEST_MODEL_TYPE;
+
+/** The same model, running on another warehouse */
+export const withCubeIngestWarehouse = (
+  model: ModelContext,
+  warehouse: string,
+): ModelContext => ({ ...model, warehouse });
+
+/** What's wrong with an ingest model, e.g. one saved by a later Cube: nothing for one Cube can use */
+export const checkCubeIngestModel = (
+  model: ModelContext,
+): readonly string[] => {
+  const problems: string[] = [];
+  if (!ENVIRONMENT_TYPES.includes(model.environmentType as string)) {
+    problems.push(
+      `Cube doesn't know the environment type "${String(model.environmentType)}"`,
+    );
+  }
+  if (
+    typeof model.producerDeploymentId !== 'string' ||
+    !/^\d+$/u.test(model.producerDeploymentId)
+  ) {
+    problems.push(`The cube's producer deployment must be a deployment id`);
+  }
+  if (model.warehouse !== undefined && !isNonEmptyString(model.warehouse)) {
+    problems.push(`The cube's warehouse must be a name`);
+  }
+  return problems;
+};
+
+/** An ingest model's settings, when Cube can use it */
+export const getCubeIngestSettings = (
+  model: ModelContext,
+): CubeIngestSettings | undefined =>
+  isCubeIngestModel(model) && !checkCubeIngestModel(model).length
+    ? {
+        environmentType:
+          model.environmentType as CubeDataProductEnvironmentType,
+        producerDeploymentId: model.producerDeploymentId as string,
+        warehouse: model.warehouse as string | undefined,
+      }
+    : undefined;
+
+/** The class a URN's environment segment names */
+const URN_ENVIRONMENT_TYPES: Readonly<
+  Record<string, CubeDataProductEnvironmentType>
+> = {
+  prod: CubeDataProductEnvironmentType.PRODUCTION,
+  'prod-parallel': CubeDataProductEnvironmentType.PRODUCTION_PARALLEL,
+};
+
+/** What an SDLC-deployed definition's URN names: its class, its project and its path */
+export interface CubeIngestUrn {
+  readonly environmentType: CubeDataProductEnvironmentType;
+  readonly groupId: string;
+  readonly artifactId: string;
+  /** The IngestDefinition element's path */
+  readonly definition: string;
+}
+
+const SDLC_DEPLOYED_URN =
+  /^urn:lakehouse:(?<environment>[^:]+):ingest:definition:alloy-git:(?<groupId>[^~]+)~(?<artifactId>[^~]+)~(?<definition>.+)$/u;
+
+/**
+ * A deployed definition's URN, when it was deployed from SDLC
+ * (`urn:lakehouse:<prod|prod-parallel>:ingest:definition:alloy-git:<group>~<artifact>~<path>`);
+ * nothing for an ad hoc one (`rest-api:`), another class, or text that isn't one
+ */
+export const parseCubeIngestUrn = (urn: string): CubeIngestUrn | undefined => {
+  const parts = SDLC_DEPLOYED_URN.exec(urn)?.groups;
+  const environment = parts?.environment;
+  const environmentType =
+    environment && Object.hasOwn(URN_ENVIRONMENT_TYPES, environment)
+      ? URN_ENVIRONMENT_TYPES[environment]
+      : undefined;
+  return parts && environmentType
+    ? {
+        environmentType,
+        groupId: parts.groupId ?? '',
+        artifactId: parts.artifactId ?? '',
+        definition: parts.definition ?? '',
+      }
+    : undefined;
+};

package/src/graph-manager/CubeIngestCatalog.ts

@@ -0,0 +1,169 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Schema } from '@finos/legend-cube';
+import type { CubeDataProductEnvironmentType } from './CubeDataProduct.js';
+import type { CubeEngineError, NodeId } from './CubeEngine.js';
+
+// The deployed ingest definitions of a host's lakehouse (PLAN §6.7), as Data
+// Cube's producer source lists them: the viewer's ingest environment for a
+// class, its producer deployments, a deployment's SDLC-deployed definitions,
+// and a definition's data sets
+
+/** A data set of a deployed ingest definition, as the definition declares it */
+export class CubeIngestDataSet {
+  readonly name: string;
+  /** Its columns: the declared ones, then the milestoning ones of its write mode; none when they can't be read */
+  readonly schema: Schema | undefined;
+  /** Why it can't be picked, e.g. it is a materialized view; none when it can */
+  readonly disabledReason: string | undefined;
+  readonly primaryKey: readonly string[];
+
+  constructor(fields: {
+    name: string;
+    schema?: Schema | undefined;
+    disabledReason?: string | undefined;
+    primaryKey?: readonly string[];
+  }) {
+    this.name = fields.name;
+    this.schema = fields.schema;
+    this.disabledReason = fields.disabledReason;
+    this.primaryKey = fields.primaryKey ?? [];
+  }
+
+  get isPickable(): boolean {
+    return this.disabledReason === undefined && this.schema !== undefined;
+  }
+}
+
+/** The viewer's ingest environment for a class: shown in the Ingest tab, never saved */
+export class CubeIngestEnvironment {
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** The environment's name, as the platform lists it */
+  readonly name: string;
+  /** The environment a run's lakehouse runtime names */
+  readonly runtimeEnvironment: string;
+
+  constructor(fields: {
+    environmentType: CubeDataProductEnvironmentType;
+    name: string;
+    runtimeEnvironment: string;
+  }) {
+    this.environmentType = fields.environmentType;
+    this.name = fields.name;
+    this.runtimeEnvironment = fields.runtimeEnvironment;
+  }
+}
+
+/** A producer deployment of the viewer's ingest environment */
+export class CubeIngestProducer {
+  /** Its deployment id, as text */
+  readonly deploymentId: string;
+  readonly urn: string;
+
+  constructor(fields: { deploymentId: string; urn: string }) {
+    this.deploymentId = fields.deploymentId;
+    this.urn = fields.urn;
+  }
+}
+
+/** A definition a producer deployment deployed from SDLC */
+export class CubeIngestDefinitionCandidate {
+  readonly urn: string;
+  /** The IngestDefinition element's path */
+  readonly definition: string;
+  readonly groupId: string;
+  readonly artifactId: string;
+
+  constructor(fields: {
+    urn: string;
+    definition: string;
+    groupId: string;
+    artifactId: string;
+  }) {
+    this.urn = fields.urn;
+    this.definition = fields.definition;
+    this.groupId = fields.groupId;
+    this.artifactId = fields.artifactId;
+  }
+
+  /** The definition's element name: the last segment of its path */
+  get name(): string {
+    const index = this.definition.lastIndexOf('::');
+    return index < 0 ? this.definition : this.definition.slice(index + 2);
+  }
+}
+
+/** A producer deployment's definitions: those Cube reads, and how many it left out */
+export interface CubeIngestDefinitionList {
+  readonly candidates: readonly CubeIngestDefinitionCandidate[];
+  /** Definitions not deployed from SDLC, or deployed to another class */
+  readonly droppedCount: number;
+}
+
+/** Where a saved ingest source's data set is */
+export interface CubeIngestDataSetLocation {
+  readonly ingestDefinitionUrn: string;
+  readonly ingestDefinition: string;
+  readonly dataSet: string;
+}
+
+/**
+ * The deployed ingest definitions, for the source dialog and for re-checking
+ * saved sources: its own port, so hosts without them need none. Calls fail
+ * with a `CubeEngineError`: with no node for listing and describing, with
+ * the node's id for schemas
+ */
+export interface CubeIngestCatalog {
+  /** The classes the host lists, the default first */
+  readonly environmentTypes: readonly CubeDataProductEnvironmentType[];
+
+  /** The viewer's ingest environment for a class */
+  resolveEnvironment(
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<CubeIngestEnvironment>;
+
+  /** The producer deployments of the viewer's ingest environment for a class */
+  listProducers(
+    environmentType: CubeDataProductEnvironmentType,
+  ): Promise<readonly CubeIngestProducer[]>;
+
+  /** A producer deployment's SDLC-deployed definitions of the class */
+  listDefinitions(
+    environmentType: CubeDataProductEnvironmentType,
+    producerDeploymentId: string,
+  ): Promise<CubeIngestDefinitionList>;
+
+  /**
+   * A definition's data sets, typed from what it declares. `fresh` reads the
+   * definition again rather than what this page visit read
+   */
+  describe(
+    urn: string,
+    environmentType: CubeDataProductEnvironmentType,
+    options?: { readonly fresh?: boolean | undefined },
+  ): Promise<readonly CubeIngestDataSet[]>;
+
+  /**
+   * The schema of each saved source, from its definition as deployed: one
+   * entry per key, failures included. `fresh` reads the definitions again
+   */
+  resolveSchemas(
+    environmentType: CubeDataProductEnvironmentType,
+    sources: ReadonlyMap<NodeId, CubeIngestDataSetLocation>,
+    options?: { readonly fresh?: boolean | undefined },
+  ): Promise<Map<NodeId, Schema | CubeEngineError>>;
+}

package/src/graph-manager/CubeLakehouseEnvironment.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { CubeDataProductProject } from './CubeDataProduct.js';
+
+/**
+ * The viewer's lakehouse environment (PLAN §6.8), which a data product run
+ * names in its lakehouse runtime: its own port, so hosts without a lakehouse
+ * need none. Fails with a `CubeEngineError` when the viewer has none
+ */
+export interface CubeLakehouseEnvironment {
+  /** The viewer's environment for the project's class, e.g. `env`, or `env-pp` for production-parallel */
+  resolveEnvironment(project: CubeDataProductProject): Promise<string>;
+}

package/src/graph-manager/CubeModelOutlineHelper.ts

@@ -30,3 +30,29 @@ export const getRuntimesForDatabase = (
   outline.runtimes.filter((runtime) =>
     runtime.storePaths.includes(databasePath),
   );
+
+/**
+ * The database type a query on these databases runs on with the runtime, for
+ * the operations some databases take another way (PLAN §11.4): the type of
+ * the runtime's connections to them. None when the runtime isn't in the
+ * outline, a database has no typed connection, or the databases' types
+ * differ: the native forms are written then.
+ */
+export const getDatabaseType = (
+  outline: CubeModelOutline,
+  runtimePath: string,
+  databasePaths: readonly string[],
+): string | undefined => {
+  const runtime = outline.runtimes.find(({ path }) => path === runtimePath);
+  const types = new Set<string>();
+  for (const databasePath of new Set(databasePaths)) {
+    const databaseTypes = (runtime?.connections ?? [])
+      .filter(({ storePath }) => storePath === databasePath)
+      .map(({ databaseType }) => databaseType);
+    if (!databaseTypes.length) {
+      return undefined;
+    }
+    databaseTypes.forEach((databaseType) => types.add(databaseType));
+  }
+  return types.size === 1 ? [...types][0] : undefined;
+};

package/src/graph-manager/CubeProject.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ModelContext } from '@finos/legend-cube';
+
+// A cube on a published project's Database (PLAN §6.2.2, §6.3) saves the
+// project at one released version as its model: the engine's alloy pointer,
+// sent to the engine as saved, which fetches the project from its depot. The
+// saved runtime is one of the project's own.
+
+/** The engine's model kind of a project pointer */
+export const CUBE_PROJECT_MODEL_TYPE = 'pointer';
+const ALLOY_SDLC_TYPE = 'alloy';
+
+/** A published project at one version */
+export interface CubeProjectCoordinates {
+  readonly groupId: string;
+  readonly artifactId: string;
+  readonly versionId: string;
+}
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.length > 0;
+
+/** Whether a version can move: a SNAPSHOT, or the depot's `latest` and `HEAD` aliases */
+export const isCubeMovingProjectVersion = (versionId: string): boolean =>
+  versionId.endsWith('SNAPSHOT') ||
+  versionId === 'latest' ||
+  versionId === 'HEAD';
+
+/** The model of a cube on a project's Database */
+export const createCubeProjectModel = (
+  project: CubeProjectCoordinates,
+): ModelContext =>
+  ({
+    _type: CUBE_PROJECT_MODEL_TYPE,
+    sdlcInfo: {
+      _type: ALLOY_SDLC_TYPE,
+      groupId: project.groupId,
+      artifactId: project.artifactId,
+      version: project.versionId,
+      packageableElementPointers: [],
+    },
+  }) as unknown as ModelContext;
+
+const sdlcInfoOf = (
+  model: ModelContext,
+): Record<string, unknown> | undefined => {
+  const sdlcInfo = model.sdlcInfo;
+  return sdlcInfo && typeof sdlcInfo === 'object' && !Array.isArray(sdlcInfo)
+    ? (sdlcInfo as Record<string, unknown>)
+    : undefined;
+};
+
+/** Whether the model is a project pointer, whether or not Cube can run it */
+export const isCubeProjectModel = (model: ModelContext): boolean =>
+  model._type === CUBE_PROJECT_MODEL_TYPE &&
+  sdlcInfoOf(model)?._type === ALLOY_SDLC_TYPE;
+
+/**
+ * Why Cube can't run a project model, in words a user can act on; none when
+ * it can. Only released versions are read (user, 2026-10-09): a version that
+ * moves would change a saved cube's tables under it
+ */
+export const checkCubeProjectModel = (
+  model: ModelContext,
+): readonly string[] => {
+  const sdlcInfo = sdlcInfoOf(model);
+  if (!sdlcInfo) {
+    return [`The cube's project has no coordinates`];
+  }
+  const problems: string[] = [];
+  (['groupId', 'artifactId', 'version'] as const).forEach((key) => {
+    if (!isNonEmptyString(sdlcInfo[key])) {
+      problems.push(`The cube's project has no ${key}`);
+    }
+  });
+  const version = sdlcInfo.version;
+  if (isNonEmptyString(version) && isCubeMovingProjectVersion(version)) {
+    problems.push(
+      `Cube reads released versions only, not ${version}: pick a released version`,
+    );
+  }
+  return problems;
+};
+
+/** The project of a project model Cube can run; undefined for any other model */
+export const getCubeProjectCoordinates = (
+  model: ModelContext,
+): CubeProjectCoordinates | undefined => {
+  if (!isCubeProjectModel(model) || checkCubeProjectModel(model).length) {
+    return undefined;
+  }
+  const sdlcInfo = sdlcInfoOf(model) as Record<string, string>;
+  return {
+    groupId: sdlcInfo.groupId as string,
+    artifactId: sdlcInfo.artifactId as string,
+    versionId: sdlcInfo.version as string,
+  };
+};
+
+/** The project as people read it: `group:artifact` at its version */
+export const formatCubeProject = (project: CubeProjectCoordinates): string =>
+  `${project.groupId}:${project.artifactId} ${project.versionId}`;

package/src/graph-manager/CubeProjectCatalog.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { CubeModelOutline } from './CubeEngine.js';
+import type { CubeProjectCoordinates } from './CubeProject.js';
+
+// The published projects a cube can read Databases from (PLAN §6.3): the
+// port the source dialog's Project tab reads, over the host's depot
+
+/** A published project, without a version */
+export interface CubeProjectSummary {
+  readonly groupId: string;
+  readonly artifactId: string;
+}
+
+export interface CubeProjectCatalog {
+  /** Every published project, by group and artifact */
+  listProjects(): Promise<readonly CubeProjectSummary[]>;
+  /** The project's released versions, newest first: never a SNAPSHOT or an alias */
+  listVersions(project: CubeProjectSummary): Promise<readonly string[]>;
+  /**
+   * The project's own Databases at the version, and the runtimes of the
+   * project and its dependencies; a dependency's Databases are not offered
+   * (user, 2026-10-09)
+   */
+  loadOutline(project: CubeProjectCoordinates): Promise<CubeModelOutline>;
+}

package/src/graph-manager/protocol/pure/CubeEngineBuilder.ts

@@ -14,8 +14,29 @@
  * limitations under the License.
  */
 
+import type { DepotServerClient } from '@finos/legend-server-depot';
+import { V1_EngineServerClient } from '@finos/legend-graph';
+import type {
+  LakehouseContractServerClient,
+  LakehouseIngestServerClient,
+  LakehousePlatformServerClient,
+} from '@finos/legend-server-lakehouse';
+import type { MarketplaceServerClient } from '@finos/legend-server-marketplace';
 import type { TracerService } from '@finos/legend-shared';
+import type { CubeConnectionExplorer } from '../../CubeConnectionExplorer.js';
+import type {
+  CubeDataProductCatalog,
+  CubeMarketplaceLinkTarget,
+} from '../../CubeDataProductCatalog.js';
 import type { CubeEngine } from '../../CubeEngine.js';
+import type { CubeIngestCatalog } from '../../CubeIngestCatalog.js';
+import type { CubeLakehouseEnvironment } from '../../CubeLakehouseEnvironment.js';
+import type { CubeProjectCatalog } from '../../CubeProjectCatalog.js';
+import { V1_CubeLakehouseEnvironmentResolver } from './v1/V1_CubeLakehouseEnvironmentResolver.js';
+import { V1_LegendCubeConnectionExplorer } from './v1/V1_LegendCubeConnectionExplorer.js';
+import { V1_LegendCubeDataProductCatalog } from './v1/V1_LegendCubeDataProductCatalog.js';
+import { V1_LegendCubeIngestCatalog } from './v1/V1_LegendCubeIngestCatalog.js';
+import { V1_LegendCubeProjectCatalog } from './v1/V1_LegendCubeProjectCatalog.js';
 import {
   type V1_CubeEngineConfig,
   V1_LegendCubeEngine,
@@ -31,4 +52,127 @@ export type CubeEngineConfig = V1_CubeEngineConfig;
 export const buildCubeEngine = (
   config: CubeEngineConfig,
   tracerService: TracerService,
-): CubeEngine => new V1_LegendCubeEngine(config, tracerService);
+  options?: {
+    /** Data product cubes run only with one */
+    lakehouseEnvironment?: CubeLakehouseEnvironment | undefined;
+    /** The warehouse the viewer last picked, for a data product cube without its own */
+    getRememberedWarehouse?: (() => string | undefined) | undefined;
+    /** Ingest cubes run only with one, built by `buildCubeIngestCatalog` */
+    ingestCatalog?: CubeIngestCatalog | undefined;
+  },
+): CubeEngine =>
+  new V1_LegendCubeEngine(config, tracerService, {
+    lakehouseEnvironment: options?.lakehouseEnvironment,
+    getRememberedWarehouse: options?.getRememberedWarehouse,
+    // the catalog reads the definitions the engine types and runs on
+    ingestDefinitions:
+      options?.ingestCatalog instanceof V1_LegendCubeIngestCatalog
+        ? options.ingestCatalog
+        : undefined,
+  });
+
+/**
+ * The connection explorer of a host that offers direct connections (PLAN
+ * §6.8), over the same engine as its Cube engine
+ */
+export const buildCubeConnectionExplorer = (
+  config: CubeEngineConfig,
+  tracerService: TracerService,
+): CubeConnectionExplorer =>
+  new V1_LegendCubeConnectionExplorer(config, tracerService);
+
+/** What a host gives Cube to read its deployed data products (PLAN §6.8) */
+export interface CubeLakehouseServices {
+  readonly contractServerClient: LakehouseContractServerClient;
+  readonly depotServerClient: DepotServerClient;
+  readonly getAccessToken: () => string | undefined;
+  /** The viewer, whose lakehouse environment data product runs use */
+  readonly getCurrentUser: () => string;
+  /** The environment the host remembers for the viewer, used before their entitlements' first one */
+  readonly getPreferredEnvironment?: (() => string | undefined) | undefined;
+  /** The marketplace's search API: with it, the source dialog searches there, never reading the lakehouse's whole list */
+  readonly marketplaceServerClient?: MarketplaceServerClient | undefined;
+  /** A deployed data product's page in the host's marketplace; none when the host has no marketplace */
+  readonly getMarketplaceLink?:
+    | ((target: CubeMarketplaceLinkTarget) => string | undefined)
+    | undefined;
+  /**
+   * The stereotype the host's marketplace marks access point groups open to
+   * everyone with; without it, a group with no contract shows no access
+   */
+  readonly enterpriseStereotype?:
+    | { readonly profile: string; readonly value: string }
+    | undefined;
+  /** The lakehouse platform, whose ingest environments the Ingest tab reads (PLAN §6.7) */
+  readonly platformServerClient?: LakehousePlatformServerClient | undefined;
+  /** A client for the ingest servers the platform names: each call names its server */
+  readonly ingestServerClient?: LakehouseIngestServerClient | undefined;
+}
+
+/** The deployed data products of a host with a lakehouse and a depot */
+export const buildCubeDataProductCatalog = (
+  services: CubeLakehouseServices,
+): CubeDataProductCatalog =>
+  new V1_LegendCubeDataProductCatalog(
+    services.contractServerClient,
+    services.depotServerClient,
+    services.getAccessToken,
+    {
+      marketplaceServerClient: services.marketplaceServerClient,
+      marketplaceLink: services.getMarketplaceLink,
+      getCurrentUser: services.getCurrentUser,
+      enterpriseStereotype: services.enterpriseStereotype,
+    },
+  );
+
+/**
+ * The published projects a cube reads Databases from (PLAN §6.3), through
+ * the host's depot. It reads nothing until the source dialog's Project tab
+ * asks
+ */
+export const buildCubeProjectCatalog = (
+  depotServerClient: DepotServerClient,
+): CubeProjectCatalog => new V1_LegendCubeProjectCatalog(depotServerClient);
+
+/** The viewer's lakehouse environment, which the engine needs to run data product cubes */
+export const buildCubeLakehouseEnvironment = (
+  services: CubeLakehouseServices,
+): CubeLakehouseEnvironment =>
+  new V1_CubeLakehouseEnvironmentResolver(
+    services.contractServerClient,
+    services.getAccessToken,
+    services.getCurrentUser,
+    services.getPreferredEnvironment,
+  );
+
+/**
+ * The deployed ingest definitions of a host with a lakehouse platform (PLAN
+ * §6.7), or none without one. It parses definitions with the engine Cube
+ * uses; pass it to `buildCubeEngine` too, so ingest cubes run
+ */
+export const buildCubeIngestCatalog = (
+  config: CubeEngineConfig,
+  tracerService: TracerService,
+  services: CubeLakehouseServices,
+): CubeIngestCatalog | undefined => {
+  const { platformServerClient, ingestServerClient } = services;
+  if (!platformServerClient || !ingestServerClient) {
+    return undefined;
+  }
+  const engineClient = new V1_EngineServerClient(config);
+  // every call throws without one
+  engineClient.setTracerService(tracerService);
+  const environment = new V1_CubeLakehouseEnvironmentResolver(
+    services.contractServerClient,
+    services.getAccessToken,
+    services.getCurrentUser,
+    services.getPreferredEnvironment,
+  );
+  return new V1_LegendCubeIngestCatalog(
+    platformServerClient,
+    ingestServerClient,
+    () => environment.resolveBaseEnvironment(),
+    (code) => engineClient.grammarToJSON_model(code),
+    services.getAccessToken,
+  );
+};