@finos/legend-cube-builder 0.0.2 → 0.0.4

package/src/components/spec-transfer/CubeSpecTransferDialog.tsx

@@ -52,7 +52,7 @@ export const CubeSpecTransferDialog = observer(
         <Modal darkMode={darkMode} className="w-[720px] max-w-full">
           <ModalHeader>
             <div className="modal__title">
-              {isExport ? 'Export spec (dev)' : 'Import spec (dev)'}
+              {isExport ? 'Export spec' : 'Import spec'}
             </div>
           </ModalHeader>
           <PanelLoadingIndicator isLoading={transfer.isReadingFile} />

package/src/graph-manager/CubeConnectionExplorer.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { PlainObject } from '@finos/legend-shared';
+import type { CubeTableFlag } from './CubeEngine.js';
+
+// Direct connections (PLAN §6.8), in Cube's own terms: what the connection
+// form gives, what the page shows of a saved connection, and what reading its
+// database finds. The connection itself stays opaque JSON outside
+// `protocol/pure/v1/`, which alone reads it
+
+/** The databases a direct connection can reach this round */
+export enum CubeDirectDatabaseType {
+  H2 = 'H2',
+  DUCKDB = 'DuckDB',
+}
+
+/** What the connection form gives, before it becomes a connection */
+export interface CubeConnectionDraft {
+  databaseType: CubeDirectDatabaseType;
+  /** Statements the engine runs on each connection, e.g. to create test tables */
+  setupSqls: readonly string[];
+  /** DuckDB only: a database file on the engine's host, or '' for an in-memory database */
+  path?: string | undefined;
+}
+
+/** How a database is reached, as the page shows it */
+export enum CubeConnectionDatasourceKind {
+  /** An H2 database the engine creates in its own H2 server */
+  LOCAL_H2 = 'LOCAL_H2',
+  DUCKDB_IN_MEMORY = 'DUCKDB_IN_MEMORY',
+  DUCKDB_FILE = 'DUCKDB_FILE',
+}
+
+/** What the page shows of a saved connection: never its setup SQL */
+export interface CubeConnectionSummary {
+  databaseType: CubeDirectDatabaseType;
+  datasourceKind: CubeConnectionDatasourceKind;
+  /** The DuckDB file, for a DuckDB file database */
+  path?: string | undefined;
+  setupSqlCount: number;
+  /** The authentication strategy, as the engine names it */
+  authenticationKind: string;
+}
+
+/** A table read from a connection's database, for the picker */
+export interface CubeExploredTable {
+  /** As the database stores it, e.g. `ORDER.LINES` */
+  name: string;
+  /** As a table's coordinates store it: always quoted, e.g. `"ORDER.LINES"` */
+  storedName: string;
+  /** The columns Cube can use */
+  columnCount: number;
+  /** The columns left out because the engine can't type them; Cube shows how many */
+  hiddenColumnCount: number;
+  flags: readonly CubeTableFlag[];
+}
+
+/**
+ * A direct connection as a cube saves it: protocol JSON, which only the
+ * engine's implementation reads
+ */
+export type CubeDirectConnection = PlainObject;
+
+/** What the page knows of a connection without calling the engine */
+export type CubeConnectionDescription =
+  | { supported: true; summary: CubeConnectionSummary }
+  /** Why Cube can't use the connection, in words a user can act on */
+  | { supported: false; problems: readonly string[] };
+
+/**
+ * Reading a direct connection's database (PLAN §6.8), for the picker: its own
+ * port, beside the `CubeEngine`, so hosts without direct connections need
+ * neither. Calls fail with a `CubeEngineError`, with no node
+ */
+export interface CubeConnectionExplorer {
+  /** The connection the connection form describes */
+  buildConnection(draft: CubeConnectionDraft): CubeDirectConnection;
+
+  /** Whether Cube can use a connection, and what the page shows of it: no engine call */
+  describeConnection(
+    connection: CubeDirectConnection,
+  ): CubeConnectionDescription;
+
+  /** The schemas of the connection's database, without the database's own; tests the connection */
+  listSchemas(connection: CubeDirectConnection): Promise<readonly string[]>;
+
+  /** A schema's tables and views, with how many columns Cube can use and hides */
+  listTables(
+    connection: CubeDirectConnection,
+    schema: string,
+  ): Promise<readonly CubeExploredTable[]>;
+}

package/src/graph-manager/CubeDataProduct.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 data product cube (PLAN §6.8, DP-1) saves its project once, as its
+// model: the project and the version its data products were deployed from,
+// the environment type and, once picked, the warehouse. The engine's
+// implementation builds, for each run, the project at that version and a
+// lakehouse runtime at a fixed path, which the saved runtime names
+
+/** The kind of a data product cube's model: Cube's own, never an engine model kind */
+export const CUBE_DATA_PRODUCT_MODEL_TYPE = 'cubeDataProduct';
+
+/** The runtime a data product cube runs with, in a package of Cube's own */
+export const CUBE_DATA_PRODUCT_RUNTIME_PATH = 'cube::dataProduct::Runtime';
+
+/** The warehouse a run uses when neither the cube nor the viewer has one (PLAN §6.8) */
+export const CUBE_DEFAULT_CONSUMER_WAREHOUSE = 'LAKEHOUSE_CONSUMER_DEFAULT_WH';
+
+/**
+ * The deployment classes Cube reads data products from: production and
+ * production-parallel, as Data Cube's selection offers. Development
+ * deployments are not supported in this phase (user, 2026-10-09)
+ */
+export enum CubeDataProductEnvironmentType {
+  PRODUCTION = 'PRODUCTION',
+  PRODUCTION_PARALLEL = 'PRODUCTION_PARALLEL',
+}
+
+/** The wire name of the development class, which Cube refuses by name */
+const DEVELOPMENT_ENVIRONMENT_TYPE = 'DEVELOPMENT';
+
+/** What a data product cube's model holds */
+export interface CubeDataProductProject {
+  readonly groupId: string;
+  readonly artifactId: string;
+  /** The version the data products were deployed from, as the catalog gave it */
+  readonly versionId: string;
+  readonly environmentType: CubeDataProductEnvironmentType;
+  /** 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;
+
+/** The model of a data product cube */
+export const createCubeDataProductModel = (
+  project: CubeDataProductProject,
+): ModelContext =>
+  ({
+    _type: CUBE_DATA_PRODUCT_MODEL_TYPE,
+    groupId: project.groupId,
+    artifactId: project.artifactId,
+    versionId: project.versionId,
+    environmentType: project.environmentType,
+    ...(project.warehouse !== undefined
+      ? { warehouse: project.warehouse }
+      : {}),
+  }) as ModelContext;
+
+export const isCubeDataProductModel = (model: ModelContext): boolean =>
+  model._type === CUBE_DATA_PRODUCT_MODEL_TYPE;
+
+/** Whether a version moves: a SNAPSHOT's data and columns may change under a cube */
+export const isCubeSnapshotVersion = (versionId: string): boolean =>
+  versionId.endsWith('-SNAPSHOT');
+
+/**
+ * The model with another warehouse; every other key is kept, including ones
+ * a later version saved, which a cube keeps as they are
+ */
+export const withCubeDataProductWarehouse = (
+  model: ModelContext,
+  warehouse: string,
+): ModelContext => ({ ...model, warehouse });
+
+/**
+ * Why Cube can't run a data product model, in words a user can act on; none
+ * when it can. A saved model is checked before every use: it may have been
+ * written by hand or by a later version
+ */
+export const checkCubeDataProductModel = (
+  model: ModelContext,
+): readonly string[] => {
+  const problems: string[] = [];
+  (['groupId', 'artifactId', 'versionId'] as const).forEach((key) => {
+    if (!isNonEmptyString(model[key])) {
+      problems.push(`The data product's project has no ${key}`);
+    }
+  });
+  if (model.environmentType === DEVELOPMENT_ENVIRONMENT_TYPE) {
+    problems.push(`Cube doesn't read development data products yet`);
+  } else if (!ENVIRONMENT_TYPES.includes(model.environmentType as string)) {
+    problems.push(
+      `Cube doesn't know the environment type "${String(model.environmentType)}"`,
+    );
+  }
+  if (model.warehouse !== undefined && !isNonEmptyString(model.warehouse)) {
+    problems.push(`The cube's warehouse must be a name`);
+  }
+  return problems;
+};
+
+/** The project of a data product model Cube can run; undefined for any other model */
+export const getCubeDataProductProject = (
+  model: ModelContext,
+): CubeDataProductProject | undefined =>
+  isCubeDataProductModel(model) && !checkCubeDataProductModel(model).length
+    ? {
+        groupId: model.groupId as string,
+        artifactId: model.artifactId as string,
+        versionId: model.versionId as string,
+        environmentType:
+          model.environmentType as CubeDataProductEnvironmentType,
+        warehouse: model.warehouse as string | undefined,
+      }
+    : undefined;
+
+/**
+ * The warehouse a run uses (PLAN §6.8, DP-2): the cube's own, else the one
+ * the viewer last picked, else the default consumer warehouse. Shown and sent
+ * alike, so the page shows what runs
+ */
+export const getEffectiveCubeWarehouse = (
+  project: Pick<CubeDataProductProject, 'warehouse'>,
+  rememberedWarehouse: string | undefined,
+): string =>
+  project.warehouse ??
+  (isNonEmptyString(rememberedWarehouse)
+    ? rememberedWarehouse
+    : CUBE_DEFAULT_CONSUMER_WAREHOUSE);

package/src/graph-manager/CubeDataProductCatalog.ts

@@ -0,0 +1,245 @@
+/**
+ * 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,
+  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>>;
+}

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
@@ -64,10 +64,24 @@ export interface CubeOutlineDatabase {
   readonly schemas: readonly CubeOutlineSchema[];
 }
 
+/** A relational connection of a runtime, for the operations some databases take another way (PLAN §11.4) */
+export interface CubeOutlineConnection {
+  /** The store it is keyed by */
+  readonly storePath: string;
+  /** The engine's name for its database type, e.g. `H2` or `SqlServer` */
+  readonly databaseType: string;
+}
+
 export interface CubeOutlineRuntime {
   readonly path: string;
   /** The stores its connections are keyed by, exactly; includes are not followed (PLAN §6.2.5) */
   readonly storePaths: readonly string[];
+  /**
+   * Its relational connections that name a database type, a list rather
+   * than a record keyed by a store path from the model; optional, as an
+   * outline from before M2 has none
+   */
+  readonly connections?: readonly CubeOutlineConnection[];
 }
 
 /** What a model offers the source picker: its databases and runtimes, as plain data */
@@ -87,6 +101,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.
@@ -100,12 +138,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);
@@ -115,6 +156,7 @@ export class CubeEngineError extends Error {
     this.firstLine = firstLine;
     this.nodeId = nodeId;
     this.role = role;
+    this.location = location;
   }
 }
 
@@ -152,4 +194,18 @@ export interface CubeEngine {
   ): Promise<CubeResult>;
   /** The Pure text of a lambda, for display only: never parsed back */
   renderPure(lambda: IR): Promise<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>;
 }