@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/graph-manager/CubeDataProductCatalog.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 { PlainObject } from '@finos/legend-shared';
+import {
+  type CubeDataProductEnvironmentType,
+  type CubeDataProductProject,
+  isCubeSnapshotVersion,
+} from './CubeDataProduct.js';
+import type { CubeEngineError, CubeResultValue, NodeId } from './CubeEngine.js';
+
+// The deployed data products a cube can read (PLAN §6.8), in Cube's own
+// terms: what the catalog lists, what a product's deployed artifact says of
+// its access points, and the schemas of saved sources. The host's
+// implementation reads the marketplace or the lakehouse's lists, the depot
+// and the artifacts; nothing here names their wire classes
+
+/** A deployed data product the catalog lists, at the version it was deployed from */
+export class CubeDataProductCandidate {
+  /** The catalog's id for the product, which its links use */
+  readonly id: string;
+  /** The deployment, as text */
+  readonly deploymentId: string;
+  /** The path of its DataProduct element */
+  readonly dataProductPath: string;
+  readonly title: string;
+  readonly description: string | undefined;
+  readonly groupId: string;
+  readonly artifactId: string;
+  /** The version it was deployed from, as the catalog gave it, snapshots included */
+  readonly versionId: string;
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** The producer's environment, for display */
+  readonly producerEnvironmentName: string | undefined;
+
+  constructor(fields: {
+    id: string;
+    deploymentId: string;
+    dataProductPath: string;
+    title: string;
+    description?: string | undefined;
+    groupId: string;
+    artifactId: string;
+    versionId: string;
+    environmentType: CubeDataProductEnvironmentType;
+    producerEnvironmentName?: string | undefined;
+  }) {
+    this.id = fields.id;
+    this.deploymentId = fields.deploymentId;
+    this.dataProductPath = fields.dataProductPath;
+    this.title = fields.title;
+    this.description = fields.description;
+    this.groupId = fields.groupId;
+    this.artifactId = fields.artifactId;
+    this.versionId = fields.versionId;
+    this.environmentType = fields.environmentType;
+    this.producerEnvironmentName = fields.producerEnvironmentName;
+  }
+
+  /** Whether it was deployed from a moving version, whose data may change under a cube */
+  get isSnapshot(): boolean {
+    return isCubeSnapshotVersion(this.versionId);
+  }
+}
+
+/** An access point of a deployed product, as its artifact describes it */
+export class CubeAccessPoint {
+  readonly id: string;
+  readonly title: string | undefined;
+  readonly description: string | undefined;
+  /** Its columns, as the artifact types them; none when it can't be read */
+  readonly schema: Schema | undefined;
+  /** Why it can't be picked, e.g. it takes parameters; none when it can */
+  readonly disabledReason: string | undefined;
+  /** A few rows the artifact holds, by the schema's columns */
+  readonly sampleRows: readonly (readonly CubeResultValue[])[];
+
+  constructor(fields: {
+    id: string;
+    title?: string | undefined;
+    description?: string | undefined;
+    schema?: Schema | undefined;
+    disabledReason?: string | undefined;
+    sampleRows?: readonly (readonly CubeResultValue[])[];
+  }) {
+    this.id = fields.id;
+    this.title = fields.title;
+    this.description = fields.description;
+    this.schema = fields.schema;
+    this.disabledReason = fields.disabledReason;
+    this.sampleRows = fields.sampleRows ?? [];
+  }
+
+  get isPickable(): boolean {
+    return this.disabledReason === undefined && this.schema !== undefined;
+  }
+}
+
+export class CubeAccessPointGroup {
+  readonly id: string;
+  readonly title: string | undefined;
+  readonly accessPoints: readonly CubeAccessPoint[];
+  /** Open to everyone in the organization, as the host's marketplace marks such groups */
+  readonly isEnterprise: boolean;
+
+  constructor(fields: {
+    id: string;
+    title?: string | undefined;
+    accessPoints: readonly CubeAccessPoint[];
+    isEnterprise?: boolean | undefined;
+  }) {
+    this.id = fields.id;
+    this.title = fields.title;
+    this.accessPoints = fields.accessPoints;
+    this.isEnterprise = fields.isEnterprise ?? false;
+  }
+}
+
+/**
+ * The viewer's access to an access point group, as the marketplace shows
+ * it: open to everyone, granted, on its way through approval, refused, or
+ * never asked for
+ */
+export enum CubeAccessPointGroupAccess {
+  ENTERPRISE = 'ENTERPRISE',
+  APPROVED = 'APPROVED',
+  SUBMITTED_FOR_APPROVALS = 'SUBMITTED_FOR_APPROVALS',
+  PENDING_MANAGER_APPROVAL = 'PENDING_MANAGER_APPROVAL',
+  PENDING_DATA_OWNER_APPROVAL = 'PENDING_DATA_OWNER_APPROVAL',
+  DENIED = 'DENIED',
+  NO_ACCESS = 'NO_ACCESS',
+}
+
+/** A deployed product's access points, by group */
+export class CubeDataProductDescription {
+  readonly candidate: CubeDataProductCandidate;
+  readonly groups: readonly CubeAccessPointGroup[];
+
+  constructor(
+    candidate: CubeDataProductCandidate,
+    groups: readonly CubeAccessPointGroup[],
+  ) {
+    this.candidate = candidate;
+    this.groups = groups;
+  }
+}
+
+/** Where a saved source's access point is */
+export interface CubeAccessPointLocation {
+  readonly dataProduct: string;
+  readonly accessPointGroup: string;
+  readonly accessPoint: string;
+}
+
+/** What a marketplace link points at */
+export interface CubeMarketplaceLinkTarget {
+  readonly dataProductId: string;
+  readonly deploymentId: string;
+  readonly environmentType: CubeDataProductEnvironmentType;
+  readonly accessPointGroup?: string | undefined;
+}
+
+/**
+ * The deployed data products, for the source dialog and for re-checking
+ * saved sources: its own port, beside the `CubeEngine`, so hosts without
+ * data products need neither. Calls fail with a `CubeEngineError`: with no
+ * node for listing and describing, with the node's id for schemas
+ */
+export interface CubeDataProductCatalog {
+  /** The deployment classes the host lists, the default first */
+  readonly environmentTypes: readonly CubeDataProductEnvironmentType[];
+
+  /**
+   * Whether `search` matches and ranks the text on a server. Otherwise the
+   * text is matched on the client, over the class's whole list
+   */
+  readonly searchesOnServer?: boolean | undefined;
+
+  /** The most products one server search gives: an answer this long may be cut short */
+  readonly searchLimit?: number | undefined;
+
+  /**
+   * Whether an answer `search` gave leaves out matches the server has, as
+   * its page says, counting rows the catalog dropped. Without it, an answer
+   * as long as `searchLimit` is taken to be cut short
+   */
+  readonly isCutShort?:
+    | ((answer: readonly CubeDataProductCandidate[]) => boolean)
+    | undefined;
+
+  /**
+   * The deployed products of a class whose title, id or description holds
+   * the text, or, searching on a server, the ones it matches, in its order
+   */
+  search(
+    search: {
+      text: string;
+      environmentType: CubeDataProductEnvironmentType;
+    },
+    signal?: AbortSignal,
+  ): Promise<readonly CubeDataProductCandidate[]>;
+
+  /** A product's access points, read from its artifact at the version it was deployed from */
+  describe(
+    candidate: CubeDataProductCandidate,
+    signal?: AbortSignal,
+  ): Promise<CubeDataProductDescription>;
+
+  /**
+   * The schema of each saved source, from the artifact at the cube's
+   * version: one entry per key, failures included. `fresh` reads the
+   * artifact again rather than what this page visit read, e.g. on Refresh
+   */
+  resolveSchemas(
+    project: CubeDataProductProject,
+    sources: ReadonlyMap<NodeId, CubeAccessPointLocation>,
+    options?: { readonly fresh?: boolean | undefined },
+  ): Promise<Map<NodeId, Schema | CubeEngineError>>;
+
+  /** The product's page in the marketplace, or none when the host has no marketplace */
+  getMarketplaceLink(target: CubeMarketplaceLinkTarget): string | undefined;
+
+  /**
+   * The viewer's access to each of the product's access point groups, by
+   * group id; a group it can't tell has no entry. Optional: a host without
+   * it shows no access
+   */
+  getAccess?(
+    candidate: CubeDataProductCandidate,
+    signal?: AbortSignal,
+  ): Promise<ReadonlyMap<string, CubeAccessPointGroupAccess>>;
+}
+
+/**
+ * Where a data product cube's engine reads the project its data products
+ * are in, as protocol JSON: by default the project at the version they were
+ * deployed from (a pointer); a host's own, e.g. Studio's workspace, whose
+ * data products aren't deployed. Fails with a `CubeEngineError`
+ */
+export interface CubeDataProductModelSource {
+  getProjectModel(project: CubeDataProductProject): Promise<PlainObject>;
+}

package/src/graph-manager/CubeDirectConnection.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type {
+  CubeDirectConnection,
+  CubeExploredTable,
+} from './CubeConnectionExplorer.js';
+
+// A direct-connection cube (PLAN §6.8) saves its connection once, as its
+// model, and its tables stay ordinary relational sources of one generated
+// Database. The engine's implementation builds that Database, its connection
+// and its runtime for each call, from the tables the call needs; their paths
+// are fixed, so saved tables and the saved runtime always name them
+
+/** The kind of a direct-connection cube's model: Cube's own, never an engine model kind */
+export const CUBE_DIRECT_MODEL_TYPE = 'cubeDirectConnection';
+
+/** The Database every table of a direct-connection cube belongs to */
+export const CUBE_DIRECT_DATABASE_PATH = 'cube::direct::Database';
+export const CUBE_DIRECT_CONNECTION_PATH = 'cube::direct::Connection';
+/** The runtime a direct-connection cube runs with */
+export const CUBE_DIRECT_RUNTIME_PATH = 'cube::direct::Runtime';
+
+/** The model of a direct-connection cube */
+export const createCubeDirectModel = (
+  connection: CubeDirectConnection,
+): ModelContext =>
+  // the connection is protocol JSON, so plain JSON
+  ({ _type: CUBE_DIRECT_MODEL_TYPE, connection }) as unknown as ModelContext;
+
+/** The connection of a direct-connection cube's model; undefined for any other model */
+export const getCubeDirectConnection = (
+  model: ModelContext,
+): CubeDirectConnection | undefined =>
+  model._type === CUBE_DIRECT_MODEL_TYPE &&
+  model.connection &&
+  typeof model.connection === 'object' &&
+  !Array.isArray(model.connection)
+    ? (model.connection as CubeDirectConnection)
+    : undefined;
+
+/**
+ * The coordinates of a table read from the connection's database, every name
+ * quoted as the built Database stores it
+ */
+export const getCubeDirectTableCoordinates = (
+  schema: string,
+  table: CubeExploredTable,
+): { database: string; schema: string; table: string } => ({
+  database: CUBE_DIRECT_DATABASE_PATH,
+  schema: `"${schema}"`,
+  table: table.storedName,
+});

package/src/graph-manager/CubeEngine.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { IR, ModelContext, Schema } from '@finos/legend-cube';
+import type { IR, JsonObject, ModelContext, Schema } from '@finos/legend-cube';
 
 // The engine port (PLAN §8.7): what Cube asks of an engine, in Cube's own
 // terms. Only its Legend implementation, under `protocol/pure/v1/`, knows the
@@ -84,10 +84,45 @@ export interface CubeOutlineRuntime {
   readonly connections?: readonly CubeOutlineConnection[];
 }
 
-/** What a model offers the source picker: its databases and runtimes, as plain data */
+/** A parameter of a function, as its signature declares it */
+export interface CubeOutlineFunctionParameter {
+  readonly name: string;
+  /** Its type's path, as written, e.g. `Float` */
+  readonly type: string;
+  /** Its multiplicity, as written, e.g. `[1]`, `[0..1]` or `[*]` */
+  readonly multiplicity: string;
+}
+
+/** A column a function declares it returns, e.g. `ID:Integer` */
+export interface CubeOutlineFunctionColumn {
+  readonly name: string;
+  readonly type: string;
+}
+
+/** A function of a model that returns a relation (PLAN §6.5), as plain data */
+export interface CubeOutlineFunction {
+  /** The path the lambda calls it by, e.g. `sales::ordersAbove` */
+  readonly path: string;
+  /** The engine's full name, e.g. `sales::ordersAbove_Float_1__Relation_1_` */
+  readonly signature: string;
+  readonly parameters: readonly CubeOutlineFunctionParameter[];
+  readonly columns: readonly CubeOutlineFunctionColumn[];
+  /**
+   * The runtime it reads through, as its body's `from()` names it, directly
+   * or through a function it calls; none when it leaves the runtime to its
+   * caller
+   */
+  readonly runtime?: string | undefined;
+  /** Why it can't be added, e.g. a parameter Cube can't take a value for */
+  readonly problem?: string | undefined;
+}
+
+/** What a model offers the source picker: its databases, runtimes and functions, as plain data */
 export interface CubeModelOutline {
   readonly databases: readonly CubeOutlineDatabase[];
   readonly runtimes: readonly CubeOutlineRuntime[];
+  /** Its functions that return a relation; optional, as an outline from before them has none */
+  readonly functions?: readonly CubeOutlineFunction[] | undefined;
 }
 
 export enum CubeEngineErrorKind {
@@ -101,6 +136,30 @@ export enum CubeEngineErrorKind {
   NETWORK = 'network',
 }
 
+/**
+ * Where in a text the engine places a problem: the source id the text was
+ * parsed under, and its 1-based first and last lines and columns, the last
+ * column included (an Extend column's expression, PLAN §11.7)
+ */
+export interface CubeSourceLocation {
+  readonly sourceId: string;
+  readonly startLine: number;
+  readonly startColumn: number;
+  readonly endLine: number;
+  readonly endColumn: number;
+}
+
+/**
+ * An expression's text as the engine's JSON (PLAN §11.7), its number
+ * literals as their digit strings: as a column stores it, with no source
+ * information, and as the engine located it in the text, so a later error
+ * can point into the text
+ */
+export interface CubeParsedExpression {
+  readonly lambda: JsonObject;
+  readonly located: JsonObject;
+}
+
 /**
  * An engine failure, placed on the node it concerns: the node a stamp in the
  * error points to, else the source being typed or the node being run.
@@ -114,12 +173,15 @@ export class CubeEngineError extends Error {
   readonly firstLine: string;
   /** The engine's whole message, without its Java trace, shown in the panel */
   readonly detail: string;
+  /** Where in a text the error is, when the text was parsed with its locations */
+  readonly location: CubeSourceLocation | undefined;
 
   constructor(
     kind: CubeEngineErrorKind,
     detail: string,
     nodeId?: NodeId,
     role?: string,
+    location?: CubeSourceLocation,
   ) {
     const firstLine = detail.split('\n', 1)[0]?.trim() ?? '';
     super(firstLine);
@@ -129,6 +191,7 @@ export class CubeEngineError extends Error {
     this.firstLine = firstLine;
     this.nodeId = nodeId;
     this.role = role;
+    this.location = location;
   }
 }
 
@@ -164,6 +227,35 @@ export interface CubeEngine {
     lambda: IR,
     options?: { abortController?: AbortController | undefined },
   ): Promise<CubeResult>;
+  /**
+   * Runs an execution lambda and gives its rows as CSV text (PLAN §11.10):
+   * the engine's own, a header row first, every value as the engine writes
+   * it; rejects with a `CubeEngineError`
+   */
+  exportCsv(
+    model: ModelContext,
+    lambda: IR,
+    options?: { abortController?: AbortController | undefined },
+  ): Promise<string>;
   /** The Pure text of a lambda, for display only: never parsed back */
   renderPure(lambda: IR): Promise<string>;
+  /**
+   * A lambda as the engine receives it, pretty-printed, its numbers kept
+   * exact (PLAN §11.16): for a viewer to copy while debugging a run
+   */
+  serializeLambda(lambda: IR): string;
+  /**
+   * An Extend column's expression as the engine's JSON (PLAN §11.7), located
+   * under the source id; rejects with a `CubeEngineError` placed in the text
+   */
+  parseExpression(
+    code: string,
+    sourceId: string,
+  ): Promise<CubeParsedExpression>;
+  /**
+   * Plans an execution lambda for its runtime's database, as a run would,
+   * without running it: some expressions type, then fail when planned (PLAN
+   * §11.7). Rejects with a `CubeEngineError`
+   */
+  planLambda(model: ModelContext, lambda: IR): Promise<void>;
 }

package/src/graph-manager/CubeEngineClientSettings.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+/** What Dev Settings changes on an engine client: the engine server client's own setters */
+export interface CubeEngineClientControls {
+  setBaseUrl(url: string | undefined): void;
+  setCompression(enabled: boolean): void;
+}
+
+/**
+ * The settings every engine client of Cube shares (PLAN §11.16): the
+ * engine's URL and whether requests are compressed. The engine, the
+ * connection explorer and the catalogs each have their own client, built
+ * from the same configuration; each registers here, so Dev Settings changes
+ * them all at once. A change takes effect from the next request.
+ */
+export class CubeEngineClientSettings {
+  /** The URL the host configured, to go back to */
+  readonly defaultBaseUrl: string | undefined;
+  baseUrl: string | undefined;
+  requestCompression: boolean;
+  private readonly clients: CubeEngineClientControls[] = [];
+
+  constructor(config: {
+    readonly baseUrl?: string | undefined;
+    readonly enableCompression?: boolean | undefined;
+  }) {
+    this.defaultBaseUrl = config.baseUrl;
+    this.baseUrl = config.baseUrl;
+    this.requestCompression = Boolean(config.enableCompression);
+  }
+
+  /** Adds a client built from the same configuration, given the settings changed since */
+  register(client: CubeEngineClientControls): void {
+    this.clients.push(client);
+    if (this.baseUrl !== this.defaultBaseUrl) {
+      client.setBaseUrl(this.baseUrl);
+    }
+    client.setCompression(this.requestCompression);
+  }
+
+  setBaseUrl(url: string | undefined): void {
+    this.baseUrl = url;
+    this.clients.forEach((client) => client.setBaseUrl(url));
+  }
+
+  setRequestCompression(enabled: boolean): void {
+    this.requestCompression = enabled;
+    this.clients.forEach((client) => client.setCompression(enabled));
+  }
+}

package/src/graph-manager/CubeIngest.ts

@@ -0,0 +1,159 @@
+/**
+ * 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;
+}
+
+/** The URN's environment segment of each class */
+const URN_ENVIRONMENTS: Readonly<
+  Record<CubeDataProductEnvironmentType, string>
+> = {
+  [CubeDataProductEnvironmentType.PRODUCTION]: 'prod',
+  [CubeDataProductEnvironmentType.PRODUCTION_PARALLEL]: 'prod-parallel',
+};
+
+/**
+ * The URN of a definition deployed from SDLC, as `parseCubeIngestUrn` reads
+ * it: for a host naming definitions of its own, e.g. Studio's workspace
+ */
+export const formatCubeIngestUrn = (urn: CubeIngestUrn): string =>
+  `urn:lakehouse:${URN_ENVIRONMENTS[urn.environmentType]}:ingest:definition:alloy-git:${urn.groupId}~${urn.artifactId}~${urn.definition}`;
+
+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;
+};