@itwin/imodel-transformer 1.0.0-dev.8 → 1.0.0

package/lib/cjs/IModelTransformer.js

@@ -19,8 +19,6 @@ const core_common_1 = require("@itwin/core-common");
 const IModelExporter_1 = require("./IModelExporter");
 const IModelImporter_1 = require("./IModelImporter");
 const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
-const PendingReferenceMap_1 = require("./PendingReferenceMap");
-const EntityMap_1 = require("./EntityMap");
 const IModelCloneContext_1 = require("./IModelCloneContext");
 const EntityUnifier_1 = require("./EntityUnifier");
 const Algo_1 = require("./Algo");
@@ -31,30 +29,6 @@ const nullLastProvenanceEntityInfo = {
     aspectVersion: "",
     aspectKind: core_backend_1.ExternalSourceAspect.Kind.Element,
 };
-/**
- * A container for tracking the state of a partially committed entity and finalizing it when it's ready to be fully committed
- * @internal
- */
-class PartiallyCommittedEntity {
-    constructor(
-    /**
-     * A set of "model|element ++ ID64" pairs, (e.g. `model0x11` or `element0x12`)
-     * It is possible for the submodel of an element to be separately resolved from the actual element,
-     * so its resolution must be tracked separately
-     */
-    _missingReferences, _onComplete) {
-        this._missingReferences = _missingReferences;
-        this._onComplete = _onComplete;
-    }
-    resolveReference(id) {
-        this._missingReferences.delete(id);
-        if (this._missingReferences.size === 0)
-            this._onComplete();
-    }
-    forceComplete() {
-        this._onComplete();
-    }
-}
 /**
  * Apply a function to each Id64 in a supported container type of Id64s.
  * Currently only supports raw Id64String or RelatedElement-like objects containing an `id` property that is a Id64String,
@@ -172,7 +146,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._isProvenanceInitTransform) {
             return "forward";
         }
-        if (!this._isSynchronization) {
+        if (!this._options.argsForProcessChanges) {
             return "not-sync";
         }
         try {
@@ -217,14 +191,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      */
     constructor(source, target, options) {
         super();
-        /** map of (unprocessed element, referencing processed element) pairs to the partially committed element that needs the reference resolved
-         * and have some helper methods below for now */
-        this._pendingReferences = new PendingReferenceMap_1.PendingReferenceMap();
         /** a set of elements for which source provenance will be explicitly tracked by ExternalSourceAspects */
         this._elementsWithExplicitlyTrackedProvenance = new Set();
-        /** map of partially committed entities to their partial commit progress */
-        this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
-        this._isSynchronization = false;
+        this._partiallyCommittedElementIds = new Set();
+        this._partiallyCommittedAspectIds = new Set();
         /**
          * A private variable meant to be set by tests which have an outdated way of setting up transforms. In all synchronizations today we expect to find an ESA in the branch db which describes the master -> branch relationship.
          * The exception to this is the first transform aka the provenance initializing transform which requires that the master imodel and the branch imodel are identical at the time of provenance initialization.
@@ -233,10 +203,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
          */
         this._allowNoScopingESA = false;
         this._changesetRanges = undefined;
-        /** Set of entity keys which were not exported and don't need to be tracked for pending reference resolution.
-         * @note Currently only tracks elements which were not exported.
-         */
-        this._skippedEntities = new Set();
         /**
          * Previously the transformer would insert provenance always pointing to the "target" relationship.
          * It should (and now by default does) instead insert provenance pointing to the provenanceSource
@@ -276,7 +242,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             // eslint-disable-next-line deprecation/deprecation
             danglingReferencesBehavior: options?.danglingReferencesBehavior ?? "reject",
             branchRelationshipDataBehavior: options?.branchRelationshipDataBehavior ?? "reject",
+            skipPropagateChangesToRootElements: options?.skipPropagateChangesToRootElements ?? true,
         };
+        // check if authorization client is defined
+        if (core_backend_1.IModelHost.authorizationClient === undefined) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "Authorization client is not set in IModelHost. If the transformer needs an accessToken, then it will fail.");
+        }
         this._isProvenanceInitTransform = this._options
             .wasSourceIModelCopiedToTarget
             ? true
@@ -360,9 +331,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         core_bentley_1.Logger.logInfo(loggerCategory, `this._includeSourceProvenance=${this._options.includeSourceProvenance}`);
         core_bentley_1.Logger.logInfo(loggerCategory, `this._cloneUsingBinaryGeometry=${this._options.cloneUsingBinaryGeometry}`);
         core_bentley_1.Logger.logInfo(loggerCategory, `this._wasSourceIModelCopiedToTarget=${this._options.wasSourceIModelCopiedToTarget}`);
-        core_bentley_1.Logger.logInfo(loggerCategory, 
-        // eslint-disable-next-line deprecation/deprecation
-        `this._isReverseSynchronization=${this._options.isReverseSynchronization}`);
         core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.autoExtendProjectExtents=${JSON.stringify(this.importer.options.autoExtendProjectExtents)}`);
         core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.simplifyElementGeometry=${this.importer.options.simplifyElementGeometry}`);
     }
@@ -456,25 +424,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             forceOldRelationshipProvenanceMethod: this._forceOldRelationshipProvenanceMethod,
         });
     }
-    /** the changeset in the scoping element's source version found for this transformation
-     * @note: the version depends on whether this is a reverse synchronization or not, as
-     * it is stored separately for both synchronization directions.
-     * @note: must call [[initScopeProvenance]] before using this property.
-     * @note: empty string and -1 for changeset and index if it has never been transformed or was transformed before federation guid update (pre 1.x).
-     */
-    get _synchronizationVersion() {
-        if (!this._cachedSynchronizationVersion) {
-            nodeAssert(this._targetScopeProvenanceProps, "_targetScopeProvenanceProps was not set yet");
-            const version = this.isReverseSynchronization
-                ? this._targetScopeProvenanceProps.jsonProperties?.reverseSyncVersion
-                : this._targetScopeProvenanceProps.version;
-            nodeAssert(version !== undefined, "no version contained in target scope");
-            const [id, index] = version === "" ? ["", -1] : version.split(";");
-            this._cachedSynchronizationVersion = { index: Number(index), id };
-            nodeAssert(!Number.isNaN(this._cachedSynchronizationVersion.index), "bad parse: invalid index in version");
-        }
-        return this._cachedSynchronizationVersion;
-    }
     /**
      * As of itwinjs 4.6.0, definitionContainers are now deleted as if they were DefinitionPartitions as opposed to Definitions.
      * This variable being true will be used to special case the deletion of DefinitionContainers the same way DefinitionPartitions are deleted.
@@ -485,10 +434,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         return this._hasDefinitionContainerDeletionFeature;
     }
+    /**
+     * We cache the synchronization version to avoid querying the target scoping ESA multiple times.
+     * If the target scoping ESA is ever updated we need to clear any potentially cached sync version otherwise we will get stale values.
+     * Sets this._cachedSynchronizationVersion to undefined.
+     */
+    clearCachedSynchronizationVersion() {
+        this._cachedSynchronizationVersion = undefined;
+    }
     /** the changeset in the scoping element's source version found for this transformation
-     * @note: the version depends on whether this is a reverse synchronization or not, as
+     * @note the version depends on whether this is a reverse synchronization or not, as
      * it is stored separately for both synchronization directions.
-     * @note: empty string and -1 for changeset and index if it has never been transformed, or was transformed before federation guid update (pre 1.x).
+     * @note empty string and -1 for changeset and index if it has never been transformed
+     * @note empty string and -1 for changeset and index if it was transformed before federation guid update (pre 1.x) and @see [[IModelTransformOptions.branchRelationshipDataBehavior]] === "unsafe-migrate".
+     * @throws if the version is not found in a preexisting scope aspect and @see [[IModelTransformOptions.branchRelationshipDataBehavior]] !== "unsafe-migrate"
      */
     get synchronizationVersion() {
         if (this._cachedSynchronizationVersion === undefined) {
@@ -499,10 +458,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             const version = this.isReverseSynchronization
                 ? JSON.parse(provenanceScopeAspect.jsonProperties ?? "{}").reverseSyncVersion
                 : provenanceScopeAspect.version;
-            if (!version) {
+            if (!version &&
+                this._options.branchRelationshipDataBehavior === "unsafe-migrate") {
                 return { index: -1, id: "" }; // previous synchronization was done before fed guid update.
             }
-            const [id, index] = version.split(";");
+            if (version === undefined) {
+                throw new Error(`Could not find synchronization version in scope aspect. This may be due to the last successful run of the transformer being done with an older version.
+         Consider running the transformer with branchRelationshipDataBehavior set to 'unsafe-migrate'`);
+            }
+            const [id, index] = version === "" ? ["", -1] : version.split(";");
             if (Number.isNaN(Number(index)))
                 throw new Error("Could not parse version data from scope aspect");
             this._cachedSynchronizationVersion = { index: Number(index), id }; // synchronization version found and cached.
@@ -578,6 +542,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     jsonProperties: JSON.stringify(aspectProps.jsonProperties),
                 });
                 aspectProps.id = id;
+                // Busting a potential cached version
+                this.clearCachedSynchronizationVersion();
             }
         }
         else {
@@ -587,29 +553,50 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             aspectProps.jsonProperties = foundEsaProps.jsonProperties
                 ? JSON.parse(foundEsaProps.jsonProperties)
                 : undefined;
-            this.handleUnsafeMigrate(aspectProps);
+            // Clone oldProps incase they're changed for logging purposes
+            const oldProps = JSON.parse(JSON.stringify(aspectProps));
+            if (this.handleUnsafeMigrate(aspectProps)) {
+                core_bentley_1.Logger.logInfo(loggerCategory, "Unsafe migrate made a change to the target scope's external source aspect. Updating aspect in database.", { oldProps, newProps: aspectProps });
+                this.provenanceDb.elements.updateAspect({
+                    ...aspectProps,
+                    jsonProperties: JSON.stringify(aspectProps.jsonProperties),
+                });
+                // Busting a potential cached version
+                this.clearCachedSynchronizationVersion();
+            }
         }
         this._targetScopeProvenanceProps =
             aspectProps;
     }
+    /** Returns true if a change was made to the aspectProps. */
     handleUnsafeMigrate(aspectProps) {
+        let madeChange = false;
         if (this._options.branchRelationshipDataBehavior !== "unsafe-migrate")
-            return;
-        const fallbackSyncVersionToUse = this._options.unsafeFallbackSyncVersion ?? "";
-        const fallbackReverseSyncVersionToUse = this._options.unsafeFallbackReverseSyncVersion ?? "";
-        if (aspectProps.version === undefined || aspectProps.version === "")
+            return madeChange;
+        const fallbackSyncVersionToUse = this._options.argsForProcessChanges?.unsafeFallbackSyncVersion ?? "";
+        const fallbackReverseSyncVersionToUse = this._options.argsForProcessChanges?.unsafeFallbackReverseSyncVersion ??
+            "";
+        if (aspectProps.version === undefined ||
+            (aspectProps.version === "" &&
+                aspectProps.version !== fallbackSyncVersionToUse)) {
             aspectProps.version = fallbackSyncVersionToUse;
+            madeChange = true;
+        }
         if (aspectProps.jsonProperties === undefined) {
             aspectProps.jsonProperties = {
                 pendingReverseSyncChangesetIndices: [],
                 pendingSyncChangesetIndices: [],
                 reverseSyncVersion: fallbackReverseSyncVersionToUse,
             };
+            madeChange = true;
         }
         else if (aspectProps.jsonProperties.reverseSyncVersion === undefined ||
-            aspectProps.jsonProperties.reverseSyncVersion === "") {
+            (aspectProps.jsonProperties.reverseSyncVersion === "" &&
+                aspectProps.jsonProperties.reverseSyncVersion !==
+                    fallbackReverseSyncVersionToUse)) {
             aspectProps.jsonProperties.reverseSyncVersion =
                 fallbackReverseSyncVersionToUse;
+            madeChange = true;
         }
         /**
          * This case will only be hit when:
@@ -622,11 +609,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             undefined) {
             core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingReverseSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
             aspectProps.jsonProperties.pendingReverseSyncChangesetIndices = [];
+            madeChange = true;
         }
         if (aspectProps.jsonProperties.pendingSyncChangesetIndices === undefined) {
             core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
             aspectProps.jsonProperties.pendingSyncChangesetIndices = [];
+            madeChange = true;
         }
+        return madeChange;
     }
     /**
      * Iterate all matching federation guids and ExternalSourceAspects in the provenance iModel (target unless reverse sync)
@@ -723,7 +713,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             targetScopeElementId: this.targetScopeElementId,
             isReverseSynchronization: this.isReverseSynchronization,
             fn,
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? true,
         });
     }
     /**
@@ -845,7 +835,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Returns `true` if *brute force* delete detections should be run.
      * @note This is only called if [[IModelTransformOptions.forceExternalSourceAspectProvenance]] option is true
-     * @note Not relevant for processChanges when change history is known.
+     * @note Not relevant for [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are provided and change history is known.
      */
     shouldDetectDeletes() {
         nodeAssert(this._syncType !== undefined);
@@ -855,9 +845,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * Detect Element deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against Elements
      * in the source iModel.
      * @deprecated in 1.x. Do not use this. // FIXME<MIKE>: how to better explain this?
-     * This method is only called during [[processAll]] when the option
+     * This method is only called during [[process]] when [[IModelTransformOptions.argsForProcessChanges]] is undefined and the option
      * [[IModelTransformOptions.forceExternalSourceAspectProvenance]] is enabled. It is not
-     * necessary when using [[processChanges]] since changeset information is sufficient.
+     * necessary when calling [[process]] with [[IModelTransformOptions.argsForProcessChanges]] defined, since changeset information is sufficient.
      * @note you do not need to call this directly unless processing a subset of an iModel.
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
@@ -887,12 +877,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
         });
     }
-    /**
-     * @deprecated in 3.x, this no longer has any effect except emitting a warning
-     */
-    skipElement(_sourceElement) {
-        core_bentley_1.Logger.logWarning(loggerCategory, "Tried to defer/skip an element, which is no longer necessary");
-    }
     /** Transform the specified sourceElement into ElementProps for the target iModel.
      * @param sourceElement The Element from the source iModel to transform.
      * @returns ElementProps for the target iModel.
@@ -937,85 +921,74 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         nodeAssert(this._hasElementChangedCache !== undefined, "has element changed cache should be initialized by now");
         return this._hasElementChangedCache.has(sourceElement.id);
     }
-    static transformCallbackFor(transformer, entity) {
-        if (entity instanceof core_backend_1.Element)
-            return transformer.onTransformElement; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.Element)
-            return transformer.onTransformModel; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.Relationship)
-            return transformer.onTransformRelationship; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.ElementAspect)
-            return transformer.onTransformElementAspect; // eslint-disable-line @typescript-eslint/unbound-method
-        else
-            (0, core_bentley_1.assert)(false, `unreachable; entity was '${entity.constructor.name}' not an Element, Relationship, or ElementAspect`);
-    }
-    /** callback to perform when a partial element says it's ready to be completed
-     * transforms the source element with all references now valid, then updates the partial element with the results
-     */
-    makePartialEntityCompleter(sourceEntity) {
-        return () => {
-            const targetId = this.context.findTargetEntityId(core_backend_1.EntityReferences.from(sourceEntity));
-            if (!core_backend_1.EntityReferences.isValid(targetId))
-                throw Error(`${sourceEntity.id} has not been inserted into the target yet, the completer is invalid. This is a bug.`);
-            const onEntityTransform = IModelTransformer.transformCallbackFor(this, sourceEntity);
-            const updateEntity = EntityUnifier_1.EntityUnifier.updaterFor(this.targetDb, sourceEntity);
-            const targetProps = onEntityTransform.call(this, sourceEntity);
-            if (sourceEntity instanceof core_backend_1.Relationship) {
-                targetProps.sourceId =
-                    this.context.findTargetElementId(sourceEntity.sourceId);
-                targetProps.targetId =
-                    this.context.findTargetElementId(sourceEntity.targetId);
+    completePartiallyCommittedElements() {
+        for (const sourceElementId of this._partiallyCommittedElementIds) {
+            const sourceElement = this.sourceDb.elements.getElement({
+                id: sourceElementId,
+                wantGeometry: this.exporter.wantGeometry,
+                wantBRepData: this.exporter.wantGeometry,
+            });
+            const targetId = this.context.findTargetElementId(sourceElementId);
+            if (core_bentley_1.Id64.isInvalid(targetId)) {
+                throw new Error(`source-target element mapping not found for element "${sourceElementId}" when completing partially committed elements. This is a bug.`);
             }
-            updateEntity({ ...targetProps, id: core_backend_1.EntityReferences.toId64(targetId) });
-            this._partiallyCommittedEntities.delete(sourceEntity);
-        };
+            const targetProps = this.onTransformElement(sourceElement);
+            this.targetDb.elements.updateElement({ ...targetProps, id: targetId });
+        }
     }
-    /** collect references this entity has that are yet to be mapped, and if there are any
-     * create a [[PartiallyCommittedEntity]] to track resolution of those references
-     */
-    collectUnmappedReferences(entity) {
-        const missingReferences = new core_common_1.EntityReferenceSet();
-        let thisPartialElem;
-        // eslint-disable-next-line deprecation/deprecation
-        for (const referenceId of entity.getReferenceConcreteIds()) {
-            // TODO: probably need to rename from 'id' to 'ref' so these names aren't so ambiguous
-            const referenceIdInTarget = this.context.findTargetEntityId(referenceId);
-            const alreadyProcessed = core_backend_1.EntityReferences.isValid(referenceIdInTarget) ||
-                this._skippedEntities.has(referenceId);
-            if (alreadyProcessed)
-                continue;
-            core_bentley_1.Logger.logTrace(loggerCategory, `Deferring resolution of reference '${referenceId}' of element '${entity.id}'`);
-            const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
-                entityReference: referenceId,
+    completePartiallyCommittedAspects() {
+        for (const sourceAspectId of this._partiallyCommittedAspectIds) {
+            const sourceAspect = this.sourceDb.elements.getAspect(sourceAspectId);
+            const targetAspectId = this.context.findTargetAspectId(sourceAspectId);
+            if (core_bentley_1.Id64.isInvalid(targetAspectId)) {
+                throw new Error(`source-target aspect mapping not found for aspect "${sourceAspectId}" when completing partially committed aspects. This is a bug.`);
+            }
+            const targetAspectProps = this.onTransformElementAspect(sourceAspect);
+            this.targetDb.elements.updateAspect({
+                ...targetAspectProps,
+                id: targetAspectId,
             });
-            if (!referencedExistsInSource) {
-                core_bentley_1.Logger.logWarning(loggerCategory, `Source ${EntityUnifier_1.EntityUnifier.getReadableType(entity)} (${entity.id}) has a dangling reference to (${referenceId})`);
-                switch (this._options.danglingReferencesBehavior) {
-                    case "ignore":
-                        continue;
-                    case "reject":
-                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
-                            `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
-                            "This must have been caused by an upstream application that changed the iModel.",
-                            "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this, but this will leave the iModel",
-                            "in a state where downstream consuming applications will need to handle the invalidity themselves. In some cases, writing a custom",
-                            "transformer to remove the reference and fix affected elements may be suitable.",
-                        ].join("\n"));
+        }
+    }
+    doAllReferencesExistInTarget(entity) {
+        let allReferencesExist = true;
+        for (const referenceId of entity.getReferenceIds()) {
+            const referencedEntityId = core_backend_1.EntityReferences.toId64(referenceId);
+            if (referencedEntityId === core_common_1.IModel.repositoryModelId ||
+                referencedEntityId === core_common_1.IModel.dictionaryId ||
+                referencedEntityId === "0xe") {
+                continue;
+            }
+            if (allReferencesExist &&
+                !core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {
+                // if we care about references existing then we cannot return early and must check all other references.
+                if (this._options.danglingReferencesBehavior === "ignore") {
+                    return false;
                 }
+                allReferencesExist = false;
             }
-            if (thisPartialElem === undefined) {
-                thisPartialElem = new PartiallyCommittedEntity(missingReferences, this.makePartialEntityCompleter(entity));
-                if (!this._partiallyCommittedEntities.has(entity))
-                    this._partiallyCommittedEntities.set(entity, thisPartialElem);
+            if (this._options.danglingReferencesBehavior === "reject") {
+                this.assertReferenceExistsInSource(referenceId, entity);
             }
-            missingReferences.add(referenceId);
-            const entityReference = core_backend_1.EntityReferences.from(entity);
-            this._pendingReferences.set({ referenced: referenceId, referencer: entityReference }, thisPartialElem);
+        }
+        return allReferencesExist;
+    }
+    assertReferenceExistsInSource(referenceId, entity) {
+        const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
+            entityReference: referenceId,
+        });
+        if (!referencedExistsInSource) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
+                `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
+                "This must have been caused by an upstream application that changed the iModel.",
+                "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this,",
+                `and the referenceId found on "${entity.id}" will not be carried over to corresponding target element.`,
+            ].join("\n"));
         }
     }
     /** Cause the specified Element and its child Elements (if applicable) to be exported from the source iModel and imported into the target iModel.
      * @param sourceElementId Identifies the Element from the source iModel to import.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processElement(sourceElementId) {
         await this.initialize();
@@ -1026,7 +999,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Import child elements into the target IModelDb
      * @param sourceElementId Import the child elements of this element in the source IModelDb.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processChildElements(sourceElementId) {
         await this.initialize();
@@ -1038,24 +1011,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     shouldExportElement(_sourceElement) {
         return true;
     }
-    onSkipElement(sourceElementId) {
-        if (this.context.findTargetElementId(sourceElementId) !== core_bentley_1.Id64.invalid) {
-            // element already has provenance
-            return;
-        }
-        core_bentley_1.Logger.logInfo(loggerCategory, `Element '${sourceElementId}' won't be exported. Marking its references as resolved`);
-        const elementKey = `e${sourceElementId}`;
-        this._skippedEntities.add(elementKey);
-        // Mark any existing pending references to the skipped element as resolved.
-        for (const referencer of this._pendingReferences.getReferencersByEntityKey(elementKey)) {
-            const key = PendingReferenceMap_1.PendingReference.from(referencer, elementKey);
-            const pendingRef = this._pendingReferences.get(key);
-            if (!pendingRef)
-                continue;
-            pendingRef.resolveReference(elementKey);
-            this._pendingReferences.delete(key);
-        }
-    }
     /**
      * If they haven't been already, import all of the required references
      * @internal do not call, override or implement this, it will be removed
@@ -1122,11 +1077,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     onExportElement(sourceElement) {
         let targetElementId;
         let targetElementProps;
-        if (this._options.preserveElementIdsForFiltering) {
-            targetElementId = sourceElement.id;
-            targetElementProps = this.onTransformElement(sourceElement);
-        }
-        else if (this._options.wasSourceIModelCopiedToTarget) {
+        if (this._options.wasSourceIModelCopiedToTarget) {
             targetElementId = sourceElement.id;
             targetElementProps =
                 this.targetDb.elements.getElementProps(targetElementId);
@@ -1165,17 +1116,40 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         if (!this.hasElementChanged(sourceElement))
             return;
-        this.collectUnmappedReferences(sourceElement);
+        if (!this.doAllReferencesExistInTarget(sourceElement)) {
+            this._partiallyCommittedElementIds.add(sourceElement.id);
+        }
         // targetElementId will be valid (indicating update) or undefined (indicating insert)
         targetElementProps.id = core_bentley_1.Id64.isValid(targetElementId)
             ? targetElementId
             : undefined;
+        if (this._options.preserveElementIdsForFiltering) {
+            const isValid = core_bentley_1.Id64.isValid(targetElementId);
+            if (isValid && targetElementId !== sourceElement.id) {
+                // Element found with different id
+                throw new Error(`Element id(${sourceElement.id}) cannot be preserved. Found a different mapping(${targetElementId}) from source element`);
+            }
+            else if (isValid && targetElementId === sourceElement.id) {
+                // targetElementId is valid (indicating update)
+                this.importer.markElementToUpdateDuringPreserveIds(sourceElement.id);
+            }
+            else if (!isValid) {
+                const sourceInTargetElemProps = this.targetDb.elements.tryGetElementProps(sourceElement.id);
+                // if we don't find mapping for source element in target(invalid) but another element with source id exists in target
+                if (sourceInTargetElemProps) {
+                    // Element id is already taken by another element
+                    throw new Error(`Element id(${sourceElement.id}) cannot be preserved. An unrelated element in the target already uses id: ${sourceElement.id}`);
+                }
+                else {
+                    // Element id in target is available to be remapped
+                    targetElementProps.id = sourceElement.id;
+                }
+            }
+        }
         if (!this._options.wasSourceIModelCopiedToTarget) {
             this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
         }
         this.context.remapElement(sourceElement.id, targetElementProps.id); // targetElementProps.id assigned by importElement
-        // now that we've mapped this elem we can fix unmapped references to it
-        this.resolvePendingReferences(sourceElement);
         // the transformer does not currently 'split' or 'join' any elements, therefore, it does not
         // insert external source aspects because federation guids are sufficient for this.
         // Other transformer subclasses must insert the appropriate aspect (as provided by a TBD API)
@@ -1203,16 +1177,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.markLastProvenance(provenance, { isRelationship: false });
         }
     }
-    resolvePendingReferences(entity) {
-        for (const referencer of this._pendingReferences.getReferencers(entity)) {
-            const key = PendingReferenceMap_1.PendingReference.from(referencer, entity);
-            const pendingRef = this._pendingReferences.get(key);
-            if (!pendingRef)
-                continue;
-            pendingRef.resolveReference(core_backend_1.EntityReferences.from(entity));
-            this._pendingReferences.delete(key);
-        }
-    }
     /** Override of [IModelExportHandler.onDeleteElement]($transformer) that is called when [IModelExporter]($transformer) detects that an Element has been deleted from the source iModel.
      * This override propagates the delete to the target iModel via [IModelImporter.deleteElement]($transformer).
      */
@@ -1237,7 +1201,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             return;
         const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
         this.importer.importModel(targetModelProps);
-        this.resolvePendingReferences(sourceModel);
     }
     /** Override of [IModelExportHandler.onDeleteModel]($transformer) that is called when [IModelExporter]($transformer) detects that a [Model]($backend) has been deleted from the source iModel. */
     onDeleteModel(sourceModelId) {
@@ -1311,7 +1274,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Cause the model container, contents, and sub-models to be exported from the source iModel and imported into the target iModel.
      * @param sourceModeledElementId Import this [Model]($backend) from the source IModelDb.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processModel(sourceModeledElementId) {
         await this.initialize();
@@ -1321,7 +1284,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @param sourceModelId Import the contents of this model from the source IModelDb.
      * @param targetModelId Import into this model in the target IModelDb. The target model must exist prior to this call.
      * @param elementClassFullName Optional classFullName of an element subclass to limit import query against the source model.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processModelContents(sourceModelId, targetModelId, elementClassFullName = core_backend_1.Element.classFullName) {
         await this.initialize();
@@ -1378,46 +1341,50 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
         return targetModelProps;
     }
-    /** Import elements that were deferred in a prior pass.
-     * @deprecated in 3.x. This method is no longer necessary since the transformer no longer needs to defer elements
-     */
-    async processDeferredElements(_numRetries = 3) { }
-    /** called at the end of a transformation,
+    /**
+     * Called at the end of a transformation,
      * updates the target scope element to say that transformation up through the
      * source's changeset has been performed. Also stores all changesets that occurred
      * during the transformation as "pending synchronization changeset indices" @see TargetScopeProvenanceJsonProps
      *
-     * You generally should not call this function yourself and use [[processChanges]] instead.
+     * You generally should not call this function yourself and use [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided instead.
      * It is public for unsupported use cases of custom synchronization transforms.
-     * @note if you are not running processChanges in this transformation, this will fail
-     * without setting the `force` option to `true`
+     * @note If [[IModelTransformOptions.argsForProcessChanges]] is not defined in this transformation, this function will return early without updating the sync version,
+     * unless the `initializeReverseSyncVersion` option is set to `true`
+     *
+     * The `initializeReverseSyncVersion` is added to set the reverse synchronization version during a forward synchronization.
+     * When set to `true`, it saves the reverse sync version as the current changeset of the targetDb. This is typically used for the first transformation between a master and branch iModel.
+     * Setting `initializeReverseSyncVersion` to `true` has the effect of making it so any changesets in the branch iModel at the time of the first transformation will be ignored during any future reverse synchronizations from the branch to the master iModel.
+     *
+     * Note that typically, the reverseSyncVersion is saved as the last changeset merged from the branch into master.
+     * Setting initializeReverseSyncVersion to true during a forward transformation could overwrite this correct reverseSyncVersion and should only be done during the first transformation between a master and branch iModel.
      */
-    updateSynchronizationVersion({ force = false } = {}) {
-        const notForcedAndHasNoChangesAndIsntProvenanceInit = !force &&
-            this._sourceChangeDataState !== "has-changes" &&
-            !this._isProvenanceInitTransform;
-        if (notForcedAndHasNoChangesAndIsntProvenanceInit)
+    updateSynchronizationVersion({ initializeReverseSyncVersion = false, } = {}) {
+        const shouldSkipSyncVersionUpdate = !initializeReverseSyncVersion &&
+            this._sourceChangeDataState !== "has-changes";
+        if (shouldSkipSyncVersionUpdate)
             return;
         nodeAssert(this._targetScopeProvenanceProps);
         const sourceVersion = `${this.sourceDb.changeset.id};${this.sourceDb.changeset.index}`;
         const targetVersion = `${this.targetDb.changeset.id};${this.targetDb.changeset.index}`;
-        if (this._isProvenanceInitTransform) {
-            this._targetScopeProvenanceProps.version = sourceVersion;
-            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
-                targetVersion;
-        }
-        else if (this.isReverseSynchronization) {
+        if (this.isReverseSynchronization) {
             const oldVersion = this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion;
             core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse version from ${oldVersion} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
                 sourceVersion;
         }
-        else if (!this.isReverseSynchronization) {
+        else {
             core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${this._targetScopeProvenanceProps.version} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.version = sourceVersion;
+            // save reverse sync version
+            if (initializeReverseSyncVersion) {
+                core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse sync version from ${this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion} to ${targetVersion}`);
+                this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
+                    targetVersion;
+            }
         }
-        if (this._isSynchronization ||
-            (this._startingChangesetIndices && this._isProvenanceInitTransform)) {
+        if (this._options.argsForProcessChanges ||
+            (this._startingChangesetIndices && initializeReverseSyncVersion)) {
             nodeAssert(this.targetDb.changeset.index !== undefined &&
                 this._startingChangesetIndices !== undefined, "updateSynchronizationVersion was called without change history");
             const jsonProps = this._targetScopeProvenanceProps.jsonProperties;
@@ -1425,16 +1392,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingSyncChanges: ${jsonProps.pendingSyncChangesetIndices}`);
             const pendingSyncChangesetIndicesKey = "pendingSyncChangesetIndices";
             const pendingReverseSyncChangesetIndicesKey = "pendingReverseSyncChangesetIndices";
-            const [syncChangesetsToClearKey, syncChangesetsToUpdateKey] = this
-                .isReverseSynchronization
-                ? [
-                    pendingReverseSyncChangesetIndicesKey,
-                    pendingSyncChangesetIndicesKey,
-                ]
-                : [
-                    pendingSyncChangesetIndicesKey,
-                    pendingReverseSyncChangesetIndicesKey,
-                ];
+            // Determine which keys to clear and update based on the synchronization direction
+            let syncChangesetsToClearKey;
+            let syncChangesetsToUpdateKey;
+            if (this.isReverseSynchronization) {
+                syncChangesetsToClearKey = pendingReverseSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingSyncChangesetIndicesKey;
+            }
+            else {
+                syncChangesetsToClearKey = pendingSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingReverseSyncChangesetIndicesKey;
+            }
+            // NOTE that as documented in [[processChanges]], this assumes that right after
+            // transformation finalization, the work will be saved immediately, otherwise we've
+            // just marked this changeset as a synchronization to ignore, and the user can add other
+            // stuff to it which would break future synchronizations
             for (let i = this._startingChangesetIndices.target + 1; i <= this.targetDb.changeset.index + 1; i++)
                 jsonProps[syncChangesetsToUpdateKey].push(i);
             // Only keep the changeset indices which are greater than the source, this means they haven't been processed yet.
@@ -1454,25 +1426,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             ...this._targetScopeProvenanceProps,
             jsonProperties: JSON.stringify(this._targetScopeProvenanceProps.jsonProperties),
         });
+        this.clearCachedSynchronizationVersion();
     }
     // FIXME<MIKE>: is this necessary when manually using low level transform APIs? (document if so)
-    async finalizeTransformation(options) {
+    finalizeTransformation() {
         this.importer.finalize();
-        this.updateSynchronizationVersion();
-        if (this._partiallyCommittedEntities.size > 0) {
-            const message = [
-                "The following elements were never fully resolved:",
-                [...this._partiallyCommittedEntities.keys()].join(","),
-                "This indicates that either some references were excluded from the transformation",
-                "or the source has dangling references.",
-            ].join("\n");
-            if (this._options.danglingReferencesBehavior === "reject")
-                throw new Error(message);
-            core_bentley_1.Logger.logWarning(loggerCategory, message);
-            for (const partiallyCommittedElem of this._partiallyCommittedEntities.values()) {
-                partiallyCommittedElem.forceComplete();
-            }
-        }
+        this.updateSynchronizationVersion({
+            initializeReverseSyncVersion: this._isProvenanceInitTransform,
+        });
         // TODO: ignore if we remove change cache usage
         if (!this._options.noDetachChangeCache) {
             if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
@@ -1485,35 +1446,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.targetDb.codeValueBehavior = "trim-unicode-whitespace";
         }
         /* eslint-enable @itwin/no-internal */
-        const defaultSaveTargetChanges = () => this.targetDb.saveChanges();
-        await (options?.saveTargetChanges ?? defaultSaveTargetChanges)(this);
-        if (this.isReverseSynchronization)
-            this.sourceDb.saveChanges();
-        const description = `${this._isProvenanceInitTransform
-            ? options?.provenanceInitTransformChangesetDescription ??
-                `initialized branch provenance with master iModel: ${this.sourceDb.iModelId}`
-            : this.isForwardSynchronization
-                ? options?.forwardSyncBranchChangesetDescription ??
-                    `Forward sync of iModel: ${this.sourceDb.iModelId}`
-                : options?.reverseSyncMasterChangesetDescription ??
-                    `Reverse sync of iModel: ${this.sourceDb.iModelId}`}`;
-        if (this.targetDb.isBriefcaseDb()) {
-            // This relies on authorizationClient on iModelHost being defined, otherwise this will fail
-            await this.targetDb.pushChanges({
-                description,
-            });
-        }
-        if (this.isReverseSynchronization && this.sourceDb.isBriefcaseDb()) {
-            // This relies on authorizationClient on iModelHost being defined, otherwise this will fail
-            await this.sourceDb.pushChanges({
-                description: options?.reverseSyncBranchChangesetDescription ??
-                    `Update provenance in response to a reverse sync to iModel: ${this.targetDb.iModelId}`,
-            });
-        }
     }
     /** Imports all relationships that subclass from the specified base class.
      * @param baseRelClassFullName The specified base relationship class.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processRelationships(baseRelClassFullName) {
         await this.initialize();
@@ -1586,8 +1522,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Detect Relationship deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against relationships in the source iModel.
      * @deprecated in 1.x. Don't use this anymore
-     * @see processChanges
-     * @note This method is called from [[processAll]] and is not needed by [[processChanges]], so it only needs to be called directly when processing a subset of an iModel.
+     * @see [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided.
+     * @note This method is called from [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are undefined, so it only needs to be called directly when processing a subset of an iModel.
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
     async detectRelationshipDeletes() {
@@ -1654,22 +1590,25 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * This override calls [[onTransformElementAspect]] and then [IModelImporter.importElementUniqueAspect]($transformer) to update the target iModel.
      */
     onExportElementUniqueAspect(sourceAspect) {
-        const targetElementId = this.context.findTargetElementId(sourceAspect.element.id);
-        const targetAspectProps = this.onTransformElementAspect(sourceAspect, targetElementId);
-        this.collectUnmappedReferences(sourceAspect);
+        const targetAspectProps = this.onTransformElementAspect(sourceAspect);
+        if (!this.doAllReferencesExistInTarget(sourceAspect)) {
+            this._partiallyCommittedAspectIds.add(sourceAspect.id);
+        }
         const targetId = this.importer.importElementUniqueAspect(targetAspectProps);
         this.context.remapElementAspect(sourceAspect.id, targetId);
-        this.resolvePendingReferences(sourceAspect);
     }
     /** Override of [IModelExportHandler.onExportElementMultiAspects]($transformer) that imports ElementMultiAspects into the target iModel when they are exported from the source iModel.
      * This override calls [[onTransformElementAspect]] for each ElementMultiAspect and then [IModelImporter.importElementMultiAspects]($transformer) to update the target iModel.
      * @note ElementMultiAspects are handled as a group to make it easier to differentiate between insert, update, and delete.
      */
     onExportElementMultiAspects(sourceAspects) {
-        const targetElementId = this.context.findTargetElementId(sourceAspects[0].element.id);
         // Transform source ElementMultiAspects into target ElementAspectProps
-        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA, targetElementId));
-        sourceAspects.forEach((a) => this.collectUnmappedReferences(a));
+        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA));
+        sourceAspects.forEach((a) => {
+            if (!this.doAllReferencesExistInTarget(a)) {
+                this._partiallyCommittedAspectIds.add(a.id);
+            }
+        });
         // const targetAspectsToImport = targetAspectPropsArray.filter((targetAspect, i) => hasEntityChanged(sourceAspects[i], targetAspect));
         const targetIds = this.importer.importElementMultiAspects(targetAspectPropsArray, (a) => {
             const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect &&
@@ -1679,16 +1618,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         });
         for (let i = 0; i < targetIds.length; ++i) {
             this.context.remapElementAspect(sourceAspects[i].id, targetIds[i]);
-            this.resolvePendingReferences(sourceAspects[i]);
         }
     }
     /** Transform the specified sourceElementAspect into ElementAspectProps for the target iModel.
      * @param sourceElementAspect The ElementAspect from the source iModel to be transformed.
-     * @param _targetElementId The ElementId of the target Element that will own the ElementAspects after transformation.
      * @returns ElementAspectProps for the target iModel.
      * @note A subclass can override this method to provide custom transform behavior.
      */
-    onTransformElementAspect(sourceElementAspect, _targetElementId) {
+    onTransformElementAspect(sourceElementAspect) {
         const targetElementAspectProps = this.context.cloneElementAspect(sourceElementAspect);
         return targetElementAspectProps;
     }
@@ -1728,6 +1665,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             nodeAssert(schemaFileName.length <= systemMaxPathSegmentSize, "Schema name was still long. This is a bug.");
             this._longNamedSchemasMap.set(schema.name, schemaFileName);
         }
+        /* eslint-disable-next-line deprecation/deprecation */
         this.sourceDb.nativeDb.exportSchema(schema.name, this._schemaExportDir, schemaFileName);
         return { schemaPath: path.join(this._schemaExportDir, schemaFileName) };
     }
@@ -1768,7 +1706,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
     }
     /** Cause all fonts to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processFonts() {
         // we do not need to initialize for this since no entities are exported
@@ -1780,14 +1718,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.importFont(font.id);
     }
     /** Cause all CodeSpecs to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processCodeSpecs() {
         await this.initialize();
         return this.exporter.exportCodeSpecs();
     }
     /** Cause a single CodeSpec to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processCodeSpec(codeSpecName) {
         await this.initialize();
@@ -1811,21 +1749,23 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.remapElement(sourceSubjectId, targetSubjectId);
         await this.processChildElements(sourceSubjectId);
         await this.processSubjectSubModels(sourceSubjectId);
-        return this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        this.completePartiallyCommittedElements();
+        this.completePartiallyCommittedAspects();
     }
     /**
      * Initialize prerequisites of processing, you must initialize with an [[InitOptions]] if you
-     * are intending to process changes, but prefer using [[processChanges]] explicitly since it calls this.
+     * are intending to process changes. Callers may wish to explicitly call initialize if they need to execute code after initialize but before [[process]] is called.
      * @note Called by all `process*` functions implicitly.
      * Overriders must call `super.initialize()` first
      */
-    async initialize(args) {
+    async initialize() {
         if (this._initialized)
             return;
-        await this._tryInitChangesetData(args);
+        this.initScopeProvenance();
+        await this._tryInitChangesetData(this._options.argsForProcessChanges);
         await this.context.initialize();
         // need exporter initialized to do remapdeletedsourceentities.
-        await this.exporter.initialize(this.getExportInitOpts(args ?? {}));
+        await this.exporter.initialize(this.getExportInitOpts(this._options.argsForProcessChanges ?? {}));
         // Exporter must be initialized prior to processing changesets in order to properly handle entity recreations (an entity delete followed by an insert of that same entity).
         await this.processChangesets();
         this._initialized = true;
@@ -1891,7 +1831,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 const changeType = change.$meta?.op;
                 if (changeType === "Deleted" &&
                     change?.$meta?.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
-                    change.Scope.Id === this.targetScopeElementId) {
+                    change.Scope.Id === this.targetScopeElementId &&
+                    change.Kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
                     elemIdToScopeEsa.set(change.Element.Id, change);
                 }
                 else if ((changeType === "Inserted" || changeType === "Updated") &&
@@ -1930,7 +1871,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
         // we need a connected iModel with changes to remap elements with deletions
         const notConnectedModel = this.sourceDb.iTwinId === undefined;
-        const noChanges = this._synchronizationVersion.index === this.sourceDb.changeset.index;
+        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index;
         if (notConnectedModel || noChanges)
             return;
         /**
@@ -2027,17 +1968,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this._sourceChangeDataState = "unconnected";
             return;
         }
-        const noChanges = this._synchronizationVersion.index === this.sourceDb.changeset.index;
+        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index;
         if (noChanges) {
             this._sourceChangeDataState = "no-changes";
             this._csFileProps = [];
             return;
         }
+        const startChangeset = "startChangeset" in args ? args.startChangeset : undefined;
         // NOTE: that we do NOT download the changesummary for the last transformed version, we want
         // to ignore those already processed changes
-        const startChangesetIndexOrId = args.startChangeset?.index ??
-            args.startChangeset?.id ??
-            this._synchronizationVersion.index + 1;
+        const startChangesetIndexOrId = startChangeset?.index ??
+            startChangeset?.id ??
+            this.synchronizationVersion.index + 1;
         const endChangesetId = this.sourceDb.changeset.id;
         const [startChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetIndexOrId, endChangesetId].map(async (indexOrId) => typeof indexOrId === "number"
             ? indexOrId
@@ -2046,20 +1988,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 iModelId: this.sourceDb.iModelId,
                 // eslint-disable-next-line deprecation/deprecation
                 changeset: { id: indexOrId },
-                accessToken: args.accessToken,
             })
                 .then((changeset) => changeset.index)));
-        const missingChangesets = startChangesetIndex > this._synchronizationVersion.index + 1;
-        if (!this._options.ignoreMissingChangesetsInSynchronizations &&
-            startChangesetIndex !== this._synchronizationVersion.index + 1 &&
-            this._synchronizationVersion.index !== -1) {
+        const missingChangesets = startChangesetIndex > this.synchronizationVersion.index + 1;
+        if (!this._options.argsForProcessChanges
+            ?.ignoreMissingChangesetsInSynchronizations &&
+            startChangesetIndex !== this.synchronizationVersion.index + 1 &&
+            this.synchronizationVersion.index !== -1) {
             throw Error(`synchronization is ${missingChangesets ? "missing changesets" : ""},` +
                 " startChangesetId should be" +
                 " exactly the first changeset *after* the previous synchronization to not miss data." +
                 ` You specified '${startChangesetIndexOrId}' which is changeset #${startChangesetIndex}` +
-                ` but the previous synchronization for this targetScopeElement was '${this._synchronizationVersion.id}'` +
-                ` which is changeset #${this._synchronizationVersion.index}. The transformer expected` +
-                ` #${this._synchronizationVersion.index + 1}.`);
+                ` but the previous synchronization for this targetScopeElement was '${this.synchronizationVersion.id}'` +
+                ` which is changeset #${this.synchronizationVersion.index}. The transformer expected` +
+                ` #${this.synchronizationVersion.index + 1}.`);
         }
         nodeAssert(this._targetScopeProvenanceProps, "_targetScopeProvenanceProps should be set by now");
         const changesetsToSkip = this.isReverseSynchronization
@@ -2081,15 +2023,44 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             csFileProps.push(...fileProps);
         }
         this._csFileProps = csFileProps;
-        this._sourceChangeDataState = "has-changes";
+        /** Theres a possibility that our csFileProps length is still 0 here, since we skip cs indices found in the pendingSync and pendingReverseSync indices arrays. */
+        this._sourceChangeDataState =
+            this._csFileProps.length === 0 ? "no-changes" : "has-changes";
+    }
+    /**
+     * The behavior of process is influenced by [[IModelTransformOptions.argsForProcessChanges]] being defined or not defined during construction passed of the IModelTransformer.
+     * @section When argsForProcessChanges are defined:
+     *
+     * Export changes from the source iModel and import the transformed entities into the target iModel.
+     * Inserts, updates, and deletes are determined by inspecting the changeset(s).
+     *
+     * Notes:
+     * - the transformer assumes that you saveChanges after processing changes. You should not modify the iModel after processChanges until saveChanges,
+     * failure to do so may result in corrupted
+     * data loss in future branch operations
+     * - if no startChangesetId or startChangeset option is provided as part of the ProcessChangesOptions, the next unsynchronized changeset
+     * will automatically be determined and used
+     * - To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired range and open the source iModel as of the end (inclusive) of the desired range.
+     *
+     * @section When argsForProcessChanges are undefined:
+     *
+     * Export everything from the source iModel and import the transformed entities into the target iModel.
+     *
+     * Notes:
+     * - [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
+     *
+     */
+    async process() {
+        await this.initialize();
+        this.logSettings();
+        return this._options.argsForProcessChanges !== undefined
+            ? this.processChanges(this._options.argsForProcessChanges)
+            : this.processAll();
     }
     /** Export everything from the source iModel and import the transformed entities into the target iModel.
      * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
      */
-    async processAll(options) {
-        this.logSettings();
-        this.initScopeProvenance();
-        await this.initialize();
+    async processAll() {
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
         if (this._options.skipPropagateChangesToRootElements) {
@@ -2101,9 +2072,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         else {
             await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
         }
+        this.completePartiallyCommittedElements();
         await this.exporter["exportAllAspects"](); // eslint-disable-line @typescript-eslint/dot-notation
+        this.completePartiallyCommittedAspects();
         await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
-        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
         if (this._options.forceExternalSourceAspectProvenance &&
             this.shouldDetectDeletes()) {
             // eslint-disable-next-line deprecation/deprecation
@@ -2114,7 +2086,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        await this.finalizeTransformation(options);
+        this.finalizeTransformation();
     }
     markLastProvenance(sourceAspect, { isRelationship = false }) {
         this._lastProvenanceEntityInfo =
@@ -2131,42 +2103,45 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Export changes from the source iModel and import the transformed entities into the target iModel.
      * Inserts, updates, and deletes are determined by inspecting the changeset(s).
-     * @note the transformer saves and pushes changes when its work is complete.
+     * @note the transformer assumes that you saveChanges after processing changes. You should not
+     * modify the iModel after processChanges until saveChanges, failure to do so may result in corrupted
+     * data loss in future branch operations
      * @note if no startChangesetId or startChangeset option is provided as part of the ProcessChangesOptions, the next unsynchronized changeset
      * will automatically be determined and used
      * @note To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired range and open the source iModel as of the end (inclusive) of the desired range.
      */
     async processChanges(options) {
-        this._isSynchronization = true;
-        this.initScopeProvenance();
-        this.logSettings();
-        await this.initialize(options);
         // must wait for initialization of synchronization provenance data
         await this.exporter.exportChanges(this.getExportInitOpts(options));
-        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        this.completePartiallyCommittedElements();
+        this.completePartiallyCommittedAspects();
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        await this.finalizeTransformation(options);
+        this.finalizeTransformation();
+        const defaultSaveTargetChanges = () => {
+            this.targetDb.saveChanges();
+        };
+        await (options.saveTargetChanges ?? defaultSaveTargetChanges)(this);
     }
     /** Changeset data must be initialized in order to build correct changeOptions.
      * Call [[IModelTransformer.initialize]] for initialization of synchronization provenance data
      */
     getExportInitOpts(opts) {
-        if (!this._isSynchronization)
+        if (!this._options.argsForProcessChanges)
             return {};
+        const startChangeset = "startChangeset" in opts ? opts.startChangeset : undefined;
         return {
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
-            accessToken: opts.accessToken,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
             ...(this._csFileProps
                 ? { csFileProps: this._csFileProps }
                 : this._changesetRanges
                     ? { changesetRanges: this._changesetRanges }
-                    : opts.startChangeset
-                        ? { startChangeset: opts.startChangeset }
+                    : startChangeset
+                        ? { startChangeset }
                         : {
                             startChangeset: {
-                                index: this._synchronizationVersion.index + 1,
+                                index: this.synchronizationVersion.index + 1,
                             },
                         }),
         };
@@ -2245,8 +2220,7 @@ class TemplateModelCloner extends IModelTransformer {
     }
     /** Cloning from a template requires this override of onTransformElement. */
     onTransformElement(sourceElement) {
-        // eslint-disable-next-line deprecation/deprecation
-        const referenceIds = sourceElement.getReferenceConcreteIds();
+        const referenceIds = sourceElement.getReferenceIds();
         referenceIds.forEach((referenceId) => {
             // TODO: consider going through all definition elements at once and remapping them to themselves
             if (!core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {