@finos/legend-graph 10.1.0 → 11.0.0

package/src/graphManager/AbstractPureGraphManager.ts

@@ -27,7 +27,7 @@ import type {
 import type { FileGenerationSpecification } from '../models/metamodels/pure/packageableElements/fileGeneration/FileGenerationSpecification.js';
 import type { GenerationOutput } from './action/generation/GenerationOutput.js';
 import type { PackageableElement } from '../models/metamodels/pure/packageableElements/PackageableElement.js';
-import type { PureModel, CoreModel, SystemModel } from '../graph/PureModel.js';
+import { PureModel, CoreModel, SystemModel } from '../graph/PureModel.js';
 import type { Mapping } from '../models/metamodels/pure/packageableElements/mapping/Mapping.js';
 import type { Runtime } from '../models/metamodels/pure/packageableElements/runtime/Runtime.js';
 import type { DependencyManager } from '../graph/DependencyManager.js';
@@ -48,11 +48,11 @@ import type {
   RawExecutionPlan,
 } from '../models/metamodels/pure/executionPlan/ExecutionPlan.js';
 import type { ExecutionNode } from '../models/metamodels/pure/executionPlan/nodes/ExecutionNode.js';
-import type {
+import {
   ActionState,
-  Log,
-  ServerClientConfig,
-  TracerService,
+  type Log,
+  type ServerClientConfig,
+  type TracerService,
 } from '@finos/legend-shared';
 import type { LightQuery, Query } from './action/query/Query.js';
 import type { Entity } from '@finos/legend-model-storage';
@@ -61,7 +61,6 @@ import type { ExternalFormatDescription } from './action/externalFormat/External
 import type { ConfigurationProperty } from '../models/metamodels/pure/packageableElements/fileGeneration/ConfigurationProperty.js';
 import type { GraphBuilderReport } from './GraphBuilderReport.js';
 import type { ModelGenerationConfiguration } from '../models/ModelGenerationConfiguration.js';
-import type { DEPRECATED__ServiceTestResult } from './action/service/DEPRECATED__ServiceTestResult.js';
 import type { RunTestsTestableInput } from '../models/metamodels/pure/test/result/RunTestsTestableInput.js';
 import type { TestResult } from '../models/metamodels/pure/test/result/TestResult.js';
 import type { GraphPluginManager } from '../GraphPluginManager.js';
@@ -72,7 +71,7 @@ import type { AssertFail } from '../models/metamodels/pure/test/assertion/status
 import type {
   MappingModelCoverageAnalysisResult,
   RawMappingModelCoverageAnalysisResult,
-} from './action/analytics/MappingAnalytics.js';
+} from './action/analytics/MappingModelCoverageAnalysis.js';
 
 export interface TEMPORARY__EngineSetupConfig {
   env: string;
@@ -130,6 +129,8 @@ export abstract class AbstractPureGraphManager {
       );
   }
 
+  abstract getSupportedProtocolVersion(): string;
+
   /**
    * TODO: we should not expose a fixed config like this, we probably
    * should not mention anything about engine because it is an internal construct
@@ -147,8 +148,6 @@ export abstract class AbstractPureGraphManager {
     },
   ): Promise<void>;
 
-  abstract getSupportedProtocolVersion(): string;
-
   // --------------------------------------------- Graph Builder ---------------------------------------------
 
   /**
@@ -164,16 +163,6 @@ export abstract class AbstractPureGraphManager {
     options?: GraphBuilderOptions,
   ): Promise<GraphBuilderReport>;
 
-  /**
-   * Process entities and build the main graph.
-   */
-  abstract buildGraph(
-    graph: PureModel,
-    entities: Entity[],
-    buildState: ActionState,
-    options?: GraphBuilderOptions,
-  ): Promise<GraphBuilderReport>;
-
   /**
    * Build immutable models which holds dependencies.
    * Dependency models MUST not depend on the main model.
@@ -186,7 +175,17 @@ export abstract class AbstractPureGraphManager {
     coreModel: CoreModel,
     systemModel: SystemModel,
     dependencyManager: DependencyManager,
-    dependencyEntitiesMap: Map<string, Entity[]>,
+    dependencyEntitiesIndex: Map<string, Entity[]>,
+    buildState: ActionState,
+    options?: GraphBuilderOptions,
+  ): Promise<GraphBuilderReport>;
+
+  /**
+   * Process entities and build the main graph.
+   */
+  abstract buildGraph(
+    graph: PureModel,
+    entities: Entity[],
     buildState: ActionState,
     options?: GraphBuilderOptions,
   ): Promise<GraphBuilderReport>;
@@ -211,6 +210,9 @@ export abstract class AbstractPureGraphManager {
   abstract pureCodeToLambda(
     lambda: string,
     lambdaId?: string,
+    options?: {
+      pruneSourceInformation?: boolean;
+    },
   ): Promise<RawLambda>;
   abstract lambdaToPureCode(
     lambda: RawLambda,
@@ -326,25 +328,25 @@ export abstract class AbstractPureGraphManager {
   // ------------------------------------------- Execute -------------------------------------------
 
   abstract executeMapping(
-    graph: PureModel,
-    mapping: Mapping,
     lambda: RawLambda,
+    mapping: Mapping,
     runtime: Runtime,
+    graph: PureModel,
     options?: ExecutionOptions,
   ): Promise<ExecutionResult>;
 
   abstract generateExecutionPlan(
-    graph: PureModel,
-    mapping: Mapping,
     lambda: RawLambda,
+    mapping: Mapping,
     runtime: Runtime,
+    graph: PureModel,
   ): Promise<RawExecutionPlan>;
 
   abstract debugExecutionPlanGeneration(
-    graph: PureModel,
-    mapping: Mapping,
     lambda: RawLambda,
+    mapping: Mapping,
     runtime: Runtime,
+    graph: PureModel,
   ): Promise<{ plan: RawExecutionPlan; debug: string }>;
 
   abstract buildExecutionPlan(
@@ -359,11 +361,11 @@ export abstract class AbstractPureGraphManager {
   abstract serializeExecutionNode(executionNode: ExecutionNode): object;
 
   abstract generateExecuteTestData(
-    graph: PureModel,
-    mapping: Mapping,
     lambda: RawLambda,
-    runtime: Runtime,
     parameters: (string | number | boolean)[],
+    mapping: Mapping,
+    runtime: Runtime,
+    graph: PureModel,
     options?: {
       // Anonymizes data by hashing any string values in the generated data
       anonymizeGeneratedData?: boolean;
@@ -377,27 +379,19 @@ export abstract class AbstractPureGraphManager {
    */
 
   abstract registerService(
-    graph: PureModel,
     service: Service,
+    graph: PureModel,
     groupId: string,
     artifactId: string,
+    version: string | undefined,
     server: string,
     executionMode: ServiceExecutionMode,
-    version: string | undefined,
   ): Promise<ServiceRegistrationResult>;
   abstract activateService(
     serviceUrl: string,
     serviceId: string,
   ): Promise<void>;
 
-  /**
-   * @deprecated
-   */
-  abstract runLegacyServiceTests(
-    service: Service,
-    graph: PureModel,
-  ): Promise<DEPRECATED__ServiceTestResult[]>;
-
   // ------------------------------------------- Database -------------------------------------------
   /**
    * @modularize
@@ -423,8 +417,8 @@ export abstract class AbstractPureGraphManager {
   // -------------------------------------- Analysis --------------------------------------
 
   abstract analyzeMappingModelCoverage(
-    graph: PureModel,
     mapping: Mapping,
+    graph: PureModel,
   ): Promise<MappingModelCoverageAnalysisResult>;
 
   abstract buildMappingModelCoverageAnalysisResult(
@@ -440,6 +434,26 @@ export abstract class AbstractPureGraphManager {
     },
   ): Entity;
 
+  async createEmptyGraph(options?: {
+    initializeSystem?: boolean;
+  }): Promise<PureModel> {
+    const extensionElementClasses = this.pluginManager
+      .getPureGraphPlugins()
+      .flatMap((plugin) => plugin.getExtraPureGraphExtensionClasses?.() ?? []);
+    const coreModel = new CoreModel(extensionElementClasses);
+    const systemModel = new SystemModel(extensionElementClasses);
+    if (options?.initializeSystem) {
+      await this.buildSystem(coreModel, systemModel, ActionState.create());
+      systemModel.initializeAutoImports();
+    }
+    const graph = new PureModel(
+      coreModel,
+      systemModel,
+      this.pluginManager.getPureGraphPlugins(),
+    );
+    return graph;
+  }
+
   // ------------------------------------------- Change detection -------------------------------------------
 
   abstract buildHashesIndex(entities: Entity[]): Promise<Map<string, string>>;

package/src/graphManager/GraphManagerEvent.ts

@@ -27,6 +27,7 @@ export enum GRAPH_MANAGER_EVENT {
   GRAPH_BUILDER_OTHER_ELEMENTS_BUILT = 'graph-manager.graph-builder.build-other-elements.success',
   GRAPH_BUILDER_COMPLETED = 'graph-manager.graph-builder.success',
 
+  GRAPH_SYSTEM_INITIALIZED = 'graph-manager.system-initialization.success',
   GRAPH_INITIALIZED = 'graph-manager.graph-initialization.success',
   GRAPH_DEPENDENCIES_FETCHED = 'graph-manager.fetch-dependencies.success',
   GRAPH_ENTITIES_FETCHED = 'graph-manager.entities-dependencies.success',

package/src/graphManager/action/analytics/{MappingAnalytics.ts → MappingModelCoverageAnalysis.ts}

@@ -17,7 +17,7 @@
 export type RawMappingModelCoverageAnalysisResult = object;
 
 export class MappedEntity {
-  readonly __NAME_TO_PROPERTY!: Map<string, MappedProperty>;
+  readonly __PROPERTIES_INDEX = new Map<string, MappedProperty>();
 
   path: string;
   properties: MappedProperty[];
@@ -25,8 +25,9 @@ export class MappedEntity {
   constructor(path: string, properties: MappedProperty[]) {
     this.path = path;
     this.properties = properties;
-    this.__NAME_TO_PROPERTY = new Map<string, MappedProperty>();
-    properties.map((p) => this.__NAME_TO_PROPERTY.set(p.name, p));
+    properties.forEach((property) =>
+      this.__PROPERTIES_INDEX.set(property.name, property),
+    );
   }
 }
 
@@ -59,13 +60,14 @@ export class EnumMappedProperty extends MappedProperty {
 }
 
 export class MappingModelCoverageAnalysisResult {
-  readonly __PATH_TO_ENTITY!: Map<string, MappedEntity>;
+  readonly __ENTITIES_INDEX = new Map<string, MappedEntity>();
 
   mappedEntities: MappedEntity[];
 
   constructor(mappedEntities: MappedEntity[]) {
     this.mappedEntities = mappedEntities;
-    this.__PATH_TO_ENTITY = new Map<string, MappedEntity>();
-    mappedEntities.map((e) => this.__PATH_TO_ENTITY.set(e.path, e));
+    mappedEntities.forEach((entity) =>
+      this.__ENTITIES_INDEX.set(entity.path, entity),
+    );
   }
 }

package/src/graphManager/action/changeDetection/CoreObserverHelper.ts

@@ -22,10 +22,7 @@ import {
   observable,
 } from 'mobx';
 import type { PackageableElement } from '../../../models/metamodels/pure/packageableElements/PackageableElement.js';
-import type {
-  OptionalPackageableElementReference,
-  PackageableElementReference,
-} from '../../../models/metamodels/pure/packageableElements/PackageableElementReference.js';
+import type { PackageableElementReference } from '../../../models/metamodels/pure/packageableElements/PackageableElementReference.js';
 import type { Multiplicity } from '../../../models/metamodels/pure/packageableElements/domain/Multiplicity.js';
 import type { InferableValue } from '../../../models/metamodels/pure/InferableValue.js';
 import type { PureGraphManagerPlugin } from '../../PureGraphManagerPlugin.js';
@@ -80,16 +77,6 @@ export const observe_PackageableElementReference = skipObserved(
     }),
 );
 
-export const observe_OptionalPackageableElementReference = skipObserved(
-  <T extends PackageableElement>(
-    metamodel: OptionalPackageableElementReference<T>,
-  ): OptionalPackageableElementReference<T> =>
-    makeObservable(metamodel, {
-      value: observable,
-      valueForSerialization: computed,
-    }),
-);
-
 export const observe_Multiplicity = skipObserved(
   (metamodel: Multiplicity): Multiplicity =>
     makeObservable(metamodel, {

package/src/graphManager/action/changeDetection/DSLExternalFormat_ObserverHelper.ts

@@ -25,7 +25,6 @@ import type { ModelUnit } from '../../../models/metamodels/pure/packageableEleme
 import {
   observe_PackageableElementReference,
   skipObserved,
-  observe_OptionalPackageableElementReference,
   observe_Abstract_PackageableElement,
 } from './CoreObserverHelper.js';
 import {
@@ -65,7 +64,9 @@ export const observe_Binding = skipObserved((metamodel: Binding): Binding => {
     _elementHashCode: override,
   });
 
-  observe_OptionalPackageableElementReference(metamodel.schemaSet);
+  if (metamodel.schemaSet) {
+    observe_PackageableElementReference(metamodel.schemaSet);
+  }
   observe_ModelUnit(metamodel.modelUnit);
 
   return metamodel;

package/src/graphManager/action/changeDetection/DSLMapping_ObserverHelper.ts

@@ -25,7 +25,7 @@ import type { AggregationAwarePropertyMapping } from '../../../models/metamodels
 import type { AggregationAwareSetImplementation } from '../../../models/metamodels/pure/packageableElements/mapping/aggregationAware/AggregationAwareSetImplementation.js';
 import type { AssociationImplementation } from '../../../models/metamodels/pure/packageableElements/mapping/AssociationImplementation.js';
 import type { EnumerationMapping } from '../../../models/metamodels/pure/packageableElements/mapping/EnumerationMapping.js';
-import type { OptionalEnumerationMappingReference } from '../../../models/metamodels/pure/packageableElements/mapping/EnumerationMappingReference.js';
+import type { EnumerationMappingReference } from '../../../models/metamodels/pure/packageableElements/mapping/EnumerationMappingReference.js';
 import type {
   EnumValueMapping,
   SourceValue,
@@ -92,7 +92,6 @@ import {
   skipObserved,
   skipObservedWithContext,
   observe_Multiplicity,
-  observe_OptionalPackageableElementReference,
 } from './CoreObserverHelper.js';
 import {
   observe_EnumValueReference,
@@ -131,16 +130,14 @@ export const observe_Abstract_Store = (metamodel: Store): void => {
 
 // ------------------------------------- Mapping -------------------------------------
 
-export const observe_OptionalEnumerationMappingReference = skipObserved(
-  (
-    metamodel: OptionalEnumerationMappingReference,
-  ): OptionalEnumerationMappingReference => {
+export const observe_EnumerationMappingReference = skipObserved(
+  (metamodel: EnumerationMappingReference): EnumerationMappingReference => {
     makeObservable(metamodel, {
       value: observable,
       valueForSerialization: computed,
     });
 
-    observe_OptionalPackageableElementReference(metamodel.ownerReference);
+    observe_PackageableElementReference(metamodel.ownerReference);
 
     return metamodel;
   },
@@ -184,8 +181,10 @@ export const observe_Abstract_PropertyMapping = (
   });
 
   observe_PropertyReference(metamodel.property);
-  // TODO: source
-  // TODO: target
+  observe_SetImplementationReference(metamodel.sourceSetImplementation);
+  if (metamodel.targetSetImplementation) {
+    observe_SetImplementationReference(metamodel.targetSetImplementation);
+  }
   if (metamodel.localMappingProperty) {
     observe_LocalMappingPropertyInfo(metamodel.localMappingProperty);
   }
@@ -202,7 +201,9 @@ export const observe_PurePropertyMapping = skipObservedWithContext(
       hashCode: computed,
     });
 
-    observe_OptionalEnumerationMappingReference(metamodel.transformer);
+    if (metamodel.transformer) {
+      observe_EnumerationMappingReference(metamodel.transformer);
+    }
     observe_RawLambda(metamodel.transform);
 
     return metamodel;
@@ -425,7 +426,9 @@ export const observe_PureInstanceSetImplementation = skipObservedWithContext(
       hashCode: computed,
     });
 
-    observe_OptionalPackageableElementReference(metamodel.srcClass);
+    if (metamodel.srcClass) {
+      observe_PackageableElementReference(metamodel.srcClass);
+    }
     if (metamodel.filter) {
       observe_RawLambda(metamodel.filter);
     }
@@ -595,7 +598,9 @@ export const observe_EnumerationMapping = skipObserved(
 
     observe_PackageableElementReference(metamodel.enumeration);
     observe_InferableMappingElementIdValue(metamodel.id);
-    observe_OptionalPackageableElementReference(metamodel.sourceType);
+    if (metamodel.sourceType) {
+      observe_PackageableElementReference(metamodel.sourceType);
+    }
     metamodel.enumValueMappings.forEach(observe_EnumValueMapping);
 
     return metamodel;

package/src/graphManager/action/changeDetection/GraphObserverHelper.ts

@@ -36,7 +36,7 @@ const observe_PureGraphExtension = skipObserved(
 const observe_Abstract_BasicModel = (metamodel: BasicModel): void => {
   makeObservable<
     BasicModel,
-    | 'elementSectionMap'
+    | 'elementSectionIndex'
     | 'sectionIndicesIndex'
     | 'profilesIndex'
     | 'typesIndex'
@@ -51,7 +51,7 @@ const observe_Abstract_BasicModel = (metamodel: BasicModel): void => {
     | 'fileGenerationsIndex'
     | 'dataElementsIndex'
   >(metamodel, {
-    elementSectionMap: observable,
+    elementSectionIndex: observable,
     extensions: observable,
 
     sectionIndicesIndex: observable,

package/src/graphManager/action/changeDetection/ValueSpecificationObserver.ts

@@ -60,7 +60,6 @@ import {
   type ObserverContext,
   skipObservedWithContext,
   skipObserved,
-  observe_OptionalPackageableElementReference,
   observe_Multiplicity,
   observe_PackageableElementReference,
 } from './CoreObserverHelper.js';
@@ -511,7 +510,9 @@ function _observe_PropertyGraphFetchTree(
   metamodel.parameters.forEach((value) =>
     observe_ValueSpecification(value, context),
   );
-  observe_OptionalPackageableElementReference(metamodel.subType);
+  if (metamodel.subType) {
+    observe_PackageableElementReference(metamodel.subType);
+  }
 
   return metamodel;
 }

package/src/graphManager/action/validation/DSLService_ValidationHelper.ts

@@ -15,11 +15,8 @@
  */
 
 import { addUniqueEntry } from '@finos/legend-shared';
-import type {
-  KeyedExecutionParameter,
-  PureExecution,
-  PureSingleExecution,
-} from '../../../models/metamodels/pure/packageableElements/service/ServiceExecution.js';
+import type { Mapping } from '../../../models/metamodels/pure/packageableElements/mapping/Mapping.js';
+import type { PureExecution } from '../../../models/metamodels/pure/packageableElements/service/ServiceExecution.js';
 import { isStubbed_PackageableElement } from '../creation/DomainModelCreatorHelper.js';
 import { isStubbed_RawLambda } from '../creation/RawValueSpecificationCreatorHelper.js';
 import {
@@ -56,8 +53,8 @@ export const validate_PureExecutionQuery = (
 };
 
 export const validate_PureExecutionMapping = (
-  metamodel: PureSingleExecution | KeyedExecutionParameter,
+  mapping: Mapping,
 ): ValidationIssue | undefined =>
-  isStubbed_PackageableElement(metamodel.mapping.value)
+  isStubbed_PackageableElement(mapping)
     ? createValidationError(['Service execution mapping cannot be empty'])
     : undefined;

package/src/helpers/DSLMapping_Helper.ts

@@ -215,7 +215,7 @@ export const findPropertyMapping = (
   return properties.find(
     (propertyMapping) =>
       propertyMapping.targetSetImplementation &&
-      propertyMapping.targetSetImplementation.id.value === targetId,
+      propertyMapping.targetSetImplementation.value.id.value === targetId,
   );
 };
 

package/src/helpers/DomainHelper.ts

@@ -23,6 +23,7 @@ import {
   MILESTONING_STEREOTYPE,
   PRIMITIVE_TYPE,
   MULTIPLICITY_INFINITE,
+  PURE_DEPRECATED_STEREOTYPE,
 } from '../MetaModelConst.js';
 import { Package } from '../models/metamodels/pure/packageableElements/domain/Package.js';
 import type { PackageableElement } from '../models/metamodels/pure/packageableElements/PackageableElement.js';
@@ -59,6 +60,7 @@ import type { Enum } from '../models/metamodels/pure/packageableElements/domain/
 import type { Constraint } from '../models/metamodels/pure/packageableElements/domain/Constraint.js';
 import type { GenericType } from '../models/metamodels/pure/packageableElements/domain/GenericType.js';
 import type { Multiplicity } from '../models/metamodels/pure/packageableElements/domain/Multiplicity.js';
+import type { AnnotatedElement } from '../models/metamodels/pure/packageableElements/domain/AnnotatedElement.js';
 
 export const addElementToPackage = (
   parent: Package,
@@ -518,3 +520,15 @@ export const getMultiplicityDescription = (
       : `Must have at least ${multiplicity.lowerBound} values(s)`
   }`;
 };
+
+export const isElementDeprecated = (
+  element: AnnotatedElement | Class,
+  graph: PureModel,
+): boolean =>
+  element.stereotypes.some(
+    (st) =>
+      st.value ===
+      graph
+        .getProfile(CORE_PURE_PATH.PROFILE_DOC)
+        .p_stereotypes.find((s) => s.value === PURE_DEPRECATED_STEREOTYPE),
+  );

package/src/index.ts

@@ -18,9 +18,9 @@
 
 // metamodels
 export * from './models/metamodels/pure/Reference.js';
-export * from './models/metamodels/pure/packageableElements/connection/Connection.js';
 export * from './models/metamodels/pure/packageableElements/PackageableElement.js';
 export * from './models/metamodels/pure/packageableElements/PackageableElementReference.js';
+export * from './models/metamodels/pure/packageableElements/mapping/SetImplementationReference.js';
 export { SectionIndex } from './models/metamodels/pure/packageableElements/section/SectionIndex.js';
 
 export { Multiplicity } from './models/metamodels/pure/packageableElements/domain/Multiplicity.js';
@@ -71,6 +71,8 @@ export {
   RuntimePointer,
   StoreConnections,
 } from './models/metamodels/pure/packageableElements/runtime/Runtime.js';
+// relational packageable elements
+export { Database } from './models/metamodels/pure/packageableElements/store/relational/model/Database.js';
 // metamodel external formats
 export { Binding } from './models/metamodels/pure/packageableElements/externalFormat/store/DSLExternalFormat_Binding.js';
 export { ModelUnit } from './models/metamodels/pure/packageableElements/externalFormat/store/DSLExternalFormat_ModelUnit.js';
@@ -184,7 +186,10 @@ export * from './graph/PureGraphPlugin.js';
 
 export { type GraphPluginManager } from './GraphPluginManager.js';
 export { CorePureGraphManagerPlugin } from './graphManager/CorePureGraphManagerPlugin.js';
-export { GraphManagerState } from './GraphManagerState.js';
+export {
+  BasicGraphManagerState,
+  GraphManagerState,
+} from './GraphManagerState.js';
 export * from './GraphManagerStateProvider.js';
 export * from './GraphManagerTestUtils.js';
 export {
@@ -219,14 +224,6 @@ export { ServiceExecutionMode } from './graphManager/action/service/ServiceExecu
 export { ServiceRegistrationResult } from './graphManager/action/service/ServiceRegistrationResult.js';
 export { DEPRECATED__ServiceTestResult } from './graphManager/action/service/DEPRECATED__ServiceTestResult.js';
 export { SourceInformation } from './graphManager/action/SourceInformation.js';
-export {
-  MappingModelCoverageAnalysisResult,
-  MappedEntity,
-  MappedProperty,
-  EntityMappedProperty,
-  EnumMappedProperty,
-} from './graphManager/action/analytics/MappingAnalytics.js';
-export { V1_MappingModelCoverageAnalysisResult } from './models/protocols/pure/v1/engine/analytics/V1_MappingAnalytics.js';
 export * from './models/protocols/pure/PureProtocolProcessorPlugin.js';
 
 // --------------------------------------------- TRANSFORMATION --------------------------------------------------
@@ -245,28 +242,22 @@ export * from './models/protocols/pure/v1/transformation/pureGraph/to/helpers/V1
 export * from './models/protocols/pure/v1/transformation/pureGraph/to/V1_ElementBuilder.js';
 export { V1_RawLambda } from './models/protocols/pure/v1/model/rawValueSpecification/V1_RawLambda.js';
 export { V1_ProcessingContext } from './models/protocols/pure/v1/transformation/pureGraph/to/helpers/V1_ProcessingContext.js';
-export { V1_ProtocolToMetaModelConnectionBuilder } from './models/protocols/pure/v1/transformation/pureGraph/to/V1_ProtocolToMetaModelConnectionBuilder.js';
 export * from './models/protocols/pure/v1/transformation/pureGraph/from/V1_GraphTransformerContext.js';
 export * from './models/protocols/pure/v1/transformation/pureGraph/from/V1_CoreTransformerHelper.js';
 export {
   V1_RawValueSpecificationTransformer,
   V1_transformRawLambda,
 } from './models/protocols/pure/v1/transformation/pureGraph/from/V1_RawValueSpecificationTransformer.js';
-export {
-  V1_deserializeConnectionValue,
-  V1_serializeConnectionValue,
-} from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_ConnectionSerializationHelper.js';
-export { V1_runtimePointerModelSchema } from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_RuntimeSerializationHelper.js';
 export {
   V1_rawLambdaModelSchema,
   V1_deserializeRawValueSpecification,
   V1_serializeRawValueSpecification,
 } from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_RawValueSpecificationSerializationHelper.js';
 export { V1_transformPropertyReference } from './models/protocols/pure/v1/transformation/pureGraph/from/V1_MappingTransformer.js';
-export { V1_buildEngineRuntime } from './models/protocols/pure/v1/transformation/pureGraph/to/helpers/V1_RuntimeBuilderHelper.js';
 export { V1_EngineServerClient } from './models/protocols/pure/v1/engine/V1_EngineServerClient.js';
 export { V1_Engine } from './models/protocols/pure/v1/engine/V1_Engine.js';
 export {
+  V1_PureModelContextType,
   V1_entitiesToPureModelContextData,
   V1_deserializePureModelContextData,
 } from './models/protocols/pure/v1/transformation/pureProtocol/V1_PureProtocolSerialization.js';
@@ -275,8 +266,13 @@ export {
   V1_stereotypePtrSchema,
   V1_taggedValueSchema,
 } from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_DomainSerializationHelper.js';
-export { V1_serializeValueSpecification } from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_ValueSpecificationSerializer.js';
 export {
+  V1_deserializeValueSpecification,
+  V1_serializeValueSpecification,
+} from './models/protocols/pure/v1/transformation/pureProtocol/serializationHelpers/V1_ValueSpecificationSerializer.js';
+export { V1_transformRootValueSpecification } from './models/protocols/pure/v1/transformation/pureGraph/from/V1_ValueSpecificationTransformer.js';
+export {
+  V1_buildValueSpecification,
   V1_ValueSpecificationBuilder,
   V1_buildGenericFunctionExpression,
   V1_buildBaseSimpleFunctionExpression,

package/src/models/metamodels/pure/Reference.ts

@@ -31,8 +31,8 @@
  * (let's say the user put in an import statement and expect the pointer to just have name of class instead of its full-path,
  * we would like to keep the pointer as is during serialization if the class has not been changed).
  *
- * As such, this class `Reference` is kept to be as generic as possible, because we can extend it to have many various
- * information. But only one thing we know for sure that is a refernece must have a `value`, which is the actual
+ * As such, this class `Reference` is kept to be as generic as possible, because we can extend it hold more
+ * information. But regardless, only one thing we know for sure that is a reference must have a `value`, which is the actual
  * object-reference
  *
  * Given such meaning for reference, below are some guideline on how we modify the reference while modifying the metamodel:
@@ -40,44 +40,35 @@
  *    NEVER change the reference instance: only change the value of the reference so other information (inference context)
  *    are kept, so we can do proper serialization
  * 2. For property which is optional and single (multiplicity: [0..1]):
- *    NEVER change the reference instance. Turn this into a required single property of `OptionalReference`
- *    so the value can be `undefined`. This way we can keep the inference context.
+ *    NEVER change the reference instance, unless the reference is removed (i.e. set to `undefined`).
+ *    If the reference is unset, and later on re-established, we will create a fresh new reference, even if it has the
+ *    same as the original's. This is intended so the behavior is consistent with case (3) below.
+ *    NOTE: We have considered another alternative to always keep the reference, just like case (1) using the
+ *    construct `OptionalReference`; this way we can keep the inference context. However, there are a few downsides to this:
+ *      i. it is complicated, it makes the code for reference complex for a small gain
+ *      ii. it makes our treatment of reference diverging from Pure and would make it hard to code-generate the metamodels
+ *      iii. it makes case (2) and case (3) treatment seem inconsistent.
  * 3. For property which can be multiple (multiplicity: [*] or similar):
- *    ALWAYS change the reference instance, for DELETE or ADD, this is obvious, but for MODIFY, we can follow case 1,
+ *    ALWAYS change the reference instance, for DELETE or ADD, this is obvious, but for MODIFY, we can follow case (1),
  *    but for simplicity sake, we will just swap out to use new a new reference
  */
 export abstract class Reference {
-  abstract value?: unknown | undefined;
-}
-
-export abstract class OptionalReference extends Reference {}
-
-export abstract class RequiredReference extends Reference {
-  abstract override value: unknown;
+  abstract value: unknown;
 }
 
 /**
- * This is intended for information derived from a reference, such as property pointer, enum-value pointer, etc.
- * since those references we resolve after we resolve the reference to the class or enumeration they belong to.
+ * This can be used for references to sub-elements, such as property pointer, enum-value pointer, etc.
+ * since those references are often resolved after we resolve the reference to the class or enumeration they belong to.
  * In other words, these reference has an owner reference.
  *
  * The rule for modifying these references is similar to that of `Reference` with one addition. That is
  * if we modify the child, we should ALWAYS modify the owner reference accordingly (except when we have a list, we will
  * trash the reference)
  */
-export abstract class ReferenceWithOwner extends RequiredReference {
-  readonly ownerReference: RequiredReference;
-
-  protected constructor(ownerReference: RequiredReference) {
-    super();
-    this.ownerReference = ownerReference;
-  }
-}
-
-export abstract class OptionalReferenceWithOwner extends OptionalReference {
-  readonly ownerReference: OptionalReference;
+export abstract class ReferenceWithOwner extends Reference {
+  readonly ownerReference: Reference;
 
-  protected constructor(ownerReference: OptionalReference) {
+  protected constructor(ownerReference: Reference) {
     super();
     this.ownerReference = ownerReference;
   }