@itwin/imodel-transformer 1.0.1-dev.0 → 1.1.0

package/lib/cjs/IModelTransformer.js

@@ -13,13 +13,12 @@ const Semver = require("semver");
 const nodeAssert = require("assert");
 const core_bentley_1 = require("@itwin/core-bentley");
 const core_geometry_1 = require("@itwin/core-geometry");
+const coreBackendPkgJson = require("@itwin/core-backend/package.json");
 const core_backend_1 = require("@itwin/core-backend");
 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");
@@ -30,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,
@@ -80,7 +55,7 @@ function mapId64(idContainer, func) {
     }
     else {
         throw Error([
-            `Id64 container '${idContainer}' is unsupported.`,
+            `Id64 container '${JSON.stringify(idContainer)}' is unsupported.`,
             "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
         ].join("\n"));
     }
@@ -149,7 +124,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 id: targetScopeElementId,
                 relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
             },
-            scope: { id: core_common_1.IModel.rootSubjectId },
+            scope: { id: core_common_1.IModel.rootSubjectId }, // the root Subject scopes scope elements
             identifier: sourceDb.iModelId,
             kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
             jsonProperties: undefined,
@@ -171,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 {
@@ -216,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.
@@ -232,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
@@ -253,7 +220,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._cachedSynchronizationVersion = undefined;
         this._targetClassNameToClassIdCache = new Map();
         // if undefined, it can be initialized by calling [[this.processChangesets]]
-        this._hasElementChangedCache = undefined;
         this._deletedSourceRelationshipData = undefined;
         this._yieldManager = new core_bentley_1.YieldManager();
         /** The directory where schemas will be exported, a random temporary directory */
@@ -273,11 +239,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             cloneUsingBinaryGeometry: options?.cloneUsingBinaryGeometry ?? true,
             targetScopeElementId: options?.targetScopeElementId ?? core_common_1.IModel.rootSubjectId,
             // eslint-disable-next-line deprecation/deprecation
-            danglingReferencesBehavior: options?.danglingReferencesBehavior ??
-                options?.danglingPredecessorsBehavior ??
-                "reject",
+            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
@@ -361,8 +330,7 @@ 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, `this._isReverseSynchronization=${this._options.isReverseSynchronization}`);
-        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.autoExtendProjectExtents=${this.importer.options.autoExtendProjectExtents}`);
+        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}`);
     }
     /** Return the IModelDb where IModelTransformer will store its provenance.
@@ -455,29 +423,30 @@ 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).
+    /**
+     * 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.
      */
-    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");
+    get hasDefinitionContainerDeletionFeature() {
+        if (this._hasDefinitionContainerDeletionFeature === undefined) {
+            this._hasDefinitionContainerDeletionFeature = Semver.satisfies(coreBackendPkgJson.version, "^4.6.0");
         }
-        return this._cachedSynchronizationVersion;
+        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) {
@@ -488,10 +457,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.
@@ -530,7 +504,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 id: this.targetScopeElementId,
                 relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
             },
-            scope: { id: core_common_1.IModel.rootSubjectId },
+            scope: { id: core_common_1.IModel.rootSubjectId }, // the root Subject scopes scope elements
             identifier: this.provenanceSourceDb.iModelId,
             kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
             jsonProperties: undefined,
@@ -567,29 +541,82 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     jsonProperties: JSON.stringify(aspectProps.jsonProperties),
                 });
                 aspectProps.id = id;
+                // Busting a potential cached version
+                this.clearCachedSynchronizationVersion();
             }
         }
         else {
             // foundEsaProps is defined.
             aspectProps.id = foundEsaProps.aspectId;
-            aspectProps.version =
-                foundEsaProps.version ??
-                    (this._options.branchRelationshipDataBehavior === "unsafe-migrate"
-                        ? ""
-                        : undefined);
+            aspectProps.version = foundEsaProps.version;
             aspectProps.jsonProperties = foundEsaProps.jsonProperties
                 ? JSON.parse(foundEsaProps.jsonProperties)
-                : this._options.branchRelationshipDataBehavior === "unsafe-migrate"
-                    ? {
-                        pendingReverseSyncChangesetIndices: [],
-                        pendingSyncChangesetIndices: [],
-                        reverseSyncVersion: "",
-                    }
-                    : undefined;
+                : undefined;
+            // 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 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 !==
+                    fallbackReverseSyncVersionToUse)) {
+            aspectProps.jsonProperties.reverseSyncVersion =
+                fallbackReverseSyncVersionToUse;
+            madeChange = true;
+        }
+        /**
+         * This case will only be hit when:
+         *  - first transformation was performed on pre-fedguid transformer.
+         *  - a second processAll transformation was performed on the same target-source iModels post-fedguid transformer.
+         *  - change processing was invoked on for the second 'initial' transformation.
+         *  NOTE: This case likely does not exist anymore, but we will keep it just to be sure.
+         */
+        if (aspectProps.jsonProperties.pendingReverseSyncChangesetIndices ===
+            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)
      * and call a function for each one.
@@ -685,9 +712,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             targetScopeElementId: this.targetScopeElementId,
             isReverseSynchronization: this.isReverseSynchronization,
             fn,
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? true,
         });
     }
+    /**
+     * Queries the provenanceDb for an ESA whose identifier is equal to the provided 'entityInProvenanceSourceId'.
+     * The identifier on the ESA is the id of the element in the [[IModelTransformer.provenanceSourceDb]]
+     * Therefore it only makes sense to call this function when you have an id in the provenanceSourceDb.
+     * @param entityInProvenanceSourceId
+     * @returns the elementId that the ESA is stored on, esa.Element.Id
+     */
     _queryProvenanceForElement(entityInProvenanceSourceId) {
         return this.provenanceDb.withPreparedStatement(`
         SELECT esa.Element.Id
@@ -705,6 +739,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 return undefined;
         });
     }
+    /**
+     * Queries the provenanceDb for an ESA whose identifier is equal to the provided 'entityInProvenanceSourceId'.
+     * The identifier on the ESA is the id of the relationship in the [[IModelTransformer.provenanceSourceDb]]
+     * Therefore it only makes sense to call this function when you have an id in the provenanceSourceDb.
+     * @param entityInProvenanceSourceId
+     * @returns
+     */
     _queryProvenanceForRelationship(entityInProvenanceSourceId, sourceRelInfo) {
         return this.provenanceDb.withPreparedStatement(`
         SELECT
@@ -793,7 +834,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);
@@ -803,9 +844,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.
      */
@@ -835,12 +876,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.
@@ -850,6 +885,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     onTransformElement(sourceElement) {
         core_bentley_1.Logger.logTrace(loggerCategory, `onTransformElement(${sourceElement.id}) "${sourceElement.getDisplayLabel()}"`);
         const targetElementProps = this.context.cloneElement(sourceElement, { binaryGeometry: this._options.cloneUsingBinaryGeometry });
+        // Special case: source element is the root subject
+        if (sourceElement.id === core_common_1.IModel.rootSubjectId) {
+            const targetElementId = this.context.findTargetElementId(sourceElement.id);
+            // When remapping rootSubject from source to non root subject in target, the code.scope gets remapped incorrectly.
+            // This is because the rootSubject has no parent and its code.scope is unique in that it is the id of itself.
+            // For all other subjects which do have parents the code.scope and its parent should be in agreement.
+            if (targetElementId !== core_bentley_1.Id64.invalid &&
+                targetElementId !== core_common_1.IModel.rootSubjectId) {
+                const targetElement = this.targetDb.elements.getElement(targetElementId);
+                targetElementProps.parent =
+                    targetElement.parent ?? targetElementProps.parent;
+                targetElementProps.code.scope = targetElement.code.scope;
+            }
+        }
         if (sourceElement instanceof core_backend_1.Subject) {
             if (targetElementProps.jsonProperties?.Subject?.Job) {
                 // don't propagate source channels into target (legacy bridge case)
@@ -860,97 +909,82 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Returns true if a change within sourceElement is detected.
      * @param sourceElement The Element from the source iModel
-     * @param targetElementId The Element from the target iModel to compare against.
      * @note A subclass can override this method to provide custom change detection behavior.
      */
-    hasElementChanged(sourceElement, _targetElementId) {
-        if (this._sourceChangeDataState === "no-changes")
-            return false;
-        if (this._sourceChangeDataState === "unconnected")
-            return true;
-        nodeAssert(this._sourceChangeDataState === "has-changes", "change data should be initialized by now");
-        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);
+    hasElementChanged(sourceElement) {
+        const sourceDbChanges = this.exporter.sourceDbChanges;
+        return (!sourceDbChanges || // are we processing changes? if not then element is considered as changed
+            sourceDbChanges.element.insertIds.has(sourceElement.id) ||
+            sourceDbChanges.element.updateIds.has(sourceElement.id));
+    }
+    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();
@@ -961,7 +995,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();
@@ -973,24 +1007,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
@@ -1057,11 +1073,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);
@@ -1098,20 +1110,44 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 }
             }
         }
-        if (core_bentley_1.Id64.isValid(targetElementId) &&
-            !this.hasElementChanged(sourceElement, targetElementId))
+        if (!this.hasElementChanged(sourceElement)) {
+            core_bentley_1.Logger.logTrace(loggerCategory, `Skipping unchanged element (${sourceElement.id}, ${sourceElement.getDisplayLabel()}).`);
             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)
@@ -1139,16 +1175,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).
      */
@@ -1168,12 +1194,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetModeledElementId = this.context.findTargetElementId(sourceModel.id);
         // there can only be one repositoryModel per database, so ignore the repo model on remapped subjects
         const isRemappedRootSubject = sourceModel.id === core_common_1.IModel.repositoryModelId &&
-            targetModeledElementId != sourceModel.id;
+            targetModeledElementId !== sourceModel.id;
         if (isRemappedRootSubject)
             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) {
@@ -1183,13 +1208,28 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetModelId = this.context.findTargetElementId(sourceModelId);
         if (!core_bentley_1.Id64.isValidId64(targetModelId))
             return;
+        let sql;
+        if (this.hasDefinitionContainerDeletionFeature) {
+            sql = `
+      SELECT 1
+      FROM bis.DefinitionPartition
+      WHERE ECInstanceId=:targetModelId
+      UNION
+      SELECT 1
+      FROM bis.DefinitionContainer
+      WHERE ECInstanceId=:targetModelId
+    `;
+        }
+        else {
+            sql = `
+      SELECT 1
+      FROM bis.DefinitionPartition
+      WHERE ECInstanceId=:targetModelId
+    `;
+        }
         if (this.exporter.sourceDbChanges?.element.deleteIds.has(sourceModelId)) {
-            const isDefinitionPartition = this.targetDb.withPreparedStatement(`
-        SELECT 1
-        FROM bis.DefinitionPartition
-        WHERE ECInstanceId=?
-      `, (stmt) => {
-                stmt.bindId(1, targetModelId);
+            const isDefinitionPartition = this.targetDb.withPreparedStatement(sql, (stmt) => {
+                stmt.bindId("targetModelId", targetModelId);
                 const val = stmt.step();
                 switch (val) {
                     case core_bentley_1.DbResult.BE_SQLITE_ROW:
@@ -1197,7 +1237,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     case core_bentley_1.DbResult.BE_SQLITE_DONE:
                         return false;
                     default:
-                        (0, core_bentley_1.assert)(false, `unexpected db result: '${stmt}'`);
+                        (0, core_bentley_1.assert)(false, `unexpected db result: '${JSON.stringify(stmt)}'`);
                 }
             });
             if (isDefinitionPartition) {
@@ -1232,7 +1272,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();
@@ -1242,7 +1282,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();
@@ -1299,66 +1339,78 @@ 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 ([[finalizeTransformation]]) 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;
             core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingReverseSyncChanges: ${jsonProps.pendingReverseSyncChangesetIndices}`);
             core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingSyncChanges: ${jsonProps.pendingSyncChangesetIndices}`);
-            const [syncChangesetsToClear, syncChangesetsToUpdate] = this
-                .isReverseSynchronization
-                ? [
-                    jsonProps.pendingReverseSyncChangesetIndices,
-                    jsonProps.pendingSyncChangesetIndices,
-                ]
-                : [
-                    jsonProps.pendingSyncChangesetIndices,
-                    jsonProps.pendingReverseSyncChangesetIndices,
-                ];
+            const pendingSyncChangesetIndicesKey = "pendingSyncChangesetIndices";
+            const pendingReverseSyncChangesetIndicesKey = "pendingReverseSyncChangesetIndices";
+            // 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++)
-                syncChangesetsToUpdate.push(i);
-            // FIXME: add test to synchronize an iModel that is not at the tip, since then clearning syncChangesets is
-            // probably wrong, and we should filter it instead
-            syncChangesetsToClear.length = 0;
+                jsonProps[syncChangesetsToUpdateKey].push(i);
+            // Only keep the changeset indices which are greater than the source, this means they haven't been processed yet.
+            jsonProps[syncChangesetsToClearKey] = jsonProps[syncChangesetsToClearKey].filter((csIndex) => {
+                return csIndex > this._startingChangesetIndices.source;
+            });
             // if reverse sync then we may have received provenance changes which should be marked as sync changes
             if (this.isReverseSynchronization) {
                 nodeAssert(this.sourceDb.changeset.index !== undefined, "changeset didn't exist");
@@ -1372,25 +1424,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))
@@ -1403,35 +1444,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();
@@ -1479,15 +1495,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             core_bentley_1.Logger.logWarning(loggerCategory, "tried to delete a relationship that wasn't in change data");
             return;
         }
-        const relArg = deletedRelData.relId ??
-            {
+        const id = deletedRelData.relId ??
+            this.targetDb.relationships.tryGetInstance(deletedRelData.classFullName, {
                 sourceId: deletedRelData.sourceIdInTarget,
                 targetId: deletedRelData.targetIdInTarget,
-            };
-        // FIXME: make importer.deleteRelationship not need full props
-        const targetRelationship = this.targetDb.relationships.tryGetInstance(deletedRelData.classFullName, relArg);
-        if (targetRelationship) {
-            this.importer.deleteRelationship(targetRelationship.toJSON());
+            })?.id;
+        if (id) {
+            this.importer.deleteRelationship({
+                id,
+                classFullName: deletedRelData.classFullName,
+            });
         }
         if (deletedRelData.provenanceAspectId) {
             try {
@@ -1503,8 +1520,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() {
@@ -1531,8 +1548,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     const json = JSON.parse(statement.getValue(2).getString());
                     const targetRelInstanceId = json.targetRelInstanceId ?? json.provenanceRelInstanceId;
                     if (targetRelInstanceId) {
-                        const targetRelationship = this.targetDb.relationships.getInstance(core_backend_1.ElementRefersToElements.classFullName, targetRelInstanceId);
-                        this.importer.deleteRelationship(targetRelationship.toJSON());
+                        this.importer.deleteRelationship({
+                            id: targetRelInstanceId,
+                            classFullName: core_backend_1.ElementRefersToElements.classFullName,
+                        });
                     }
                     aspectDeleteIds.push(statement.getValue(0).getId());
                 }
@@ -1569,22 +1588,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 &&
@@ -1594,16 +1616,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;
     }
@@ -1629,7 +1649,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         let schemaFileName = schema.name + ext;
         // many file systems have a max file-name/path-segment size of 255, so we workaround that on all systems
         const systemMaxPathSegmentSize = 255;
-        if (schemaFileName.length > systemMaxPathSegmentSize) {
+        // windows usually has a limit for the total path length of 260
+        const windowsMaxPathLimit = 260;
+        if (schemaFileName.length > systemMaxPathSegmentSize ||
+            path.join(this._schemaExportDir, schemaFileName).length >=
+                windowsMaxPathLimit) {
             // this name should be well under 255 bytes
             // ( 100 + (Number.MAX_SAFE_INTEGER.toString().length = 16) + (ext.length = 13) ) = 129 which is less than 255
             // You'd have to be past 2**53-1 (Number.MAX_SAFE_INTEGER) long named schemas in order to hit decimal formatting,
@@ -1639,6 +1663,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) };
     }
@@ -1679,7 +1704,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
@@ -1691,14 +1716,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();
@@ -1722,29 +1747,30 @@ 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;
     }
     /**
-     * Reads all the changeset files in the private member of the transformer: _csFileProps and does two things with these changesets.
-     * Finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
-     * Populates this._hasElementChangedCache with a set of elementIds that have been updated or inserted into the database.
+     * Reads all the changeset files in the private member of the transformer: _csFileProps
+     * and finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
      * This function returns early if csFileProps is undefined or is of length 0.
      * @returns void
      */
@@ -1752,9 +1778,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.forEachTrackedElement((sourceElementId, targetElementId) => {
             this.context.remapElement(sourceElementId, targetElementId);
         });
-        if (this._csFileProps === undefined || this._csFileProps.length === 0)
-            return;
-        const hasElementChangedCache = new Set();
+        if (this.exporter.sourceDbChanges)
+            await this.addCustomChanges(this.exporter.sourceDbChanges);
+        if (this._csFileProps === undefined || this._csFileProps.length === 0) {
+            if (this.exporter.sourceDbChanges === undefined ||
+                !this.exporter.sourceDbChanges.hasChanges)
+                return;
+            // our sourcedbChanges aren't empty (probably due to someone adding custom changes), change our sourceChangeDataState to has-changes
+            if (this._sourceChangeDataState === "no-changes")
+                this._sourceChangeDataState = "has-changes";
+        }
         const relationshipECClassIdsToSkip = new Set();
         for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)")) {
             relationshipECClassIdsToSkip.add(row.ECInstanceId);
@@ -1777,7 +1810,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 alreadyImportedModelInserts.add(targetModelId);
         });
         this._deletedSourceRelationshipData = new Map();
-        for (const csFile of this._csFileProps) {
+        for (const csFile of this._csFileProps ?? []) {
             const csReader = core_backend_1.SqliteChangesetReader.openFile({
                 fileName: csFile.pathname,
                 db: this.sourceDb,
@@ -1798,11 +1831,10 @@ 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")
-                    hasElementChangedCache.add(change.ECInstanceId);
             }
             // Loop to process deletes.
             for (const change of changes) {
@@ -1815,13 +1847,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 if (changeType !== "Deleted" ||
                     relationshipECClassIdsToSkip.has(ecClassId))
                     continue;
-                this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
+                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
             }
             csReader.close();
         }
-        this._hasElementChangedCache = hasElementChangedCache;
         return;
     }
+    /**
+     * This will be called when transformer is called with [[IModelTransformOptions.argsForProcessChanges]] to process changes.
+     * It will be executed after changes in changesets are populated into `sourceDbChanges` and before data processing begins.
+     * Remap table between the source and target iModels will be built at that time, meaning that functions like [[IModelTransformer.context.findTargetElementId]] will return meaningful results.
+     * This function should be used to modify the `sourceDbChanges`, if necessary, using `add custom change` methods in [[ChangedInstanceIds]], such as [[ChangedInstanceIds.addCustomElementChange]], [[ChangedInstanceIds.addCustomModelChange]] and other.
+     * @param sourceDbChanges the ChangedInstanceIds already populated by the exporter with the changes in source changesets, if any, passed to the transformer.
+     * @note Its expected that this function be overridden by a subclass of transformer if it needs to modify sourceDbChanges.
+     */
+    async addCustomChanges(_sourceDbChanges) { }
     /**
      * Helper function for processChangesets. Remaps the id of element deleted found in the 'change' to an element in the targetDb.
      * @param change the change to process, must be of changeType "Deleted"
@@ -1832,116 +1872,100 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
      * @returns void
      */
-    processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
+    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 &&
+            (this.exporter.sourceDbChanges === undefined ||
+                !this.exporter.sourceDbChanges.hasChanges);
         if (notConnectedModel || noChanges)
             return;
-        // optimization: if we have provenance, use it to avoid more querying later
-        // eventually when itwin.js supports attaching a second iModelDb in JS,
-        // this won't have to be a conditional part of the query, and we can always have it by attaching
-        const queryCanAccessProvenance = this.sourceDb === this.provenanceDb;
-        const instId = change.ECInstanceId;
-        if (!isRelationship) {
-            const sourceElemFedGuid = change.FederationGuid;
+        /**
+         * if our ChangedECInstance is in the provenanceDb, then we can use the ids we find in the ChangedECInstance to query for ESAs.
+         * This is because the ESAs are stored on an element Id thats present in the provenanceDb.
+         */
+        const changeDataInProvenanceDb = this.sourceDb === this.provenanceDb;
+        const getTargetIdFromSourceId = async (id) => {
             let identifierValue;
-            if (queryCanAccessProvenance) {
-                const aspects = this.sourceDb.elements.getAspects(instId, core_backend_1.ExternalSourceAspect.classFullName);
-                for (const aspect of aspects) {
-                    // look for aspect where the ecInstanceId = the aspect.element.id
-                    if (aspect.element.id === instId &&
-                        aspect.scope.id === this.targetScopeElementId)
-                        identifierValue = aspect.identifier;
-                }
-                // Think I need to query the esas given the instId.. not sure what db to do it on though.. soruce or target.. or provenance?
-                // I need to know the id of the element dpeneding on which db its stored in.
+            let element;
+            if (isRelationship) {
+                element = this.sourceDb.elements.tryGetElement(id);
             }
-            if (queryCanAccessProvenance && !identifierValue) {
-                if (mapOfDeletedElemIdToScopeEsas.get(instId) !== undefined)
-                    identifierValue =
-                        mapOfDeletedElemIdToScopeEsas.get(instId).Identifier;
+            const fedGuid = isRelationship
+                ? element?.federationGuid
+                : change.FederationGuid;
+            if (changeDataInProvenanceDb) {
+                // TODO: clarify what happens if there are multiple (e.g. elements were merged)
+                for await (const row of this.sourceDb.createQueryReader("SELECT esa.Identifier FROM bis.ExternalSourceAspect esa WHERE Scope.Id=:scopeId AND Kind=:kind AND Element.Id=:relatedElementId LIMIT 1", core_common_1.QueryBinder.from([
+                    this.targetScopeElementId,
+                    core_backend_1.ExternalSourceAspect.Kind.Element,
+                    id,
+                ]))) {
+                    identifierValue = row.Identifier;
+                }
+                identifierValue =
+                    identifierValue ?? mapOfDeletedElemIdToScopeEsas.get(id)?.Identifier;
             }
-            const targetId = (queryCanAccessProvenance && identifierValue) ||
-                // maybe batching these queries would perform better but we should
-                // try to attach the second db and query both together anyway
-                (sourceElemFedGuid &&
-                    this._queryElemIdByFedGuid(this.targetDb, sourceElemFedGuid)) ||
-                // FIXME<MIKE>: describe why it's safe to assume nothing has been deleted in provenanceDb
-                this._queryProvenanceForElement(instId);
-            // since we are processing one changeset at a time, we can see local source deletes
-            // of entities that were never synced and can be safely ignored
-            const deletionNotInTarget = !targetId;
-            if (deletionNotInTarget)
-                return;
-            this.context.remapElement(instId, targetId);
-            // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
-            // In such case an entity update will be triggered and we no longer need to delete the entity.
-            if (alreadyImportedElementInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.element.deleteIds.delete(instId);
+            // Check for targetId by an esa first
+            if (changeDataInProvenanceDb && identifierValue) {
+                const targetId = identifierValue;
+                return targetId;
             }
-            if (alreadyImportedModelInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.model.deleteIds.delete(instId);
+            // Check for targetId using sourceId's fedguid if we didn't find an esa.
+            if (fedGuid) {
+                const targetId = this._queryElemIdByFedGuid(this.targetDb, fedGuid);
+                return targetId;
             }
-        }
-        else {
-            // is deleted relationship
-            const classFullName = change.$meta?.classFullName;
+            return undefined;
+        };
+        const changedInstanceId = change.ECInstanceId;
+        if (isRelationship) {
             const sourceIdOfRelationshipInSource = change.SourceECInstanceId;
             const targetIdOfRelationshipInSource = change.TargetECInstanceId;
-            const [sourceIdInTarget, targetIdInTarget] = [
-                sourceIdOfRelationshipInSource,
-                targetIdOfRelationshipInSource,
-            ].map((id) => {
-                let element;
-                try {
-                    element = this.sourceDb.elements.getElement(id);
-                }
-                catch (err) {
-                    return undefined;
-                }
-                const fedGuid = element.federationGuid;
-                let identifierValue;
-                if (queryCanAccessProvenance) {
-                    const aspects = this.sourceDb.elements.getAspects(id, core_backend_1.ExternalSourceAspect.classFullName);
-                    for (const aspect of aspects) {
-                        if (aspect.element.id === id &&
-                            aspect.scope.id === this.targetScopeElementId)
-                            identifierValue = aspect.identifier;
-                    }
-                    if (identifierValue === undefined) {
-                        if (mapOfDeletedElemIdToScopeEsas.get(id) !== undefined)
-                            identifierValue =
-                                mapOfDeletedElemIdToScopeEsas.get(id).Identifier;
-                    }
-                }
-                return ((queryCanAccessProvenance && identifierValue) ||
-                    // maybe batching these queries would perform better but we should
-                    // try to attach the second db and query both together anyway
-                    (fedGuid && this._queryElemIdByFedGuid(this.targetDb, fedGuid)));
-            });
-            if (sourceIdInTarget && targetIdInTarget) {
-                this._deletedSourceRelationshipData.set(instId, {
+            const classFullName = change.$meta?.classFullName;
+            const sourceIdOfRelationshipInTarget = await getTargetIdFromSourceId(sourceIdOfRelationshipInSource);
+            const targetIdOfRelationshipInTarget = await getTargetIdFromSourceId(targetIdOfRelationshipInSource);
+            if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
+                this._deletedSourceRelationshipData.set(changedInstanceId, {
                     classFullName: classFullName ?? "",
-                    sourceIdInTarget,
-                    targetIdInTarget,
+                    sourceIdInTarget: sourceIdOfRelationshipInTarget,
+                    targetIdInTarget: targetIdOfRelationshipInTarget,
                 });
             }
-            else {
-                // FIXME<MIKE>: describe why it's safe to assume nothing has been deleted in provenanceDb
-                const relProvenance = this._queryProvenanceForRelationship(instId, {
+            else if (this.sourceDb === this.provenanceSourceDb) {
+                const relProvenance = this._queryProvenanceForRelationship(changedInstanceId, {
                     classFullName: classFullName ?? "",
                     sourceId: sourceIdOfRelationshipInSource,
                     targetId: targetIdOfRelationshipInSource,
                 });
                 if (relProvenance && relProvenance.relationshipId)
-                    this._deletedSourceRelationshipData.set(instId, {
+                    this._deletedSourceRelationshipData.set(changedInstanceId, {
                         classFullName: classFullName ?? "",
                         relId: relProvenance.relationshipId,
                         provenanceAspectId: relProvenance.aspectId,
                     });
             }
         }
+        else {
+            let targetId = await getTargetIdFromSourceId(changedInstanceId);
+            if (targetId === undefined && this.sourceDb === this.provenanceSourceDb) {
+                targetId = this._queryProvenanceForElement(changedInstanceId);
+            }
+            // since we are processing one changeset at a time, we can see local source deletes
+            // of entities that were never synced and can be safely ignored
+            const deletionNotInTarget = !targetId;
+            if (deletionNotInTarget)
+                return;
+            this.context.remapElement(changedInstanceId, targetId);
+            // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
+            // In such case an entity update will be triggered and we no longer need to delete the entity.
+            if (alreadyImportedElementInserts.has(targetId)) {
+                this.exporter.sourceDbChanges?.element.deleteIds.delete(changedInstanceId);
+            }
+            if (alreadyImportedModelInserts.has(targetId)) {
+                this.exporter.sourceDbChanges?.model.deleteIds.delete(changedInstanceId);
+            }
+        }
     }
     async _tryInitChangesetData(args) {
         if (!args ||
@@ -1950,17 +1974,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
@@ -1969,20 +1994,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
@@ -2004,19 +2029,47 @@ 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) {
-            // FIXME<NICK>: This option in exportAll was a maybe.
             // The RepositoryModel and root Subject of the target iModel should not be transformed.
             await this.exporter.exportChildElements(core_common_1.IModel.rootSubjectId); // start below the root Subject
             await this.exporter.exportModelContents(core_common_1.IModel.repositoryModelId, core_backend_1.Element.classFullName, true); // after the Subject hierarchy, process the other elements of the RepositoryModel
@@ -2025,18 +2078,21 @@ 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
             await this.detectElementDeletes();
+            // eslint-disable-next-line deprecation/deprecation
             await this.detectRelationshipDeletes();
         }
         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 =
@@ -2051,240 +2107,47 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                         : core_backend_1.ExternalSourceAspect.Kind.Element,
                 };
     }
-    /**
-     * Load the state of the active transformation from an open SQLiteDb
-     * You can override this if you'd like to load from custom tables in the resumable dump state, but you should call
-     * this super implementation
-     * @note the SQLiteDb must be open
-     */
-    loadStateFromDb(db) {
-        const lastProvenanceEntityInfo = db.withSqliteStatement(`SELECT entityId, aspectId, aspectVersion, aspectKind FROM ${IModelTransformer.lastProvenanceEntityInfoTable}`, (stmt) => {
-            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== stmt.step())
-                throw Error("expected row when getting lastProvenanceEntityId from target state table");
-            const entityId = stmt.getValueString(0);
-            const isGuidOrGuidPair = entityId.includes("-");
-            return isGuidOrGuidPair
-                ? entityId
-                : {
-                    entityId,
-                    aspectId: stmt.getValueString(1),
-                    aspectVersion: stmt.getValueString(2),
-                    aspectKind: stmt.getValueString(3),
-                };
-        });
-        /*
-        // TODO: maybe save transformer state resumption state based on target changset and require calls
-        // to saveChanges
-        if () {
-          const [sourceFedGuid, targetFedGuid, relClassFullName] = lastProvenanceEntityInfo.split("/");
-          const isRelProvenance = targetFedGuid !== undefined;
-          const instanceId = isRelProvenance
-            ? this.targetDb.elements.getElement({federationGuid: sourceFedGuid})
-            : "";
-          //const classId =
-          if (isRelProvenance) {
-          }
-        }
-        */
-        const targetHasCorrectLastProvenance = typeof lastProvenanceEntityInfo === "string" ||
-            // ignore provenance check if it's null since we can't bind those ids
-            !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.entityId) ||
-            !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.aspectId) ||
-            this.provenanceDb.withPreparedStatement(`
-        SELECT Version FROM ${core_backend_1.ExternalSourceAspect.classFullName}
-        WHERE Scope.Id=:scopeId
-          AND ECInstanceId=:aspectId
-          AND Kind=:kind
-          AND Element.Id=:entityId
-      `, (statement) => {
-                statement.bindId("scopeId", this.targetScopeElementId);
-                statement.bindId("aspectId", lastProvenanceEntityInfo.aspectId);
-                statement.bindString("kind", lastProvenanceEntityInfo.aspectKind);
-                statement.bindId("entityId", lastProvenanceEntityInfo.entityId);
-                const stepResult = statement.step();
-                switch (stepResult) {
-                    case core_bentley_1.DbResult.BE_SQLITE_ROW:
-                        const version = statement.getValue(0).getString();
-                        return version === lastProvenanceEntityInfo.aspectVersion;
-                    case core_bentley_1.DbResult.BE_SQLITE_DONE:
-                        return false;
-                    default:
-                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.SQLiteError, `got sql error ${stepResult}`);
-                }
-            });
-        if (!targetHasCorrectLastProvenance)
-            throw Error([
-                "Target for resuming from does not have the expected provenance ",
-                "from the target that the resume state was made with",
-            ].join("\n"));
-        this._lastProvenanceEntityInfo = lastProvenanceEntityInfo;
-        const state = db.withSqliteStatement(`SELECT data FROM ${IModelTransformer.jsStateTable}`, (stmt) => {
-            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== stmt.step())
-                throw Error("expected row when getting data from js state table");
-            return JSON.parse(stmt.getValueString(0));
-        });
-        if (state.transformerClass !== this.constructor.name)
-            throw Error("resuming from a differently named transformer class, it is not necessarily valid to resume with a different transformer class");
-        // force assign to readonly options since we do not know how the transformer subclass takes options to pass to the superclass
-        this._options = state.options;
-        this.context.loadStateFromDb(db);
-        this.importer.loadStateFromJson(state.importerState);
-        this.exporter.loadStateFromJson(state.exporterState);
-        this._elementsWithExplicitlyTrackedProvenance =
-            core_bentley_1.CompressedId64Set.decompressSet(state.explicitlyTrackedElements);
-        this.loadAdditionalStateJson(state.additionalState);
-    }
-    /**
-     * @deprecated in 0.1.x, this is buggy, and it is now equivalently efficient to simply restart the transformation
-     * from the original changeset
-     *
-     * Return a new transformer instance with the same remappings state as saved from a previous [[IModelTransformer.saveStateToFile]] call.
-     * This allows you to "resume" an iModel transformation, you will have to call [[IModelTransformer.processChanges]]/[[IModelTransformer.processAll]]
-     * again but the remapping state will cause already mapped elements to be skipped.
-     * To "resume" an iModel Transformation you need:
-     * - the sourceDb at the same changeset
-     * - the same targetDb in the state in which it was before
-     * @param statePath the path to the serialized state of the transformer, use [[IModelTransformer.saveStateToFile]] to get this from an existing transformer instance
-     * @param constructorArgs remaining arguments that you would normally pass to the Transformer subclass you are using, usually (sourceDb, targetDb)
-     * @note custom transformers with custom state may need to override this method in order to handle loading their own custom state somewhere
-     */
-    static resumeTransformation(statePath, ...constructorArgs) {
-        const transformer = new this(...constructorArgs);
-        const db = new core_backend_1.SQLiteDb();
-        db.openDb(statePath, core_bentley_1.OpenMode.Readonly);
-        try {
-            transformer.loadStateFromDb(db);
-        }
-        finally {
-            db.closeDb();
-        }
-        return transformer;
-    }
-    /**
-     * You may override this to store arbitrary json state in a transformer state dump, useful for some resumptions
-     * @see [[IModelTransformer.saveStateToFile]]
-     */
-    getAdditionalStateJson() {
-        return {};
-    }
-    /**
-     * You may override this to load arbitrary json state in a transformer state dump, useful for some resumptions
-     * @see [[IModelTransformer.loadStateFromFile]]
-     */
-    loadAdditionalStateJson(_additionalState) { }
-    /**
-     * Save the state of the active transformation to an open SQLiteDb
-     * You can override this if you'd like to write custom tables to the resumable dump state, but you should call
-     * this super implementation
-     * @note the SQLiteDb must be open
-     */
-    saveStateToDb(db) {
-        const jsonState = {
-            transformerClass: this.constructor.name,
-            options: this._options,
-            explicitlyTrackedElements: core_bentley_1.CompressedId64Set.compressSet(this._elementsWithExplicitlyTrackedProvenance),
-            importerState: this.importer.saveStateToJson(),
-            exporterState: this.exporter.saveStateToJson(),
-            additionalState: this.getAdditionalStateJson(),
-        };
-        this.context.saveStateToDb(db);
-        if (core_bentley_1.DbResult.BE_SQLITE_DONE !==
-            db.executeSQL(`CREATE TABLE ${IModelTransformer.jsStateTable} (data TEXT)`))
-            throw Error("Failed to create the js state table in the state database");
-        if (core_bentley_1.DbResult.BE_SQLITE_DONE !==
-            db.executeSQL(`
-      CREATE TABLE ${IModelTransformer.lastProvenanceEntityInfoTable} (
-        -- either the invalid id for null provenance state, federation guid (or pair for rels) of the entity, or a hex element id
-        entityId TEXT,
-        -- the following are only valid if the above entityId is a hex id representation
-        aspectId TEXT,
-        aspectVersion TEXT,
-        aspectKind TEXT
-      )
-    `))
-            throw Error("Failed to create the target state table in the state database");
-        db.saveChanges();
-        db.withSqliteStatement(`INSERT INTO ${IModelTransformer.jsStateTable} (data) VALUES (?)`, (stmt) => {
-            stmt.bindString(1, JSON.stringify(jsonState));
-            if (core_bentley_1.DbResult.BE_SQLITE_DONE !== stmt.step())
-                throw Error("Failed to insert options into the state database");
-        });
-        db.withSqliteStatement(`INSERT INTO ${IModelTransformer.lastProvenanceEntityInfoTable} (entityId, aspectId, aspectVersion, aspectKind) VALUES (?,?,?,?)`, (stmt) => {
-            const lastProvenanceEntityInfo = this
-                ._lastProvenanceEntityInfo;
-            stmt.bindString(1, lastProvenanceEntityInfo?.entityId ??
-                this._lastProvenanceEntityInfo);
-            stmt.bindString(2, lastProvenanceEntityInfo?.aspectId ?? "");
-            stmt.bindString(3, lastProvenanceEntityInfo?.aspectVersion ?? "");
-            stmt.bindString(4, lastProvenanceEntityInfo?.aspectKind ?? "");
-            if (core_bentley_1.DbResult.BE_SQLITE_DONE !== stmt.step())
-                throw Error("Failed to insert options into the state database");
-        });
-        db.saveChanges();
-    }
-    /**
-     * @deprecated in 0.1.x, this is buggy, and it is now equivalently efficient to simply restart the transformation
-     * from the original changeset
-     *
-     * Save the state of the active transformation to a file path, if a file at the path already exists, it will be overwritten
-     * This state can be used by [[IModelTransformer.resumeTransformation]] to resume a transformation from this point.
-     * The serialization format is a custom sqlite database.
-     * @note custom transformers with custom state may override [[IModelTransformer.saveStateToDb]] or [[IModelTransformer.getAdditionalStateJson]]
-     *       and [[IModelTransformer.loadStateFromDb]] (with a super call) or [[IModelTransformer.loadAdditionalStateJson]]
-     *       if they have custom state that needs to be stored with
-     *       potentially inside the same sqlite file in separate tables
-     */
-    saveStateToFile(nativeStatePath) {
-        const db = new core_backend_1.SQLiteDb();
-        if (core_backend_1.IModelJsFs.existsSync(nativeStatePath))
-            core_backend_1.IModelJsFs.unlinkSync(nativeStatePath);
-        db.createDb(nativeStatePath);
-        try {
-            this.saveStateToDb(db);
-            db.saveChanges();
-        }
-        finally {
-            db.closeDb();
-        }
-    }
     /** 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,
                             },
                         }),
         };
@@ -2303,10 +2166,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
 }
 exports.IModelTransformer = IModelTransformer;
 IModelTransformer.noEsaSyncDirectionErrorMessage = "Couldn't find an external source aspect to determine sync direction. This often means that the master->branch relationship has not been established. Consider running the transformer with wasSourceIModelCopiedToTarget set to true.";
-/** @internal the name of the table where javascript state of the transformer is serialized in transformer state dumps */
-IModelTransformer.jsStateTable = "TransformerJsState";
-/** @internal the name of the table where the target state heuristics is serialized in transformer state dumps */
-IModelTransformer.lastProvenanceEntityInfoTable = "LastProvenanceEntityInfo";
 /** IModelTransformer that clones the contents of a template model.
  * @beta
  */
@@ -2367,8 +2226,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))) {