@itwin/imodel-transformer 0.4.18-fedguidopt.6 → 1.0.0-dev.10

package/lib/cjs/IModelTransformer.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TemplateModelCloner = exports.IModelTransformer = void 0;
 /*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
 /** @packageDocumentation
  * @module iModels
  */
@@ -13,6 +13,7 @@ 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");
@@ -80,7 +81,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"));
     }
@@ -95,15 +96,115 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     get targetScopeElementId() {
         return this._options.targetScopeElementId;
     }
-    get _isReverseSynchronization() {
-        return this._isSynchronization && this._options.isReverseSynchronization;
+    /**
+     * Queries for an esa which matches the props in the provided aspectProps.
+     * @param dbToQuery db to run the query on for scope external source
+     * @param aspectProps aspectProps to search for @see ExternalSourceAspectProps
+     */
+    static queryScopeExternalSourceAspect(dbToQuery, aspectProps) {
+        const sql = `
+      SELECT ECInstanceId, Version, JsonProperties
+      FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+      WHERE Element.Id=:elementId
+        AND Scope.Id=:scopeId
+        AND Kind=:kind
+        AND Identifier=:identifier
+      LIMIT 1
+    `;
+        return dbToQuery.withPreparedStatement(sql, (statement) => {
+            statement.bindId("elementId", aspectProps.element.id);
+            if (aspectProps.scope === undefined)
+                return undefined; // return instead of binding an invalid id
+            statement.bindId("scopeId", aspectProps.scope.id);
+            statement.bindString("kind", aspectProps.kind);
+            statement.bindString("identifier", aspectProps.identifier);
+            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== statement.step())
+                return undefined;
+            const aspectId = statement.getValue(0).getId();
+            const versionValue = statement.getValue(1);
+            const version = versionValue.isNull
+                ? undefined
+                : versionValue.getString();
+            const jsonPropsValue = statement.getValue(2);
+            const jsonProperties = jsonPropsValue.isNull
+                ? undefined
+                : jsonPropsValue.getString();
+            return { aspectId, version, jsonProperties };
+        });
+    }
+    /**
+     * Determines the sync direction "forward" or "reverse" of a given sourceDb and targetDb by looking for the scoping ESA.
+     * If the sourceDb's iModelId is found as the identifier of the expected scoping ESA in the targetDb, then it is a forward synchronization.
+     * If the targetDb's iModelId is found as the identifier of the expected scoping ESA in the sourceDb, then it is a reverse synchronization.
+     * @throws if no scoping ESA can be found in either the sourceDb or targetDb which describes a master branch relationship between the two databases.
+     * @returns "forward" or "reverse"
+     */
+    static determineSyncType(sourceDb, targetDb, 
+    /** @see [[IModelTransformOptions.targetScopeElementId]] */
+    targetScopeElementId) {
+        const aspectProps = {
+            id: undefined,
+            version: undefined,
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: {
+                id: targetScopeElementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
+            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,
+        };
+        /** First check if the targetDb is the branch (branch is the @see provenanceDb) */
+        const esaPropsFromTargetDb = this.queryScopeExternalSourceAspect(targetDb, aspectProps);
+        if (esaPropsFromTargetDb !== undefined) {
+            return "forward"; // we found an esa assuming targetDb is the provenanceDb/branch so this is a forward sync.
+        }
+        // Now check if the sourceDb is the branch
+        aspectProps.identifier = targetDb.iModelId;
+        const esaPropsFromSourceDb = this.queryScopeExternalSourceAspect(sourceDb, aspectProps);
+        if (esaPropsFromSourceDb !== undefined) {
+            return "reverse"; // we found an esa assuming sourceDb is the provenanceDb/branch so this is a reverse sync.
+        }
+        throw new Error(this.noEsaSyncDirectionErrorMessage);
+    }
+    determineSyncType() {
+        if (this._isProvenanceInitTransform) {
+            return "forward";
+        }
+        if (!this._isSynchronization) {
+            return "not-sync";
+        }
+        try {
+            return IModelTransformer.determineSyncType(this.sourceDb, this.targetDb, this.targetScopeElementId);
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                err.message === IModelTransformer.noEsaSyncDirectionErrorMessage &&
+                this._allowNoScopingESA) {
+                return "forward";
+            }
+            throw err;
+        }
     }
-    get _isForwardSynchronization() {
-        return this._isSynchronization && !this._options.isReverseSynchronization;
+    get isReverseSynchronization() {
+        if (this._syncType === undefined)
+            this._syncType = this.determineSyncType();
+        return this._syncType === "reverse";
+    }
+    get isForwardSynchronization() {
+        if (this._syncType === undefined)
+            this._syncType = this.determineSyncType();
+        return this._syncType === "forward";
     }
     /** The element classes that are considered to define provenance in the iModel */
     static get provenanceElementClasses() {
-        return [core_backend_1.FolderLink, core_backend_1.SynchronizationConfigLink, core_backend_1.ExternalSource, core_backend_1.ExternalSourceAttachment];
+        return [
+            core_backend_1.FolderLink,
+            core_backend_1.SynchronizationConfigLink,
+            core_backend_1.ExternalSource,
+            core_backend_1.ExternalSourceAttachment,
+        ];
     }
     /** The element aspect classes that are considered to define provenance in the iModel */
     static get provenanceElementAspectClasses() {
@@ -124,12 +225,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         /** map of partially committed entities to their partial commit progress */
         this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
         this._isSynchronization = false;
+        /**
+         * 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.
+         * A couple ofoutdated tests run their first transform providing a source and targetdb that are slightly different which is no longer supported. In order to not remove these tests which are still providing value
+         * this private property on the IModelTransformer exists.
+         */
+        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();
-        // FIXME: add test transforming using this, then switching to new transform method
         /**
          * 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
@@ -146,7 +253,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._startingChangesetIndices = undefined;
         this._cachedSynchronizationVersion = undefined;
         this._targetClassNameToClassIdCache = new Map();
-        // if undefined, it can be initialized by calling [[this._cacheSourceChanges]]
+        // if undefined, it can be initialized by calling [[this.processChangesets]]
         this._hasElementChangedCache = undefined;
         this._deletedSourceRelationshipData = undefined;
         this._yieldManager = new core_bentley_1.YieldManager();
@@ -155,9 +262,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._longNamedSchemasMap = new Map();
         /** state to prevent reinitialization, @see [[initialize]] */
         this._initialized = false;
-        /** length === 0 when _changeDataState = "no-change", length > 0 means "has-changes", otherwise undefined  */
-        this._changeSummaryIds = undefined;
         this._sourceChangeDataState = "uninited";
+        /** length === 0 when _changeDataState = "no-change", length > 0 means "has-changes", otherwise undefined  */
+        this._csFileProps = undefined;
         /** previous provenance, either a federation guid, a `${sourceFedGuid}/${targetFedGuid}` pair, or required aspect props */
         this._lastProvenanceEntityInfo = nullLastProvenanceEntityInfo;
         // initialize IModelTransformOptions
@@ -167,9 +274,13 @@ 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",
         };
-        this._isFirstSynchronization = this._options.wasSourceIModelCopiedToTarget ? true : undefined;
+        this._isProvenanceInitTransform = this._options
+            .wasSourceIModelCopiedToTarget
+            ? true
+            : undefined;
         // initialize exporter and sourceDb
         if (source instanceof core_backend_1.IModelDb) {
             this.exporter = new IModelExporter_1.IModelExporter(source);
@@ -180,7 +291,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.sourceDb = this.exporter.sourceDb;
         this.exporter.registerHandler(this);
         this.exporter.wantGeometry = options?.loadSourceGeometry ?? false; // optimization to not load source GeometryStreams by default
-        if (!this._options.includeSourceProvenance) { // clone provenance from the source iModel into the target iModel?
+        if (!this._options.includeSourceProvenance) {
+            // clone provenance from the source iModel into the target iModel?
             IModelTransformer.provenanceElementClasses.forEach((cls) => this.exporter.excludeElementClass(cls.classFullName));
             IModelTransformer.provenanceElementAspectClasses.forEach((cls) => this.exporter.excludeElementAspectClass(cls.classFullName));
         }
@@ -188,26 +300,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.exporter.excludeElementAspectClass("BisCore:TextAnnotationData"); // This ElementAspect is auto-created by the BisCore:TextAnnotation2d/3d element handlers
         // initialize importer and targetDb
         if (target instanceof core_backend_1.IModelDb) {
-            this.importer = new IModelImporter_1.IModelImporter(target, { preserveElementIdsForFiltering: this._options.preserveElementIdsForFiltering });
+            this.importer = new IModelImporter_1.IModelImporter(target, {
+                preserveElementIdsForFiltering: this._options.preserveElementIdsForFiltering,
+                skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
+            });
         }
         else {
             this.importer = target;
-            /* eslint-disable deprecation/deprecation */
-            if (Boolean(this._options.preserveElementIdsForFiltering) !== this.importer.preserveElementIdsForFiltering) {
-                core_bentley_1.Logger.logWarning(loggerCategory, [
-                    "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.",
-                    "The custom importer target's option will be force updated to use the transformer's value.",
-                    "This behavior is deprecated and will be removed in a future version, throwing an error if they are out of sync.",
-                ].join("\n"));
-                this.importer.preserveElementIdsForFiltering = Boolean(this._options.preserveElementIdsForFiltering);
-            }
-            /* eslint-enable deprecation/deprecation */
+            this.validateSharedOptionsMatch();
         }
         this.targetDb = this.importer.targetDb;
         // create the IModelCloneContext, it must be initialized later
         this.context = new IModelCloneContext_1.IModelCloneContext(this.sourceDb, this.targetDb);
         if (this.sourceDb.isBriefcase && this.targetDb.isBriefcase) {
-            nodeAssert(this.sourceDb.changeset.index !== undefined && this.targetDb.changeset.index !== undefined, "database has no changeset index");
+            nodeAssert(this.sourceDb.changeset.index !== undefined &&
+                this.targetDb.changeset.index !== undefined, "database has no changeset index");
             this._startingChangesetIndices = {
                 target: this.targetDb.changeset.index,
                 source: this.sourceDb.changeset.index,
@@ -215,12 +322,27 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         // this internal is guaranteed stable for just transformer usage
         /* eslint-disable @itwin/no-internal */
-        if ("codeValueBehavior" in this.sourceDb) {
+        if (("codeValueBehavior" in this.sourceDb)) {
             this.sourceDb.codeValueBehavior = "exact";
             this.targetDb.codeValueBehavior = "exact";
         }
         /* eslint-enable @itwin/no-internal */
     }
+    /** validates that the importer set on the transformer has the same values for its shared options as the transformer.
+     *  @note This expects that the importer is already set on the transformer.
+     */
+    validateSharedOptionsMatch() {
+        if (Boolean(this._options.preserveElementIdsForFiltering) !==
+            this.importer.options.preserveElementIdsForFiltering) {
+            const errMessage = "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.";
+            throw new Error(errMessage);
+        }
+        if (Boolean(this._options.skipPropagateChangesToRootElements) !==
+            this.importer.options.skipPropagateChangesToRootElements) {
+            const errMessage = "A custom importer was passed as a target but its 'skipPropagateChangesToRootElements' option is out of sync with the transformer's option.";
+            throw new Error(errMessage);
+        }
+    }
     /** Dispose any native resources associated with this IModelTransformer. */
     dispose() {
         core_bentley_1.Logger.logTrace(loggerCategory, "dispose()");
@@ -238,32 +360,41 @@ 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(loggerCategory, 
+        // eslint-disable-next-line deprecation/deprecation
+        `this._isReverseSynchronization=${this._options.isReverseSynchronization}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.autoExtendProjectExtents=${JSON.stringify(this.importer.options.autoExtendProjectExtents)}`);
         core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.simplifyElementGeometry=${this.importer.options.simplifyElementGeometry}`);
     }
     /** Return the IModelDb where IModelTransformer will store its provenance.
      * @note This will be [[targetDb]] except when it is a reverse synchronization. In that case it be [[sourceDb]].
      */
     get provenanceDb() {
-        return this._options.isReverseSynchronization ? this.sourceDb : this.targetDb;
+        return this.isReverseSynchronization ? this.sourceDb : this.targetDb;
     }
     /** Return the IModelDb where IModelTransformer looks for entities referred to by stored provenance.
      * @note This will be [[sourceDb]] except when it is a reverse synchronization. In that case it be [[targetDb]].
      */
     get provenanceSourceDb() {
-        return this._options.isReverseSynchronization ? this.targetDb : this.sourceDb;
+        return this.isReverseSynchronization ? this.targetDb : this.sourceDb;
     }
     /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
     static initElementProvenanceOptions(sourceElementId, targetElementId, args) {
-        const elementId = args.isReverseSynchronization ? sourceElementId : targetElementId;
+        const elementId = args.isReverseSynchronization
+            ? sourceElementId
+            : targetElementId;
         const version = args.isReverseSynchronization
             ? args.targetDb.elements.queryLastModifiedTime(targetElementId)
             : args.sourceDb.elements.queryLastModifiedTime(sourceElementId);
-        const aspectIdentifier = args.isReverseSynchronization ? targetElementId : sourceElementId;
+        const aspectIdentifier = args.isReverseSynchronization
+            ? targetElementId
+            : sourceElementId;
         const aspectProps = {
             classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: { id: elementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
+            element: {
+                id: elementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
             scope: { id: args.targetScopeElementId },
             identifier: aspectIdentifier,
             kind: core_backend_1.ExternalSourceAspect.Kind.Element,
@@ -272,9 +403,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         return aspectProps;
     }
     static initRelationshipProvenanceOptions(sourceRelInstanceId, targetRelInstanceId, args) {
-        const provenanceDb = args.isReverseSynchronization ? args.sourceDb : args.targetDb;
-        const aspectIdentifier = args.isReverseSynchronization ? targetRelInstanceId : sourceRelInstanceId;
-        const provenanceRelInstanceId = args.isReverseSynchronization ? sourceRelInstanceId : targetRelInstanceId;
+        const provenanceDb = args.isReverseSynchronization
+            ? args.sourceDb
+            : args.targetDb;
+        const aspectIdentifier = args.isReverseSynchronization
+            ? targetRelInstanceId
+            : sourceRelInstanceId;
+        const provenanceRelInstanceId = args.isReverseSynchronization
+            ? sourceRelInstanceId
+            : targetRelInstanceId;
         const elementId = provenanceDb.withPreparedStatement("SELECT SourceECInstanceId FROM bis.ElementRefersToElements WHERE ECInstanceId=?", (stmt) => {
             stmt.bindId(1, provenanceRelInstanceId);
             nodeAssert(stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW);
@@ -285,7 +422,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             : { provenanceRelInstanceId };
         const aspectProps = {
             classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: { id: elementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
+            element: {
+                id: elementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
             scope: { id: args.targetScopeElementId },
             identifier: aspectIdentifier,
             kind: core_backend_1.ExternalSourceAspect.Kind.Relationship,
@@ -296,7 +436,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
     initElementProvenance(sourceElementId, targetElementId) {
         return IModelTransformer.initElementProvenanceOptions(sourceElementId, targetElementId, {
-            isReverseSynchronization: !!this._options.isReverseSynchronization,
+            isReverseSynchronization: this.isReverseSynchronization,
             targetScopeElementId: this.targetScopeElementId,
             sourceDb: this.sourceDb,
             targetDb: this.targetDb,
@@ -311,36 +451,35 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         return IModelTransformer.initRelationshipProvenanceOptions(sourceRelationship.id, targetRelInstanceId, {
             sourceDb: this.sourceDb,
             targetDb: this.targetDb,
-            isReverseSynchronization: !!this._options.isReverseSynchronization,
+            isReverseSynchronization: this.isReverseSynchronization,
             targetScopeElementId: this.targetScopeElementId,
             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._options.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) {
@@ -348,13 +487,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (!provenanceScopeAspect) {
                 return { index: -1, id: "" }; // first synchronization.
             }
-            const version = this._options.isReverseSynchronization
+            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.
@@ -366,15 +510,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
      */
     tryGetProvenanceScopeAspect() {
-        const scopeProvenanceAspectId = this.queryScopeExternalSource({
+        const scopeProvenanceAspectProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, {
+            id: undefined,
             classFullName: core_backend_1.ExternalSourceAspect.classFullName,
             scope: { id: core_common_1.IModel.rootSubjectId },
             kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
             element: { id: this.targetScopeElementId ?? core_common_1.IModel.rootSubjectId },
             identifier: this.provenanceSourceDb.iModelId,
         });
-        return scopeProvenanceAspectId.aspectId
-            ? this.provenanceDb.elements.getAspect(scopeProvenanceAspectId.aspectId)
+        return scopeProvenanceAspectProps !== undefined
+            ? this.provenanceDb.elements.getAspect(scopeProvenanceAspectProps.aspectId)
             : undefined;
     }
     /**
@@ -388,19 +533,17 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             id: undefined,
             version: undefined,
             classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: { id: this.targetScopeElementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
-            scope: { id: core_common_1.IModel.rootSubjectId },
+            element: {
+                id: this.targetScopeElementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
+            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,
         };
-        // FIXME: handle older transformed iModels which do NOT have the version. Add test where we don't set those and then start setting them.
-        // or reverseSyncVersion set correctly
-        const externalSource = this.queryScopeExternalSource(aspectProps, { getJsonProperties: true }); // this query includes "identifier"
-        aspectProps.id = externalSource.aspectId;
-        aspectProps.version = externalSource.version;
-        aspectProps.jsonProperties = externalSource.jsonProperties ? JSON.parse(externalSource.jsonProperties) : {};
-        if (undefined === aspectProps.id) {
+        const foundEsaProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, aspectProps); // this query includes "identifier"
+        if (foundEsaProps === undefined) {
             aspectProps.version = ""; // empty since never before transformed. Will be updated in [[finalizeTransformation]]
             aspectProps.jsonProperties = {
                 pendingReverseSyncChangesetIndices: [],
@@ -426,44 +569,85 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Provenance scope conflict");
             }
             if (!this._options.noProvenance) {
-                this.provenanceDb.elements.insertAspect({
+                const id = this.provenanceDb.elements.insertAspect({
                     ...aspectProps,
                     jsonProperties: JSON.stringify(aspectProps.jsonProperties),
                 });
+                aspectProps.id = id;
+                // Busting a potential cached version
+                this.clearCachedSynchronizationVersion();
             }
         }
-        this._targetScopeProvenanceProps = aspectProps;
-    }
-    /**
-     * @returns the id and version of an aspect with the given element, scope, kind, and identifier
-     * May also return a reverseSyncVersion from json properties if requested
-     */
-    queryScopeExternalSource(aspectProps, { getJsonProperties = false } = {}) {
-        const sql = `
-      SELECT ECInstanceId, Version
-      ${getJsonProperties ? ", JsonProperties" : ""}
-      FROM ${core_backend_1.ExternalSourceAspect.classFullName}
-      WHERE Element.Id=:elementId
-        AND Scope.Id=:scopeId
-        AND Kind=:kind
-        AND Identifier=:identifier
-      LIMIT 1
-    `;
-        const emptyResult = { aspectId: undefined, version: undefined, jsonProperties: undefined };
-        return this.provenanceDb.withPreparedStatement(sql, (statement) => {
-            statement.bindId("elementId", aspectProps.element.id);
-            if (aspectProps.scope === undefined)
-                return emptyResult; // return undefined instead of binding an invalid id
-            statement.bindId("scopeId", aspectProps.scope.id);
-            statement.bindString("kind", aspectProps.kind);
-            statement.bindString("identifier", aspectProps.identifier);
-            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== statement.step())
-                return emptyResult;
-            const aspectId = statement.getValue(0).getId();
-            const version = statement.getValue(1).getString();
-            const jsonProperties = getJsonProperties ? statement.getValue(2).getString() : undefined;
-            return { aspectId, version, jsonProperties };
-        });
+        else {
+            // foundEsaProps is defined.
+            aspectProps.id = foundEsaProps.aspectId;
+            aspectProps.version = foundEsaProps.version;
+            aspectProps.jsonProperties = foundEsaProps.jsonProperties
+                ? JSON.parse(foundEsaProps.jsonProperties)
+                : 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.unsafeFallbackSyncVersion ?? "";
+        const fallbackReverseSyncVersionToUse = this._options.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)
@@ -477,13 +661,19 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (!args.provenanceDb.containsClass(core_backend_1.ExternalSourceAspect.classFullName)) {
             throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadSchema, "The BisCore schema version of the target database is too old");
         }
-        const sourceDb = args.isReverseSynchronization ? args.provenanceDb : args.provenanceSourceDb;
-        const targetDb = args.isReverseSynchronization ? args.provenanceSourceDb : args.provenanceDb;
+        const sourceDb = args.isReverseSynchronization
+            ? args.provenanceDb
+            : args.provenanceSourceDb;
+        const targetDb = args.isReverseSynchronization
+            ? args.provenanceSourceDb
+            : args.provenanceDb;
         // query for provenanceDb
         const elementIdByFedGuidQuery = `
       SELECT e.ECInstanceId, FederationGuid
       FROM bis.Element e
-      WHERE e.ECInstanceId NOT IN (0x1, 0xe, 0x10) -- special static elements
+      ${args.skipPropagateChangesToRootElements
+            ? "WHERE e.ECInstanceId NOT IN (0x1, 0xe, 0x10) -- special static elements"
+            : ""}
       ORDER BY FederationGuid
     `;
         // iterate through sorted list of fed guids from both dbs to get the intersection
@@ -501,22 +691,22 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             // and the fact that '0' < '9' < a' < 'f' in ascii/utf8
             while (true) {
                 const currSourceRow = sourceRow, currTargetRow = targetRow;
-                if (currSourceRow.federationGuid !== undefined
-                    && currTargetRow.federationGuid !== undefined
-                    && currSourceRow.federationGuid === currTargetRow.federationGuid) {
+                if (currSourceRow.federationGuid !== undefined &&
+                    currTargetRow.federationGuid !== undefined &&
+                    currSourceRow.federationGuid === currTargetRow.federationGuid) {
                     // data flow direction is always sourceDb -> targetDb and it does not depend on where the explicit element provenance is stored
                     args.fn(sourceRow.id, targetRow.id);
                 }
-                if (currTargetRow.federationGuid === undefined
-                    || (currSourceRow.federationGuid !== undefined
-                        && currSourceRow.federationGuid >= currTargetRow.federationGuid)) {
+                if (currTargetRow.federationGuid === undefined ||
+                    (currSourceRow.federationGuid !== undefined &&
+                        currSourceRow.federationGuid >= currTargetRow.federationGuid)) {
                     if (targetStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
                         return;
                     targetRow = targetStmt.getRow();
                 }
-                if (currSourceRow.federationGuid === undefined
-                    || (currTargetRow.federationGuid !== undefined
-                        && currSourceRow.federationGuid <= currTargetRow.federationGuid)) {
+                if (currSourceRow.federationGuid === undefined ||
+                    (currTargetRow.federationGuid !== undefined &&
+                        currSourceRow.federationGuid <= currTargetRow.federationGuid)) {
                     if (sourceStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
                         return;
                     sourceRow = sourceStmt.getRow();
@@ -534,7 +724,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         // victims of the old provenance method that have both fedguids and an inserted aspect.
         // But this is a private function with one known caller where that doesn't matter
         args.provenanceDb.withPreparedStatement(provenanceAspectsQuery, (stmt) => {
-            const runFnInDataFlowDirection = (sourceId, targetId) => args.isReverseSynchronization ? args.fn(sourceId, targetId) : args.fn(targetId, sourceId);
+            const runFnInDataFlowDirection = (sourceId, targetId) => args.isReverseSynchronization
+                ? args.fn(sourceId, targetId)
+                : args.fn(targetId, sourceId);
             stmt.bindId("scopeId", args.targetScopeElementId);
             stmt.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
             while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
@@ -550,240 +742,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             provenanceSourceDb: this.provenanceSourceDb,
             provenanceDb: this.provenanceDb,
             targetScopeElementId: this.targetScopeElementId,
-            isReverseSynchronization: !!this._options.isReverseSynchronization,
+            isReverseSynchronization: this.isReverseSynchronization,
             fn,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
         });
     }
-    /** Initialize the source to target Element mapping from ExternalSourceAspects in the target iModel.
-     * @note This method is called from all `process*` functions and should never need to be called directly.
-     * @deprecated in 3.x. call [[initialize]] instead, it does the same thing among other initialization
-     * @note Passing an [[InitFromExternalSourceAspectsArgs]] is required when processing changes, to remap any elements that may have been deleted.
-     *       You must await the returned promise as well in this case. The synchronous behavior has not changed but is deprecated and won't process everything.
-     */
-    initFromExternalSourceAspects(args) {
-        this.forEachTrackedElement((sourceElementId, targetElementId) => {
-            this.context.remapElement(sourceElementId, targetElementId);
-        });
-        if (args)
-            return this.remapDeletedSourceEntities();
-    }
     /**
-     * Scan changesets for deleted entities, if in a reverse synchronization, provenance has
-     * already been deleted, so we must scan for that as well.
+     * 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
      */
-    async remapDeletedSourceEntities() {
-        // 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;
-        if (notConnectedModel || noChanges)
-            return;
-        this._deletedSourceRelationshipData = new Map();
-        nodeAssert(this._changeSummaryIds, "change summaries should be initialized before we get here");
-        if (this._changeSummaryIds.length === 0)
-            return;
-        const alreadyImportedElementInserts = new Set();
-        const alreadyImportedModelInserts = new Set();
-        this.exporter.sourceDbChanges?.element.insertIds.forEach((insertedSourceElementId) => {
-            const targetElementId = this.context.findTargetElementId(insertedSourceElementId);
-            if (core_bentley_1.Id64.isValid(targetElementId))
-                alreadyImportedElementInserts.add(targetElementId);
-        });
-        this.exporter.sourceDbChanges?.model.insertIds.forEach((insertedSourceModelId) => {
-            const targetModelId = this.context.findTargetElementId(insertedSourceModelId);
-            if (core_bentley_1.Id64.isValid(targetModelId))
-                alreadyImportedModelInserts.add(targetModelId);
-        });
-        // 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 deletedEntitySql = `
-      SELECT
-        1 AS IsElemNotRel,
-        ic.ChangedInstance.Id AS InstanceId,
-        NULL AS InstId2, -- need these columns for relationship ends in the unioned query
-        NULL AS InstId3,
-        ec.FederationGuid AS FedGuid,
-        NULL AS FedGuid2,
-        ic.ChangedInstance.ClassId AS ClassId
-        ${queryCanAccessProvenance ? `
-        /*
-        -- can't coalesce these due to a bug, so do it in JS
-        , coalesce(
-            IIF(esa.Scope.Id=:targetScopeElement, esa.Identifier, NULL),
-            IIF(esac.Scope.Id=:targetScopeElement, esac.Identifier, NULL)
-          ) AS Identifier1
-        */
-        , CASE WHEN esa.Scope.Id = ${this.targetScopeElementId} THEN esa.Identifier ELSE NULL END AS Identifier1A
-        -- FIXME: using :targetScopeElement parameter in this second potential identifier breaks ecsql
-        , CASE WHEN esac.Scope.Id = ${this.targetScopeElementId} THEN esac.Identifier ELSE NULL END AS Identifier1B
-        , NULL AS Identifier2A
-        , NULL AS Identifier2B
-        ` : ""}
-      FROM ecchange.change.InstanceChange ic
-        LEFT JOIN bis.Element.Changes(:changeSummaryId, 'BeforeDelete') ec
-          ON ic.ChangedInstance.Id=ec.ECInstanceId
-        ${queryCanAccessProvenance ? `
-          LEFT JOIN bis.ExternalSourceAspect esa
-            ON ec.ECInstanceId=esa.Element.Id
-          LEFT JOIN bis.ExternalSourceAspect.Changes(:changeSummaryId, 'BeforeDelete') esac
-            ON ec.ECInstanceId=esac.Element.Id
-        ` : ""}
-      WHERE ic.OpCode=:opDelete
-        AND ic.Summary.Id=:changeSummaryId
-        AND ic.ChangedInstance.ClassId IS (BisCore.Element)
-
-      UNION ALL
-
-      SELECT
-        0 AS IsElemNotRel,
-        ic.ChangedInstance.Id AS InstanceId,
-        coalesce(se.ECInstanceId, sec.ECInstanceId) AS InstId2,
-        coalesce(te.ECInstanceId, tec.ECInstanceId) AS InstId3,
-        coalesce(se.FederationGuid, sec.FederationGuid) AS FedGuid1,
-        coalesce(te.FederationGuid, tec.FederationGuid) AS FedGuid2,
-        ic.ChangedInstance.ClassId AS ClassId
-        ${queryCanAccessProvenance ? `
-        , sesa.Identifier AS Identifier1A
-        , sesac.Identifier AS Identifier1B
-        , tesa.Identifier AS Identifier2A
-        , tesac.Identifier AS Identifier2B
-        ` : ""}
-      FROM ecchange.change.InstanceChange ic
-        LEFT JOIN bis.ElementRefersToElements.Changes(:changeSummaryId, 'BeforeDelete') ertec
-          ON ic.ChangedInstance.Id=ertec.ECInstanceId
-        -- FIXME: test a deletion of both an element and a relationship at the same time
-        LEFT JOIN bis.Element se
-          ON se.ECInstanceId=ertec.SourceECInstanceId
-        LEFT JOIN bis.Element te
-          ON te.ECInstanceId=ertec.TargetECInstanceId
-        LEFT JOIN bis.Element.Changes(:changeSummaryId, 'BeforeDelete') sec
-          ON sec.ECInstanceId=ertec.SourceECInstanceId
-        LEFT JOIN bis.Element.Changes(:changeSummaryId, 'BeforeDelete') tec
-          ON tec.ECInstanceId=ertec.TargetECInstanceId
-        ${queryCanAccessProvenance ? `
-          -- NOTE: need to join on both se/te and sec/tec incase the element was deleted
-          LEFT JOIN bis.ExternalSourceAspect sesa
-            ON se.ECInstanceId=sesa.Element.Id -- don't use *esac*.Identifier because it's a string
-          LEFT JOIN bis.ExternalSourceAspect.Changes(:changeSummaryId, 'BeforeDelete') sesac
-            ON sec.ECInstanceId=sesac.Element.Id
-          LEFT JOIN bis.ExternalSourceAspect tesa
-            ON te.ECInstanceId=tesa.Element.Id
-          LEFT JOIN bis.ExternalSourceAspect.Changes(:changeSummaryId, 'BeforeDelete') tesac
-            ON tec.ECInstanceId=tesac.Element.Id
-          ` : ""}
-      WHERE ic.OpCode=:opDelete
-        AND ic.Summary.Id=:changeSummaryId
-        AND ic.ChangedInstance.ClassId IS (BisCore.ElementRefersToElements)
-        ${queryCanAccessProvenance ? `
-          AND (sesa.Scope.Id=:targetScopeElement OR sesa.Scope.Id IS NULL)
-          AND (sesa.Kind='Relationship' OR sesa.Kind IS NULL)
-          AND (sesac.Scope.Id=:targetScopeElement OR sesac.Scope.Id IS NULL)
-          AND (sesac.Kind='Relationship' OR sesac.Kind IS NULL)
-          AND (tesa.Scope.Id=:targetScopeElement OR tesa.Scope.Id IS NULL)
-          AND (tesa.Kind='Relationship' OR tesa.Kind IS NULL)
-          AND (tesac.Scope.Id=:targetScopeElement OR tesac.Scope.Id IS NULL)
-          AND (tesac.Kind='Relationship' OR tesac.Kind IS NULL)
-          ` : ""}
-    `;
-        for (const changeSummaryId of this._changeSummaryIds) {
-            this.sourceDb.withPreparedStatement(deletedEntitySql, (stmt) => {
-                stmt.bindInteger("opDelete", core_common_1.ChangeOpCode.Delete);
-                if (queryCanAccessProvenance)
-                    stmt.bindId("targetScopeElement", this.targetScopeElementId);
-                stmt.bindId("changeSummaryId", changeSummaryId);
-                while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
-                    const isElemNotRel = stmt.getValue(0).getBoolean();
-                    const instId = stmt.getValue(1).getId();
-                    if (isElemNotRel) {
-                        const sourceElemFedGuid = stmt.getValue(4).getGuid();
-                        // "Identifier" is a string, so null value returns '' which doesn't work with ??, and I don't like ||
-                        let identifierValue;
-                        // identifier must be coalesced in JS due to an ESCQL bug, so there are multiple columns
-                        if (queryCanAccessProvenance) {
-                            identifierValue = stmt.getValue(7);
-                            if (identifierValue.isNull)
-                                identifierValue = stmt.getValue(8);
-                        }
-                        // TODO: if I could attach the second db, will probably be much faster to get target id
-                        // as part of the whole query rather than with _queryElemIdByFedGuid
-                        const targetId = (queryCanAccessProvenance && identifierValue
-                            && !identifierValue.isNull
-                            && identifierValue.getString())
-                            // 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)
-                            continue;
-                        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);
-                        }
-                        if (alreadyImportedModelInserts.has(targetId)) {
-                            this.exporter.sourceDbChanges?.model.deleteIds.delete(instId);
-                        }
-                    }
-                    else { // is deleted relationship
-                        const classFullName = stmt.getValue(6).getClassNameForClassId();
-                        const [sourceIdInTarget, targetIdInTarget] = [
-                            // identifier must be coalesced in JS due to an ESCQL bug, so there are multiple columns
-                            { guidColumn: 4, identifierColumns: { a: 7, b: 8 }, isTarget: false },
-                            { guidColumn: 5, identifierColumns: { a: 9, b: 10 }, isTarget: true },
-                        ].map(({ guidColumn, identifierColumns }) => {
-                            const fedGuid = stmt.getValue(guidColumn).getGuid();
-                            let identifierValue;
-                            // identifier must be coalesced in JS due to an ESCQL bug, so there are multiple columns
-                            if (queryCanAccessProvenance) {
-                                identifierValue = stmt.getValue(identifierColumns.a);
-                                if (identifierValue.isNull)
-                                    identifierValue = stmt.getValue(identifierColumns.b);
-                            }
-                            return ((queryCanAccessProvenance && identifierValue
-                                // FIXME: this is really far from idiomatic, try to undo that
-                                && !identifierValue.isNull
-                                && identifierValue.getString())
-                                // 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)));
-                        });
-                        // 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
-                        if (sourceIdInTarget && targetIdInTarget) {
-                            this._deletedSourceRelationshipData.set(instId, {
-                                classFullName,
-                                sourceIdInTarget,
-                                targetIdInTarget,
-                            });
-                        }
-                        else {
-                            // FIXME<MIKE>: describe why it's safe to assume nothing has been deleted in provenanceDb
-                            const relProvenance = this._queryProvenanceForRelationship(instId, {
-                                classFullName,
-                                sourceId: stmt.getValue(2).getId(),
-                                targetId: stmt.getValue(3).getId(),
-                            });
-                            if (relProvenance && relProvenance.relationshipId)
-                                this._deletedSourceRelationshipData.set(instId, {
-                                    classFullName,
-                                    relId: relProvenance.relationshipId,
-                                    provenanceAspectId: relProvenance.aspectId,
-                                });
-                        }
-                    }
-                }
-                // NEXT: remap sourceId and targetId to target, get provenance there
-                // NOTE: it is possible during a forward sync for the target to already have deleted
-                // something that the source deleted, in which case we can safely ignore the gone provenance
-            });
-        }
-    }
     _queryProvenanceForElement(entityInProvenanceSourceId) {
         return this.provenanceDb.withPreparedStatement(`
         SELECT esa.Element.Id
@@ -801,6 +771,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
@@ -833,7 +810,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             sourceId: this.context.findTargetElementId(sourceRelInfo.sourceId),
             targetId: this.context.findTargetElementId(sourceRelInfo.targetId),
         };
-        if (targetRelInfo.sourceId === undefined || targetRelInfo.targetId === undefined)
+        if (targetRelInfo.sourceId === undefined ||
+            targetRelInfo.targetId === undefined)
             return undefined; // couldn't find an element, rel is invalid or deleted
         return this.targetDb.withPreparedStatement(`
       SELECT ECInstanceId
@@ -867,7 +845,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
       JOIN ECDbMeta.ECSchemaDef s ON c.Schema.Id=s.ECInstanceId
       WHERE s.Name=? AND c.Name=?
     `, (stmt) => {
-            const [schemaName, className] = classFullName.split(".");
+            const [schemaName, className] = classFullName.indexOf(".") !== -1
+                ? classFullName.split(".")
+                : classFullName.split(":");
             stmt.bindString(1, schemaName);
             stmt.bindString(2, className);
             if (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW)
@@ -885,26 +865,19 @@ 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.
      */
     shouldDetectDeletes() {
-        // FIXME: all synchronizations should mark this as false, but we can probably change this
-        // to just follow the new deprecated option
-        if (this._isFirstSynchronization)
-            return false; // not necessary the first time since there are no deletes to detect
-        if (this._options.isReverseSynchronization)
-            return false; // not possible for a reverse synchronization since provenance will be deleted when element is deleted
-        // FIXME: do any tests fail? if not, consider using @see _isSynchronization
-        if (this._isForwardSynchronization)
-            return false; // not possible for a reverse synchronization since provenance will be deleted when element is deleted
-        return true;
+        nodeAssert(this._syncType !== undefined);
+        return this._syncType === "not-sync";
     }
     /**
      * 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
-     * [[IModelTransformerOptions.forceExternalSourceAspectProvenance]] is enabled. It is not
+     * [[IModelTransformOptions.forceExternalSourceAspectProvenance]] is enabled. It is not
      * necessary when using [[processChanges]] 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.
@@ -916,18 +889,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
       WHERE Scope.Id=:scopeId
         AND Kind=:kind
     `;
-        nodeAssert(!this._options.isReverseSynchronization, "synchronizations with processChanges already detect element deletes, don't call detectElementDeletes");
+        nodeAssert(!this.isReverseSynchronization, "synchronizations with processChanges already detect element deletes, don't call detectElementDeletes");
         this.provenanceDb.withPreparedStatement(sql, (stmt) => {
             stmt.bindId("scopeId", this.targetScopeElementId);
             stmt.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
             while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
                 // ExternalSourceAspect.Identifier is of type string
                 const aspectIdentifier = stmt.getValue(0).getString();
-                if (!core_bentley_1.Id64.isId64(aspectIdentifier)) {
+                if (!core_bentley_1.Id64.isValidId64(aspectIdentifier)) {
                     continue;
                 }
                 const targetElemId = stmt.getValue(1).getId();
-                const wasDeletedInSource = !EntityUnifier_1.EntityUnifier.exists(this.sourceDb, { entityReference: `e${aspectIdentifier}` });
+                const wasDeletedInSource = !EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
+                    entityReference: `e${aspectIdentifier}`,
+                });
                 if (wasDeletedInSource)
                     this.importer.deleteElement(targetElemId);
             }
@@ -937,7 +912,7 @@ 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`);
+        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.
@@ -948,6 +923,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)
@@ -956,52 +945,17 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         return targetElementProps;
     }
-    // TODO: this is a PoC, see if we minimize memory usage
-    _cacheSourceChanges() {
-        nodeAssert(this._changeSummaryIds && this._changeSummaryIds.length > 0, "should have changeset data by now");
-        this._hasElementChangedCache = new Set();
-        const query = `
-      SELECT
-        ic.ChangedInstance.Id AS InstId
-      FROM ecchange.change.InstanceChange ic
-      JOIN iModelChange.Changeset imc ON ic.Summary.Id=imc.Summary.Id
-      -- TODO: do relationship entities also need this cache optimization?
-      WHERE ic.ChangedInstance.ClassId IS (BisCore.Element)
-        AND InVirtualSet(:changeSummaryIds, ic.Summary.Id)
-        -- ignore deleted, we take care of those in remapDeletedSourceEntities
-        -- include inserted since inserted code-colliding elements should be considered
-        -- a change so that the colliding element is exported to the target
-        AND ic.OpCode<>:opDelete
-    `;
-        // there is a single mega-query multi-join+coalescing hack that I used originally to get around
-        // only being able to run table.Changes() on one changeset at once, but sqlite only supports up to 64
-        // tables in a join. Need to talk to core about .Changes being able to take a set of changesets
-        // You can find this version in the `federation-guid-optimization-megaquery` branch
-        // I wouldn't use it unless we prove via profiling that it speeds things up significantly
-        // And even then let's first try scanning the raw changesets instead of applying them as these queries
-        // require
-        this.sourceDb.withPreparedStatement(query, (stmt) => {
-            stmt.bindInteger("opDelete", core_common_1.ChangeOpCode.Delete);
-            stmt.bindIdSet("changeSummaryIds", this._changeSummaryIds);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
-                const instId = stmt.getValue(0).getId();
-                this._hasElementChangedCache.add(instId);
-            }
-        });
-    }
     /** 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) {
+    hasElementChanged(sourceElement) {
         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");
-        if (this._hasElementChangedCache === undefined)
-            this._cacheSourceChanges();
+        nodeAssert(this._hasElementChangedCache !== undefined, "has element changed cache should be initialized by now");
         return this._hasElementChangedCache.has(sourceElement.id);
     }
     static transformCallbackFor(transformer, entity) {
@@ -1028,8 +982,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             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);
+                targetProps.sourceId =
+                    this.context.findTargetElementId(sourceEntity.sourceId);
+                targetProps.targetId =
+                    this.context.findTargetElementId(sourceEntity.targetId);
             }
             updateEntity({ ...targetProps, id: core_backend_1.EntityReferences.toId64(targetId) });
             this._partiallyCommittedEntities.delete(sourceEntity);
@@ -1045,11 +1001,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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);
+            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 });
+            const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
+                entityReference: referenceId,
+            });
             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) {
@@ -1059,7 +1018,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                         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 IModelTransformerOptions.danglingReferencesBehavior option to 'ignore' to ignore this, but this will leave 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"));
@@ -1097,7 +1056,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Override of [IModelExportHandler.shouldExportElement]($transformer) that is called to determine if an element should be exported from the source iModel.
      * @note Reaching this point means that the element has passed the standard exclusion checks in IModelExporter.
      */
-    shouldExportElement(_sourceElement) { return true; }
+    shouldExportElement(_sourceElement) {
+        return true;
+    }
     onSkipElement(sourceElementId) {
         if (this.context.findTargetElementId(sourceElementId) !== core_bentley_1.Id64.invalid) {
             // element already has provenance
@@ -1128,7 +1089,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             const referenceType = elemClass.requiredReferenceKeyTypeMap[referenceKey];
             // For now we just consider all required references to be elements (as they are in biscore), and do not support
             // entities that refuse to be inserted without a different kind of entity (e.g. aspect or relationship) first being inserted
-            (0, core_bentley_1.assert)(referenceType === core_common_1.ConcreteEntityTypes.Element || referenceType === core_common_1.ConcreteEntityTypes.Model);
+            (0, core_bentley_1.assert)(referenceType === core_common_1.ConcreteEntityTypes.Element ||
+                referenceType === core_common_1.ConcreteEntityTypes.Model);
             return mapId64(idContainer, (id) => {
                 if (id === core_bentley_1.Id64.invalid || id === core_common_1.IModel.rootSubjectId)
                     return undefined; // not allowed to directly export the root subject
@@ -1137,13 +1099,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     // This is relied upon by the TemplateModelCloner
                     // TODO: extract this out to only be in the TemplateModelCloner
                     const asDefinitionElem = this.sourceDb.elements.tryGetElement(id, core_backend_1.DefinitionElement);
-                    if (asDefinitionElem && !(asDefinitionElem instanceof core_backend_1.RecipeDefinitionElement)) {
+                    if (asDefinitionElem &&
+                        !(asDefinitionElem instanceof core_backend_1.RecipeDefinitionElement)) {
                         this.context.remapElement(id, id);
                     }
                 }
                 return id;
-            })
-                .filter((sourceReferenceId) => {
+            }).filter((sourceReferenceId) => {
                 if (sourceReferenceId === undefined)
                     return false;
                 const referenceInTargetId = this.context.findTargetElementId(sourceReferenceId);
@@ -1171,7 +1133,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const isSubModeled = dbHasModel(this.sourceDb, elementId);
         const idOfElemInTarget = this.context.findTargetElementId(elementId);
         const isElemInTarget = core_bentley_1.Id64.invalid !== idOfElemInTarget;
-        const needsModelImport = isSubModeled && (!isElemInTarget || !dbHasModel(this.targetDb, idOfElemInTarget));
+        const needsModelImport = isSubModeled &&
+            (!isElemInTarget || !dbHasModel(this.targetDb, idOfElemInTarget));
         return { needsElemImport: !isElemInTarget, needsModelImport };
     }
     /** Override of [IModelExportHandler.onExportElement]($transformer) that imports an element into the target iModel when it is exported from the source iModel.
@@ -1186,27 +1149,33 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         else if (this._options.wasSourceIModelCopiedToTarget) {
             targetElementId = sourceElement.id;
-            targetElementProps = this.targetDb.elements.getElementProps(targetElementId);
+            targetElementProps =
+                this.targetDb.elements.getElementProps(targetElementId);
         }
         else {
             targetElementId = this.context.findTargetElementId(sourceElement.id);
             targetElementProps = this.onTransformElement(sourceElement);
         }
         // if an existing remapping was not yet found, check by FederationGuid
-        if (this.context.isBetweenIModels && !core_bentley_1.Id64.isValid(targetElementId) && sourceElement.federationGuid !== undefined) {
-            targetElementId = this._queryElemIdByFedGuid(this.targetDb, sourceElement.federationGuid) ?? core_bentley_1.Id64.invalid;
+        if (this.context.isBetweenIModels &&
+            !core_bentley_1.Id64.isValid(targetElementId) &&
+            sourceElement.federationGuid !== undefined) {
+            targetElementId =
+                this._queryElemIdByFedGuid(this.targetDb, sourceElement.federationGuid) ?? core_bentley_1.Id64.invalid;
             if (core_bentley_1.Id64.isValid(targetElementId))
                 this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found
         }
         // if an existing remapping was not yet found, check by Code as long as the CodeScope is valid (invalid means a missing reference so not worth checking)
-        if (!core_bentley_1.Id64.isValidId64(targetElementId) && core_bentley_1.Id64.isValidId64(targetElementProps.code.scope)) {
+        if (!core_bentley_1.Id64.isValidId64(targetElementId) &&
+            core_bentley_1.Id64.isValidId64(targetElementProps.code.scope)) {
             // respond the same way to undefined code value as the @see Code class, but don't use that class because it trims
             // whitespace from the value, and there are iModels out there with untrimmed whitespace that we ought not to trim
             targetElementProps.code.value = targetElementProps.code.value ?? "";
             const maybeTargetElementId = this.targetDb.elements.queryElementIdByCode(targetElementProps.code);
             if (undefined !== maybeTargetElementId) {
                 const maybeTargetElem = this.targetDb.elements.getElement(maybeTargetElementId);
-                if (maybeTargetElem.classFullName === targetElementProps.classFullName) { // ensure code remapping doesn't change the target class
+                if (maybeTargetElem.classFullName === targetElementProps.classFullName) {
+                    // ensure code remapping doesn't change the target class
                     targetElementId = maybeTargetElementId;
                     this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found by Code
                 }
@@ -1215,14 +1184,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 }
             }
         }
-        if (core_bentley_1.Id64.isValid(targetElementId) && !this.hasElementChanged(sourceElement, targetElementId))
+        if (!this.hasElementChanged(sourceElement))
             return;
         this.collectUnmappedReferences(sourceElement);
         // targetElementId will be valid (indicating update) or undefined (indicating insert)
-        targetElementProps.id
-            = core_bentley_1.Id64.isValid(targetElementId)
-                ? targetElementId
-                : undefined;
+        targetElementProps.id = core_bentley_1.Id64.isValid(targetElementId)
+            ? targetElementId
+            : undefined;
         if (!this._options.wasSourceIModelCopiedToTarget) {
             this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
         }
@@ -1237,17 +1205,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         // FIXME: verify at finalization time that we don't lose provenance on new elements
         // FIXME: make public and improve `initElementProvenance` API for usage by consolidators
         if (!this._options.noProvenance) {
-            let provenance = this._options.forceExternalSourceAspectProvenance || this._elementsWithExplicitlyTrackedProvenance.has(sourceElement.id)
+            let provenance = this._options.forceExternalSourceAspectProvenance ||
+                this._elementsWithExplicitlyTrackedProvenance.has(sourceElement.id)
                 ? undefined
                 : sourceElement.federationGuid;
             if (!provenance) {
                 const aspectProps = this.initElementProvenance(sourceElement.id, targetElementProps.id);
-                const aspectId = this.queryScopeExternalSource(aspectProps).aspectId;
-                if (aspectId === undefined) {
+                const foundEsaProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, aspectProps);
+                if (foundEsaProps === undefined)
                     aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
-                }
                 else {
-                    aspectProps.id = aspectId;
+                    // Since initElementProvenance sets a property 'version' on the aspectProps that we wish to persist in the provenanceDb, only grab the id from the foundEsaProps.
+                    aspectProps.id = foundEsaProps.aspectId;
                     this.provenanceDb.elements.updateAspect(aspectProps);
                 }
                 provenance = aspectProps;
@@ -1278,10 +1247,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * This override calls [[onTransformModel]] and then [IModelImporter.importModel]($transformer) to update the target iModel.
      */
     onExportModel(sourceModel) {
-        if (core_common_1.IModel.repositoryModelId === sourceModel.id) {
+        if (this._options.skipPropagateChangesToRootElements &&
+            core_common_1.IModel.repositoryModelId === sourceModel.id)
             return; // The RepositoryModel should not be directly imported
-        }
         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;
+        if (isRemappedRootSubject)
+            return;
         const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
         this.importer.importModel(targetModelProps);
         this.resolvePendingReferences(sourceModel);
@@ -1294,18 +1268,36 @@ 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: return true;
-                    case core_bentley_1.DbResult.BE_SQLITE_DONE: return false;
-                    default: (0, core_bentley_1.assert)(false, `unexpected db result: '${stmt}'`);
+                    case core_bentley_1.DbResult.BE_SQLITE_ROW:
+                        return true;
+                    case core_bentley_1.DbResult.BE_SQLITE_DONE:
+                        return false;
+                    default:
+                        (0, core_bentley_1.assert)(false, `unexpected db result: '${JSON.stringify(stmt)}'`);
                 }
             });
             if (isDefinitionPartition) {
@@ -1319,7 +1311,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.importer.deleteModel(targetModelId);
         }
         catch (error) {
-            const isDeletionProhibitedErr = error instanceof core_common_1.IModelError && (error.errorNumber === core_bentley_1.IModelStatus.DeletionProhibited || error.errorNumber === core_bentley_1.IModelStatus.ForeignKeyConstraint);
+            const isDeletionProhibitedErr = error instanceof core_common_1.IModelError &&
+                (error.errorNumber === core_bentley_1.IModelStatus.DeletionProhibited ||
+                    error.errorNumber === core_bentley_1.IModelStatus.ForeignKeyConstraint);
             if (!isDeletionProhibitedErr)
                 throw error;
             // Transformer tries to delete models before it deletes elements. Definition models cannot be deleted unless all of their modeled elements are deleted first.
@@ -1330,7 +1324,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Schedule modeled partition deletion */
     scheduleModeledPartitionDeletion(sourceModelId) {
-        const deletedElements = this.exporter.sourceDbChanges?.element.deleteIds;
+        const deletedElements = this.exporter.sourceDbChanges?.element
+            .deleteIds;
         if (!deletedElements.has(sourceModelId)) {
             deletedElements.add(sourceModelId);
         }
@@ -1396,7 +1391,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     onTransformModel(sourceModel, targetModeledElementId) {
         const targetModelProps = sourceModel.toJSON();
         // don't directly edit deep object since toJSON performs a shallow clone
-        targetModelProps.modeledElement = { ...targetModelProps.modeledElement, id: targetModeledElementId };
+        targetModelProps.modeledElement = {
+            ...targetModelProps.modeledElement,
+            id: targetModeledElementId,
+        };
         targetModelProps.id = targetModeledElementId;
         targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
         return targetModelProps;
@@ -1405,10 +1403,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @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"
+     * during the transformation as "pending synchronization changeset indices" @see TargetScopeProvenanceJsonProps
      *
      * You generally should not call this function yourself and use [[processChanges]] instead.
      * It is public for unsupported use cases of custom synchronization transforms.
@@ -1416,45 +1414,61 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * without setting the `force` option to `true`
      */
     updateSynchronizationVersion({ force = false } = {}) {
-        if (!force && (this._sourceChangeDataState !== "has-changes" && !this._isFirstSynchronization))
+        const notForcedAndHasNoChangesAndIsntProvenanceInit = !force &&
+            this._sourceChangeDataState !== "has-changes" &&
+            !this._isProvenanceInitTransform;
+        if (notForcedAndHasNoChangesAndIsntProvenanceInit)
             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._isFirstSynchronization) {
+        if (this._isProvenanceInitTransform) {
             this._targetScopeProvenanceProps.version = sourceVersion;
-            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion = targetVersion;
+            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
+                targetVersion;
         }
-        else if (this._options.isReverseSynchronization) {
+        else 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;
+            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
+                sourceVersion;
         }
-        else if (!this._options.isReverseSynchronization) {
+        else if (!this.isReverseSynchronization) {
             core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${this._targetScopeProvenanceProps.version} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.version = sourceVersion;
         }
-        if (this._isSynchronization) {
-            (0, core_bentley_1.assert)(this.targetDb.changeset.index !== undefined && this._startingChangesetIndices !== undefined, "updateSynchronizationVersion was called without change history");
+        if (this._isSynchronization ||
+            (this._startingChangesetIndices && this._isProvenanceInitTransform)) {
+            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";
+            const [syncChangesetsToClearKey, syncChangesetsToUpdateKey] = this
+                .isReverseSynchronization
+                ? [
+                    pendingReverseSyncChangesetIndicesKey,
+                    pendingSyncChangesetIndicesKey,
+                ]
+                : [
+                    pendingSyncChangesetIndicesKey,
+                    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
-            // FIXME: force save for the user to prevent that
             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, "changeset didn't exist");
+            if (this.isReverseSynchronization) {
+                nodeAssert(this.sourceDb.changeset.index !== undefined, "changeset didn't exist");
                 for (let i = this._startingChangesetIndices.source + 1; i <= this.sourceDb.changeset.index + 1; i++)
                     jsonProps.pendingReverseSyncChangesetIndices.push(i);
             }
@@ -1465,19 +1479,22 @@ 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)
     finalizeTransformation() {
         this.importer.finalize();
         this.updateSynchronizationVersion();
         if (this._partiallyCommittedEntities.size > 0) {
-            // FIXME: throw in this case if danglingReferenceBehavior === reject
-            core_bentley_1.Logger.logWarning(loggerCategory, [
+            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"));
+            ].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();
             }
@@ -1489,7 +1506,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         // this internal is guaranteed stable for just transformer usage
         /* eslint-disable @itwin/no-internal */
-        if ("codeValueBehavior" in this.sourceDb) {
+        if (("codeValueBehavior" in this.sourceDb)) {
             this.sourceDb.codeValueBehavior = "trim-unicode-whitespace";
             this.targetDb.codeValueBehavior = "trim-unicode-whitespace";
         }
@@ -1506,7 +1523,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Override of [IModelExportHandler.shouldExportRelationship]($transformer) that is called to determine if a [Relationship]($backend) should be exported.
      * @note Reaching this point means that the relationship has passed the standard exclusion checks in [IModelExporter]($transformer).
      */
-    shouldExportRelationship(_sourceRelationship) { return true; }
+    shouldExportRelationship(_sourceRelationship) {
+        return true;
+    }
     /** Override of [IModelExportHandler.onExportRelationship]($transformer) that imports a relationship into the target iModel when it is exported from the source iModel.
      * This override calls [[onTransformRelationship]] and then [IModelImporter.importRelationship]($transformer) to update the target iModel.
      */
@@ -1515,14 +1534,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetFedGuid = queryElemFedGuid(this.sourceDb, sourceRelationship.targetId);
         const targetRelationshipProps = this.onTransformRelationship(sourceRelationship);
         const targetRelationshipInstanceId = this.importer.importRelationship(targetRelationshipProps);
-        if (!this._options.noProvenance && core_bentley_1.Id64.isValid(targetRelationshipInstanceId)) {
+        if (!this._options.noProvenance &&
+            core_bentley_1.Id64.isValid(targetRelationshipInstanceId)) {
             let provenance = !this._options.forceExternalSourceAspectProvenance
                 ? sourceFedGuid && targetFedGuid && `${sourceFedGuid}/${targetFedGuid}`
                 : undefined;
             if (!provenance) {
                 const aspectProps = this.initRelationshipProvenance(sourceRelationship, targetRelationshipInstanceId);
-                aspectProps.id = this.queryScopeExternalSource(aspectProps).aspectId;
-                if (undefined === aspectProps.id) {
+                const foundEsaProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, aspectProps);
+                // onExportRelationship doesn't need to call updateAspect if esaProps were found, because relationship provenance doesn't have the same concept of a version as element provenance (which uses last mod time on the elements).
+                if (undefined === foundEsaProps) {
                     aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
                 }
                 provenance = aspectProps;
@@ -1541,14 +1562,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 ?? {
-            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());
+        const id = deletedRelData.relId ??
+            this.targetDb.relationships.tryGetInstance(deletedRelData.classFullName, {
+                sourceId: deletedRelData.sourceIdInTarget,
+                targetId: deletedRelData.targetIdInTarget,
+            })?.id;
+        if (id) {
+            this.importer.deleteRelationship({
+                id,
+                classFullName: deletedRelData.classFullName,
+            });
         }
         if (deletedRelData.provenanceAspectId) {
             try {
@@ -1569,7 +1592,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
     async detectRelationshipDeletes() {
-        if (this._options.isReverseSynchronization) {
+        if (this.isReverseSynchronization) {
             throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
         }
         const aspectDeleteIds = [];
@@ -1584,14 +1607,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Relationship);
             while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
                 const sourceRelInstanceId = core_bentley_1.Id64.fromJSON(statement.getValue(1).getString());
-                if (undefined === this.sourceDb.relationships.tryGetInstanceProps(core_backend_1.ElementRefersToElements.classFullName, sourceRelInstanceId)) {
+                if (undefined ===
+                    this.sourceDb.relationships.tryGetInstanceProps(core_backend_1.ElementRefersToElements.classFullName, sourceRelInstanceId)) {
                     // this function exists only to support some in-imodel transformations, which must
                     // use the old (external source aspect) provenance method anyway so we don't need to support
                     // new provenance
                     const json = JSON.parse(statement.getValue(2).getString());
-                    if (undefined !== json.targetRelInstanceId) {
-                        const targetRelationship = this.targetDb.relationships.getInstance(core_backend_1.ElementRefersToElements.classFullName, json.targetRelInstanceId);
-                        this.importer.deleteRelationship(targetRelationship.toJSON());
+                    const targetRelInstanceId = json.targetRelInstanceId ?? json.provenanceRelInstanceId;
+                    if (targetRelInstanceId) {
+                        this.importer.deleteRelationship({
+                            id: targetRelInstanceId,
+                            classFullName: core_backend_1.ElementRefersToElements.classFullName,
+                        });
                     }
                     aspectDeleteIds.push(statement.getValue(0).getId());
                 }
@@ -1611,8 +1638,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         targetRelationshipProps.targetId = this.context.findTargetElementId(sourceRelationship.targetId);
         // TODO: move to cloneRelationship in IModelCloneContext
         sourceRelationship.forEachProperty((propertyName, propertyMetaData) => {
-            if ((core_common_1.PrimitiveTypeCode.Long === propertyMetaData.primitiveType) && ("Id" === propertyMetaData.extendedType)) {
-                targetRelationshipProps[propertyName] = this.context.findTargetElementId(sourceRelationship.asAny[propertyName]);
+            if (core_common_1.PrimitiveTypeCode.Long === propertyMetaData.primitiveType &&
+                "Id" === propertyMetaData.extendedType) {
+                targetRelationshipProps[propertyName] =
+                    this.context.findTargetElementId(sourceRelationship.asAny[propertyName]);
             }
         });
         return targetRelationshipProps;
@@ -1644,8 +1673,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         sourceAspects.forEach((a) => this.collectUnmappedReferences(a));
         // 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 && a.scope?.id === this.targetScopeElementId;
-            return !this._options.includeSourceProvenance || !isExternalSourceAspectFromTransformer;
+            const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect &&
+                a.scope?.id === this.targetScopeElementId;
+            return (!this._options.includeSourceProvenance ||
+                !isExternalSourceAspectFromTransformer);
         });
         for (let i = 0; i < targetIds.length; ++i) {
             this.context.remapElementAspect(sourceAspects[i].id, targetIds[i]);
@@ -1686,7 +1717,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const systemMaxPathSegmentSize = 255;
         // 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) {
+        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,
@@ -1726,7 +1759,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             const maybeLongNameResolvingSchemaCtx = this._longNamedSchemasMap.size > 0
                 ? this._makeLongNameResolvingSchemaCtx()
                 : undefined;
-            return await this.targetDb.importSchemas(schemaFullPaths, { ecSchemaXmlContext: maybeLongNameResolvingSchemaCtx });
+            return await this.targetDb.importSchemas(schemaFullPaths, {
+                ecSchemaXmlContext: maybeLongNameResolvingSchemaCtx,
+            });
         }
         finally {
             core_backend_1.IModelJsFs.removeSync(this._schemaExportDir);
@@ -1734,8 +1769,8 @@ 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 [[processChanges]] and [[processAll]], 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
         await this.initialize();
@@ -1762,7 +1797,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Override of [IModelExportHandler.shouldExportCodeSpec]($transformer) that is called to determine if a CodeSpec should be exported from the source iModel.
      * @note Reaching this point means that the CodeSpec has passed the standard exclusion checks in [IModelExporter]($transformer).
      */
-    shouldExportCodeSpec(_sourceCodeSpec) { return true; }
+    shouldExportCodeSpec(_sourceCodeSpec) {
+        return true;
+    }
     /** Override of [IModelExportHandler.onExportCodeSpec]($transformer) that imports a CodeSpec into the target iModel when it is exported from the source iModel. */
     onExportCodeSpec(sourceCodeSpec) {
         this.context.importCodeSpec(sourceCodeSpec.id);
@@ -1786,33 +1823,224 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async initialize(args) {
         if (this._initialized)
             return;
-        await this.context.initialize();
         await this._tryInitChangesetData(args);
+        await this.context.initialize();
+        // need exporter initialized to do remapdeletedsourceentities.
         await this.exporter.initialize(this.getExportInitOpts(args ?? {}));
-        // Exporter must be initialized prior to `initFromExternalSourceAspects` in order to handle entity recreations.
-        // eslint-disable-next-line deprecation/deprecation
-        await this.initFromExternalSourceAspects(args);
+        // 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.
+     * This function returns early if csFileProps is undefined or is of length 0.
+     * @returns void
+     */
+    async processChangesets() {
+        this.forEachTrackedElement((sourceElementId, targetElementId) => {
+            this.context.remapElement(sourceElementId, targetElementId);
+        });
+        if (this._csFileProps === undefined || this._csFileProps.length === 0)
+            return;
+        const hasElementChangedCache = new Set();
+        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);
+        }
+        const relationshipECClassIds = new Set();
+        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementRefersToElements)")) {
+            relationshipECClassIds.add(row.ECInstanceId);
+        }
+        const elementECClassIds = new Set();
+        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.Element)")) {
+            elementECClassIds.add(row.ECInstanceId);
+        }
+        // For later use when processing deletes.
+        const alreadyImportedElementInserts = new Set();
+        const alreadyImportedModelInserts = new Set();
+        this.exporter.sourceDbChanges?.element.insertIds.forEach((insertedSourceElementId) => {
+            const targetElementId = this.context.findTargetElementId(insertedSourceElementId);
+            if (core_bentley_1.Id64.isValid(targetElementId))
+                alreadyImportedElementInserts.add(targetElementId);
+        });
+        this.exporter.sourceDbChanges?.model.insertIds.forEach((insertedSourceModelId) => {
+            const targetModelId = this.context.findTargetElementId(insertedSourceModelId);
+            if (core_bentley_1.Id64.isValid(targetModelId))
+                alreadyImportedModelInserts.add(targetModelId);
+        });
+        this._deletedSourceRelationshipData = new Map();
+        for (const csFile of this._csFileProps) {
+            const csReader = core_backend_1.SqliteChangesetReader.openFile({
+                fileName: csFile.pathname,
+                db: this.sourceDb,
+                disableSchemaCheck: true,
+            });
+            const csAdaptor = new core_backend_1.ChangesetECAdaptor(csReader);
+            const ecChangeUnifier = new core_backend_1.PartialECChangeUnifier();
+            while (csAdaptor.step()) {
+                ecChangeUnifier.appendFrom(csAdaptor);
+            }
+            const changes = [...ecChangeUnifier.instances];
+            /** a map of element ids to this transformation scope's ESA data for that element, in case the ESA is deleted in the target */
+            const elemIdToScopeEsa = new Map();
+            for (const change of changes) {
+                if (change.ECClassId !== undefined &&
+                    relationshipECClassIdsToSkip.has(change.ECClassId))
+                    continue;
+                const changeType = change.$meta?.op;
+                if (changeType === "Deleted" &&
+                    change?.$meta?.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
+                    change.Scope.Id === this.targetScopeElementId) {
+                    elemIdToScopeEsa.set(change.Element.Id, change);
+                }
+                else if ((changeType === "Inserted" || changeType === "Updated") &&
+                    change.ECClassId !== undefined &&
+                    elementECClassIds.has(change.ECClassId))
+                    hasElementChangedCache.add(change.ECInstanceId);
+            }
+            // Loop to process deletes.
+            for (const change of changes) {
+                const changeType = change.$meta?.op;
+                const ecClassId = change.ECClassId ?? change.$meta?.fallbackClassId;
+                if (ecClassId === undefined)
+                    throw new Error(`ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`);
+                if (changeType === undefined)
+                    throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
+                if (changeType !== "Deleted" ||
+                    relationshipECClassIdsToSkip.has(ecClassId))
+                    continue;
+                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
+            }
+            csReader.close();
+        }
+        this._hasElementChangedCache = hasElementChangedCache;
+        return;
+    }
+    /**
+     * 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"
+     * @param mapOfDeletedElemIdToScopeEsas a map of elementIds to changedECInstances (which are ESAs). the elementId is not the id of the esa itself, but the elementid that the esa was stored on before the esa's deletion.
+     * All ESAs in this map are part of the transformer's scope / ESA data and are tracked in case the ESA is deleted in the target.
+     * @param isRelationship is relationship or not
+     * @param alreadyImportedElementInserts used to handle entity recreation and not delete already handled element inserts.
+     * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
+     * @returns void
+     */
+    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;
+        if (notConnectedModel || noChanges)
+            return;
+        /**
+         * 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;
+            let element;
+            if (isRelationship) {
+                element = this.sourceDb.elements.tryGetElement(id);
+            }
+            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;
+            }
+            // Check for targetId by an esa first
+            if (changeDataInProvenanceDb && identifierValue) {
+                const targetId = identifierValue;
+                return targetId;
+            }
+            // 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;
+            }
+            return undefined;
+        };
+        const changedInstanceId = change.ECInstanceId;
+        if (isRelationship) {
+            const sourceIdOfRelationshipInSource = change.SourceECInstanceId;
+            const targetIdOfRelationshipInSource = change.TargetECInstanceId;
+            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: sourceIdOfRelationshipInTarget,
+                    targetIdInTarget: targetIdOfRelationshipInTarget,
+                });
+            }
+            else if (this.sourceDb === this.provenanceSourceDb) {
+                const relProvenance = this._queryProvenanceForRelationship(changedInstanceId, {
+                    classFullName: classFullName ?? "",
+                    sourceId: sourceIdOfRelationshipInSource,
+                    targetId: targetIdOfRelationshipInSource,
+                });
+                if (relProvenance && relProvenance.relationshipId)
+                    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 || this.sourceDb.iTwinId === undefined || this.sourceDb.changeset.index === undefined) {
+        if (!args ||
+            this.sourceDb.iTwinId === undefined ||
+            this.sourceDb.changeset.index === undefined) {
             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._changeSummaryIds = [];
+            this._csFileProps = [];
             return;
         }
         // 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 = args.startChangeset?.index ??
+            args.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"
+        const [startChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetIndexOrId, endChangesetId].map(async (indexOrId) => typeof indexOrId === "number"
             ? indexOrId
             : core_backend_1.IModelHost.hubAccess
                 .queryChangeset({
@@ -1822,55 +2050,68 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 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) {
-            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}.`);
+        const missingChangesets = startChangesetIndex > this.synchronizationVersion.index + 1;
+        if (!this._options.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}.`);
         }
         nodeAssert(this._targetScopeProvenanceProps, "_targetScopeProvenanceProps should be set by now");
-        const changesetsToSkip = this._isReverseSynchronization
-            ? this._targetScopeProvenanceProps.jsonProperties.pendingReverseSyncChangesetIndices
-            : this._targetScopeProvenanceProps.jsonProperties.pendingSyncChangesetIndices;
+        const changesetsToSkip = this.isReverseSynchronization
+            ? this._targetScopeProvenanceProps.jsonProperties
+                .pendingReverseSyncChangesetIndices
+            : this._targetScopeProvenanceProps.jsonProperties
+                .pendingSyncChangesetIndices;
         core_bentley_1.Logger.logTrace(loggerCategory, `changesets to skip: ${changesetsToSkip}`);
         this._changesetRanges = (0, Algo_1.rangesFromRangeAndSkipped)(startChangesetIndex, endChangesetIndex, changesetsToSkip);
         core_bentley_1.Logger.logTrace(loggerCategory, `ranges: ${this._changesetRanges}`);
+        const csFileProps = [];
         for (const [first, end] of this._changesetRanges) {
-            this._changeSummaryIds = await core_backend_1.ChangeSummaryManager.createChangeSummaries({
-                accessToken: args.accessToken,
+            // TODO: should the first changeset in a reverse sync really be included even though its 'initialized branch provenance'? The answer is no, its a bug that needs to be fixed.
+            const fileProps = await core_backend_1.IModelHost.hubAccess.downloadChangesets({
                 iModelId: this.sourceDb.iModelId,
-                iTwinId: this.sourceDb.iTwinId,
+                targetDir: core_backend_1.BriefcaseManager.getChangeSetsPath(this.sourceDb.iModelId),
                 range: { first, end },
             });
+            csFileProps.push(...fileProps);
         }
-        core_backend_1.ChangeSummaryManager.attachChangeCache(this.sourceDb);
-        this._sourceChangeDataState = "has-changes";
+        this._csFileProps = csFileProps;
+        /** 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";
     }
     /** 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.
-   */
+     * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
+     */
     async processAll() {
         this.logSettings();
         this.initScopeProvenance();
         await this.initialize();
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
-        // 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
-        await this.exporter.exportSubModels(core_common_1.IModel.repositoryModelId); // start below the RepositoryModel
+        if (this._options.skipPropagateChangesToRootElements) {
+            // 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
+            await this.exporter.exportSubModels(core_common_1.IModel.repositoryModelId); // start below the RepositoryModel
+        }
+        else {
+            await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
+        }
         await this.exporter["exportAllAspects"](); // eslint-disable-line @typescript-eslint/dot-notation
         await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
         await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
-        // FIXME: add a deprecated option to force run these, don't otherwise
-        if (this.shouldDetectDeletes()) {
+        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)
@@ -1879,222 +2120,34 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.finalizeTransformation();
     }
     markLastProvenance(sourceAspect, { isRelationship = false }) {
-        this._lastProvenanceEntityInfo
-            = typeof sourceAspect === "string"
+        this._lastProvenanceEntityInfo =
+            typeof sourceAspect === "string"
                 ? sourceAspect
                 : {
                     entityId: sourceAspect.element.id,
                     aspectId: sourceAspect.id,
                     aspectVersion: sourceAspect.version ?? "",
-                    aspectKind: isRelationship ? core_backend_1.ExternalSourceAspect.Kind.Relationship : core_backend_1.ExternalSourceAspect.Kind.Element,
+                    aspectKind: isRelationship
+                        ? core_backend_1.ExternalSourceAspect.Kind.Relationship
+                        : 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
+    /** 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 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.
      */
-    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();
-        }
-    }
-    async processChanges(optionsOrAccessToken, startChangesetId) {
+    async processChanges(options) {
         this._isSynchronization = true;
         this.initScopeProvenance();
-        const args = typeof optionsOrAccessToken === "string"
-            ? {
-                accessToken: optionsOrAccessToken,
-                startChangeset: startChangesetId
-                    ? { id: startChangesetId }
-                    : { index: this._synchronizationVersion.index + 1 },
-            }
-            : optionsOrAccessToken;
         this.logSettings();
-        await this.initialize(args);
+        await this.initialize(options);
         // must wait for initialization of synchronization provenance data
-        await this.exporter.exportChanges(this.getExportInitOpts(args));
+        await this.exporter.exportChanges(this.getExportInitOpts(options));
         await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
@@ -2103,7 +2156,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const defaultSaveTargetChanges = () => {
             this.targetDb.saveChanges();
         };
-        await (args.saveTargetChanges ?? defaultSaveTargetChanges)(this);
+        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
@@ -2112,12 +2165,19 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (!this._isSynchronization)
             return {};
         return {
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
             accessToken: opts.accessToken,
-            ...this._changesetRanges
-                ? { changesetRanges: this._changesetRanges }
-                : opts.startChangeset
-                    ? { startChangeset: opts.startChangeset }
-                    : { startChangeset: { index: this._synchronizationVersion.index + 1 } },
+            ...(this._csFileProps
+                ? { csFileProps: this._csFileProps }
+                : this._changesetRanges
+                    ? { changesetRanges: this._changesetRanges }
+                    : opts.startChangeset
+                        ? { startChangeset: opts.startChangeset }
+                        : {
+                            startChangeset: {
+                                index: this.synchronizationVersion.index + 1,
+                            },
+                        }),
         };
     }
     /** Combine an array of source elements into a single target element.
@@ -2133,10 +2193,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
 }
 exports.IModelTransformer = IModelTransformer;
-/** @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.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.";
 /** IModelTransformer that clones the contents of a template model.
  * @beta
  */
@@ -2207,7 +2264,8 @@ class TemplateModelCloner extends IModelTransformer {
                 }
                 else {
                     const definitionElement = this.sourceDb.elements.tryGetElement(referenceId, core_backend_1.DefinitionElement);
-                    if (definitionElement && !(definitionElement instanceof core_backend_1.RecipeDefinitionElement)) {
+                    if (definitionElement &&
+                        !(definitionElement instanceof core_backend_1.RecipeDefinitionElement)) {
                         this.context.remapElement(referenceId, referenceId); // when in the same iModel, can use existing DefinitionElements without remapping
                     }
                     else {
@@ -2222,7 +2280,7 @@ class TemplateModelCloner extends IModelTransformer {
         if (sourceElement instanceof core_backend_1.GeometricElement) {
             const is3d = sourceElement instanceof core_backend_1.GeometricElement3d;
             const placementClass = is3d ? core_common_1.Placement3d : core_common_1.Placement2d;
-            const placement = (placementClass).fromJSON(targetElementProps.placement);
+            const placement = placementClass.fromJSON(targetElementProps.placement);
             if (placement.isValid) {
                 nodeAssert(this._transform3d);
                 placement.multiplyTransform(this._transform3d);