@itwin/imodel-transformer 2.0.0-dev.2 → 2.0.0-dev.21

package/lib/cjs/IModelTransformer.js

@@ -21,13 +21,9 @@ const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
 const IModelCloneContext_1 = require("./IModelCloneContext");
 const EntityUnifier_1 = require("./EntityUnifier");
 const Algo_1 = require("./Algo");
+const SyncTypeResolver_1 = require("./SyncTypeResolver");
+const ProvenanceManager_1 = require("./ProvenanceManager");
 const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelTransformer;
-const nullLastProvenanceEntityInfo = {
-    entityId: core_bentley_1.Id64.invalid,
-    aspectId: core_bentley_1.Id64.invalid,
-    aspectVersion: "",
-    aspectKind: core_backend_1.ExternalSourceAspect.Kind.Element,
-};
 /**
  * Apply a function to each Id64 in a supported container type of Id64s.
  * Currently only supports raw Id64String or RelatedElement-like objects containing an `id` property that is a Id64String,
@@ -77,7 +73,26 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     targetDb;
     /** The IModelTransformContext for this IModelTransformer. */
     context;
-    _syncType;
+    /** The transform to be applied to the placement of spatial elements
+     * This transform should be applied when:
+     * - source and target db have different ECEF locations
+     * - source and target db have matching GCS/CRS data, but differing `geographicCoordinateSystem.additionalTransform.helmert2DWithZOffset`
+     * @note for ECEF transforms, this can only be used when source and target are linearly located imodels
+     * @note for non linearly located imodels, this transform will be a linear transform derived from Helmert Transforms from the src and target iModels.
+     * @beta
+     */
+    _linearSpatialTransform;
+    /** The [[EditTxn]] used for write operations on the target iModel.
+     * The caller is responsible for starting, committing or abandoning this transaction.
+     * @beta
+     */
+    _targetEditTxn;
+    /** The optional [[EditTxn]] used for write operations on the source iModel during reverse synchronization.
+     * @beta
+     */
+    _sourceEditTxn;
+    _syncTypeResolver;
+    _provenanceManager;
     /** The Id of the Element in the **target** iModel that represents the **source** repository as a whole and scopes its [ExternalSourceAspect]($backend) instances. */
     get targetScopeElementId() {
         return this._options.targetScopeElementId;
@@ -86,118 +101,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     _elementsWithExplicitlyTrackedProvenance = new Set();
     _partiallyCommittedElementIds = new Set();
     _partiallyCommittedAspectIds = new Set();
-    /** the options that were used to initialize this transformer */
-    _options;
-    /**
-     * 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.
-     */
-    _allowNoScopingESA = false;
-    static 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.";
     /**
-     * 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
+     * Tracks target element IDs that were remapped by Code during the current
+     * transformation pass. Used to prevent deletion of target elements that have been remapped
+     * to a new source element in the same pass (e.g., when a source element is deleted and a
+     * new one with the same properties is added, causing a remap to the same target).
      */
-    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
-    `;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        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 };
-        });
-    }
+    _targetElementIdsRemappedByCode = new Set();
     /**
-     * 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"
+     * Tracks target model IDs that were imported (inserted or updated) during the current
+     * transformation pass. Used to prevent deletion of target models that have been recreated
+     * in the same pass (e.g. when a partition element is recreated with a new model).
      */
-    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._options.argsForProcessChanges) {
-            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 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";
-    }
+    _targetModelsImportedInCurrentTransform = new Set();
+    /** the options that were used to initialize this transformer */
+    _options;
     _changesetRanges = undefined;
     /**
      * Set if the transformer is being used to perform the provenance initialization step of a fork initialization.
@@ -206,34 +124,29 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     _isProvenanceInitTransform;
     /** 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 ProvenanceManager_1.ProvenanceManager.provenanceElementClasses;
     }
     /** The element aspect classes that are considered to define provenance in the iModel */
     static get provenanceElementAspectClasses() {
-        return [core_backend_1.ExternalSourceAspect];
+        return ProvenanceManager_1.ProvenanceManager.provenanceElementAspectClasses;
     }
     /** Construct a new IModelTransformer
-     * @param source Specifies the source IModelExporter or the source IModelDb that will be used to construct the source IModelExporter.
-     * @param target Specifies the target IModelImporter or the target IModelDb that will be used to construct the target IModelImporter.
+     * @param args The required arguments including source and target.
      * @param options The options that specify how the transformation should be done.
      */
-    constructor(source, target, options) {
+    constructor(args, options) {
         super();
+        const { source, target } = args;
         // initialize IModelTransformOptions
         this._options = {
             ...options,
             // non-falsy defaults
             cloneUsingBinaryGeometry: options?.cloneUsingBinaryGeometry ?? true,
             targetScopeElementId: options?.targetScopeElementId ?? core_common_1.IModel.rootSubjectId,
-            // eslint-disable-next-line deprecation/deprecation
             danglingReferencesBehavior: options?.danglingReferencesBehavior ?? "reject",
             branchRelationshipDataBehavior: options?.branchRelationshipDataBehavior ?? "reject",
             skipPropagateChangesToRootElements: options?.skipPropagateChangesToRootElements ?? true,
+            tryAlignGeolocation: options?.tryAlignGeolocation ?? false,
         };
         // check if authorization client is defined
         if (core_backend_1.IModelHost.authorizationClient === undefined) {
@@ -261,7 +174,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.exporter.excludeElementAspectClass(core_backend_1.ChannelRootAspect.classFullName); // Channel boundaries within the source iModel are not relevant to the target iModel
         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) {
+        if (target instanceof core_backend_1.EditTxn) {
             this.importer = new IModelImporter_1.IModelImporter(target, {
                 preserveElementIdsForFiltering: this._options.preserveElementIdsForFiltering,
                 skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
@@ -272,16 +185,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.validateSharedOptionsMatch();
         }
         this.targetDb = this.importer.targetDb;
+        this._targetEditTxn = this.importer.editTxn;
+        this._sourceEditTxn = options?.sourceEditTxn;
         // 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");
-            this._startingChangesetIndices = {
-                target: this.targetDb.changeset.index,
-                source: this.sourceDb.changeset.index,
-            };
-        }
         // this internal is guaranteed stable for just transformer usage
         /* eslint-disable @itwin/no-internal */
         if (("codeValueBehavior" in this.sourceDb)) {
@@ -289,6 +196,22 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.targetDb.codeValueBehavior = "exact";
         }
         /* eslint-enable @itwin/no-internal */
+        this._syncTypeResolver = new SyncTypeResolver_1.SyncTypeResolver(this.context, this._options.targetScopeElementId, !!this._isProvenanceInitTransform, !!this._options.argsForProcessChanges);
+        this._provenanceManager = new ProvenanceManager_1.ProvenanceManager(this._options.targetScopeElementId, this._options, this._syncTypeResolver, this._targetEditTxn, this._sourceEditTxn);
+        if (this._options.tryAlignGeolocation) {
+            if (this.sourceDb.geographicCoordinateSystem ||
+                this.targetDb.geographicCoordinateSystem) {
+                core_bentley_1.Logger.logTrace(loggerCategory, "Aligning Additional transforms between imodels due to imodels containing GeographicCoordinateSystem data");
+                this._linearSpatialTransform =
+                    this.calculateTransformFromHelmertTransforms();
+            }
+            else if (this.sourceDb.ecefLocation && this.targetDb.ecefLocation) {
+                core_bentley_1.Logger.logTrace(loggerCategory, "Aligning ECEF Location's between imodels due to imodels not containing GeographicCoordinateSystem data");
+                this._linearSpatialTransform = this.calculateEcefTransform();
+            }
+            else
+                core_bentley_1.Logger.logTrace(loggerCategory, "No Geolcation data to align, both GCS and ECEF are undefined");
+        }
     }
     /** 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.
@@ -308,7 +231,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Dispose any native resources associated with this IModelTransformer. */
     dispose() {
         core_bentley_1.Logger.logTrace(loggerCategory, "dispose()");
-        this.context.dispose();
+        this.context[Symbol.dispose]();
     }
     /** Log current settings that affect IModelTransformer's behavior. */
     logSettings() {
@@ -325,74 +248,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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.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.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 version = args.isReverseSynchronization
-            ? args.targetDb.elements.queryLastModifiedTime(targetElementId)
-            : args.sourceDb.elements.queryLastModifiedTime(sourceElementId);
-        const aspectIdentifier = args.isReverseSynchronization
-            ? targetElementId
-            : sourceElementId;
-        const aspectProps = {
-            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: {
-                id: elementId,
-                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
-            },
-            scope: { id: args.targetScopeElementId },
-            identifier: aspectIdentifier,
-            kind: core_backend_1.ExternalSourceAspect.Kind.Element,
-            version,
-        };
-        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;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        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);
-            return stmt.getValue(0).getId();
-        });
-        const jsonProperties = args.forceOldRelationshipProvenanceMethod
-            ? { targetRelInstanceId }
-            : { provenanceRelInstanceId };
-        const aspectProps = {
-            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: {
-                id: elementId,
-                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
-            },
-            scope: { id: args.targetScopeElementId },
-            identifier: aspectIdentifier,
-            kind: core_backend_1.ExternalSourceAspect.Kind.Relationship,
-            jsonProperties: JSON.stringify(jsonProperties),
-        };
-        return aspectProps;
-    }
     /**
      * 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
@@ -401,43 +256,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      */
     _forceOldRelationshipProvenanceMethod = false;
     /** 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.isReverseSynchronization,
-            targetScopeElementId: this.targetScopeElementId,
-            sourceDb: this.sourceDb,
-            targetDb: this.targetDb,
-        });
-    }
-    /** Create an ExternalSourceAspectProps in a standard way for a Relationship in an iModel --> iModel transformations.
-     * The ExternalSourceAspect is meant to be owned by the Element in the target iModel that is the `sourceId` of transformed relationship.
-     * The `identifier` property of the ExternalSourceAspect will be the ECInstanceId of the relationship in the master iModel.
-     * The ECInstanceId of the relationship in the branch iModel will be stored in the JsonProperties of the ExternalSourceAspect.
-     */
-    initRelationshipProvenance(sourceRelationship, targetRelInstanceId) {
-        return IModelTransformer.initRelationshipProvenanceOptions(sourceRelationship.id, targetRelInstanceId, {
-            sourceDb: this.sourceDb,
-            targetDb: this.targetDb,
-            isReverseSynchronization: this.isReverseSynchronization,
-            targetScopeElementId: this.targetScopeElementId,
-            forceOldRelationshipProvenanceMethod: this._forceOldRelationshipProvenanceMethod,
-        });
-    }
-    /** NOTE: the json properties must be converted to string before insertion */
-    _targetScopeProvenanceProps = undefined;
-    /**
-     * Index of the changeset that the transformer was at when the transformation begins (was constructed).
-     * Used to determine at the end which changesets were part of a synchronization.
-     */
-    _startingChangesetIndices = undefined;
-    _cachedSynchronizationVersion = undefined;
-    /**
-     * 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;
+    async initElementProvenance(sourceElementId, targetElementId) {
+        return this._provenanceManager.initElementProvenance(sourceElementId, targetElementId);
     }
     /** 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
@@ -446,448 +266,59 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @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) {
-            const provenanceScopeAspect = this.tryGetProvenanceScopeAspect();
-            if (!provenanceScopeAspect) {
-                return { index: -1, id: "" }; // first synchronization.
-            }
-            const version = this.isReverseSynchronization
-                ? JSON.parse(provenanceScopeAspect.jsonProperties ?? "{}").reverseSyncVersion
-                : provenanceScopeAspect.version;
-            if (!version &&
-                this._options.branchRelationshipDataBehavior === "unsafe-migrate") {
-                return { index: -1, id: "" }; // previous synchronization was done before fed guid update.
-            }
-            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.
-        }
-        return this._cachedSynchronizationVersion;
+    async getSynchronizationVersion() {
+        return this._provenanceManager.getSynchronizationVersion();
     }
     /**
      * @returns provenance scope aspect if it exists in the provenanceDb.
      * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
      */
-    tryGetProvenanceScopeAspect() {
-        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 scopeProvenanceAspectProps !== undefined
-            ? this.provenanceDb.elements.getAspect(scopeProvenanceAspectProps.aspectId)
-            : undefined;
+    async tryGetProvenanceScopeAspect() {
+        return this._provenanceManager.tryGetProvenanceScopeAspect();
     }
     /**
      * Make sure there are no conflicting other scope-type external source aspects on the *target scope element*,
      * If there are none at all, insert one, then this must be a first synchronization.
-     * @returns the last synced version (changesetId) on the target scope's external source aspect,
-     *          if this was a [BriefcaseDb]($backend)
      */
-    initScopeProvenance() {
-        const aspectProps = {
-            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 }, // the root Subject scopes scope elements
-            identifier: this.provenanceSourceDb.iModelId,
-            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
-            jsonProperties: undefined,
-        };
-        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: [],
-                pendingSyncChangesetIndices: [],
-                reverseSyncVersion: "", // empty since never before transformed. Will be updated in first reverse sync
-            };
-            // this query does not include "identifier" to find possible conflicts
-            const sql = `
-        SELECT ECInstanceId
-        FROM ${core_backend_1.ExternalSourceAspect.classFullName}
-        WHERE Element.Id=:elementId
-          AND Scope.Id=:scopeId
-          AND Kind=:kind
-        LIMIT 1
-      `;
-            // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-            const hasConflictingScope = this.provenanceDb.withPreparedStatement(sql, 
-            // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-            (statement) => {
-                statement.bindId("elementId", aspectProps.element.id);
-                statement.bindId("scopeId", aspectProps.scope.id); // this scope.id can never be invalid, we create it above
-                statement.bindString("kind", aspectProps.kind);
-                return core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step();
-            });
-            if (hasConflictingScope) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Provenance scope conflict");
-            }
-            if (!this._options.noProvenance) {
-                const id = this.provenanceDb.elements.insertAspect({
-                    ...aspectProps,
-                    jsonProperties: JSON.stringify(aspectProps.jsonProperties),
-                });
-                aspectProps.id = id;
-                // Busting a potential cached version
-                this.clearCachedSynchronizationVersion();
-            }
-        }
-        else {
-            // foundEsaProps is defined.
-            aspectProps.id = foundEsaProps.aspectId;
-            aspectProps.version = foundEsaProps.version;
-            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.argsForProcessChanges?.unsafeFallbackSyncVersion ?? "";
-        const fallbackReverseSyncVersionToUse = this._options.argsForProcessChanges?.unsafeFallbackReverseSyncVersion ??
-            "";
-        if (aspectProps.version === undefined ||
-            (aspectProps.version === "" &&
-                aspectProps.version !== fallbackSyncVersionToUse)) {
-            aspectProps.version = fallbackSyncVersionToUse;
-            madeChange = true;
-        }
-        if (aspectProps.jsonProperties === undefined) {
-            aspectProps.jsonProperties = {
-                pendingReverseSyncChangesetIndices: [],
-                pendingSyncChangesetIndices: [],
-                reverseSyncVersion: fallbackReverseSyncVersionToUse,
-            };
-            madeChange = true;
-        }
-        else if (aspectProps.jsonProperties.reverseSyncVersion === undefined ||
-            (aspectProps.jsonProperties.reverseSyncVersion === "" &&
-                aspectProps.jsonProperties.reverseSyncVersion !==
-                    fallbackReverseSyncVersionToUse)) {
-            aspectProps.jsonProperties.reverseSyncVersion =
-                fallbackReverseSyncVersionToUse;
-            madeChange = true;
-        }
-        /**
-         * This case will only be hit when:
-         *  - first transformation was performed on pre-fedguid transformer.
-         *  - a second processAll transformation was performed on the same target-source iModels post-fedguid transformer.
-         *  - change processing was invoked on for the second 'initial' transformation.
-         *  NOTE: This case likely does not exist anymore, but we will keep it just to be sure.
-         */
-        if (aspectProps.jsonProperties.pendingReverseSyncChangesetIndices ===
-            undefined) {
-            core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingReverseSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
-            aspectProps.jsonProperties.pendingReverseSyncChangesetIndices = [];
-            madeChange = true;
-        }
-        if (aspectProps.jsonProperties.pendingSyncChangesetIndices === undefined) {
-            core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
-            aspectProps.jsonProperties.pendingSyncChangesetIndices = [];
-            madeChange = true;
-        }
-        return madeChange;
+    async initScopeProvenance() {
+        return this._provenanceManager.initScopeProvenance();
     }
     /**
-     * Iterate all matching federation guids and ExternalSourceAspects in the provenance iModel (target unless reverse sync)
-     * and call a function for each one.
-     * @note provenance is done by federation guids where possible
-     * @note this may execute on each element more than once! Only use in cases where that is handled
+     * Get the IModelDb where provenance (ExternalSourceAspects) is stored.
+     * This will be targetDb except when it is a reverse synchronization, in which case it will be sourceDb.
      */
-    static forEachTrackedElement(args) {
-        if (args.provenanceDb === args.provenanceSourceDb)
-            return;
-        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;
-        // query for provenanceDb
-        const elementIdByFedGuidQuery = `
-      SELECT e.ECInstanceId, FederationGuid
-      FROM bis.Element e
-      ${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
-        // NOTE: if we exposed the native attach database support,
-        // we could get the intersection of fed guids in one query, not sure if it would be faster
-        // OR we could do a raw sqlite query...
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        sourceDb.withStatement(elementIdByFedGuidQuery, (sourceStmt) => 
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        targetDb.withStatement(elementIdByFedGuidQuery, (targetStmt) => {
-            if (sourceStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return;
-            let sourceRow = sourceStmt.getRow();
-            if (targetStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return;
-            let targetRow = targetStmt.getRow();
-            // NOTE: these comparisons rely upon the lowercase of the guid,
-            // 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) {
-                    // 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 (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 (sourceStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
-                        return;
-                    sourceRow = sourceStmt.getRow();
-                }
-            }
-        }));
-        // query for provenanceDb
-        const provenanceAspectsQuery = `
-      SELECT esa.Identifier, Element.Id
-      FROM bis.ExternalSourceAspect esa
-      WHERE Scope.Id=:scopeId
-        AND Kind=:kind
-    `;
-        // Technically this will a second time call the function (as documented) on
-        // 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
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        args.provenanceDb.withPreparedStatement(provenanceAspectsQuery, (stmt) => {
-            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()) {
-                // ExternalSourceAspect.Identifier is of type string
-                const aspectIdentifier = stmt.getValue(0).getString();
-                const elementId = stmt.getValue(1).getId();
-                runFnInDataFlowDirection(elementId, aspectIdentifier);
-            }
-        });
-    }
-    forEachTrackedElement(fn) {
-        return IModelTransformer.forEachTrackedElement({
-            provenanceSourceDb: this.provenanceSourceDb,
-            provenanceDb: this.provenanceDb,
-            targetScopeElementId: this.targetScopeElementId,
-            isReverseSynchronization: this.isReverseSynchronization,
-            fn,
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? true,
-        });
+    async getProvenanceDb() {
+        return (await this.getIsReverseSynchronization())
+            ? this.sourceDb
+            : this.targetDb;
     }
     /**
-     * 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
+     * Get whether this is a reverse synchronization.
      */
-    _queryProvenanceForElement(entityInProvenanceSourceId) {
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        return this.provenanceDb.withPreparedStatement(`
-        SELECT esa.Element.Id
-        FROM Bis.ExternalSourceAspect esa
-        WHERE esa.Kind=?
-          AND esa.Scope.Id=?
-          AND esa.Identifier=?
-      `, (stmt) => {
-            stmt.bindString(1, core_backend_1.ExternalSourceAspect.Kind.Element);
-            stmt.bindId(2, this.targetScopeElementId);
-            stmt.bindString(3, entityInProvenanceSourceId);
-            if (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return stmt.getValue(0).getId();
-            else
-                return undefined;
-        });
+    async getIsReverseSynchronization() {
+        return (await this._syncTypeResolver.getSyncType()) === "reverse";
     }
     /**
-     * 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
+     * Get whether this is a forward synchronization.
      */
-    _queryProvenanceForRelationship(entityInProvenanceSourceId, sourceRelInfo) {
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        return this.provenanceDb.withPreparedStatement(`
-        SELECT
-          ECInstanceId,
-          JSON_EXTRACT(JsonProperties, '$.targetRelInstanceId'),
-          JSON_EXTRACT(JsonProperties, '$.provenanceRelInstanceId')
-        FROM Bis.ExternalSourceAspect
-        WHERE Kind=?
-          AND Scope.Id=?
-          AND Identifier=?
-      `, (stmt) => {
-            stmt.bindString(1, core_backend_1.ExternalSourceAspect.Kind.Relationship);
-            stmt.bindId(2, this.targetScopeElementId);
-            stmt.bindString(3, entityInProvenanceSourceId);
-            if (stmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return undefined;
-            const aspectId = stmt.getValue(0).getId();
-            const provenanceRelInstIdVal = stmt.getValue(2);
-            const provenanceRelInstanceId = !provenanceRelInstIdVal.isNull
-                ? provenanceRelInstIdVal.getString()
-                : this._queryTargetRelId(sourceRelInfo);
-            return {
-                aspectId,
-                relationshipId: provenanceRelInstanceId,
-            };
-        });
-    }
-    _queryTargetRelId(sourceRelInfo) {
-        const targetRelInfo = {
-            sourceId: this.context.findTargetElementId(sourceRelInfo.sourceId),
-            targetId: this.context.findTargetElementId(sourceRelInfo.targetId),
-        };
-        if (targetRelInfo.sourceId === undefined ||
-            targetRelInfo.targetId === undefined)
-            return undefined; // couldn't find an element, rel is invalid or deleted
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        return this.targetDb.withPreparedStatement(`
-      SELECT ECInstanceId
-      FROM bis.ElementRefersToElements
-      WHERE SourceECInstanceId=?
-        AND TargetECInstanceId=?
-        AND ECClassId=?
-    `, (stmt) => {
-            stmt.bindId(1, targetRelInfo.sourceId);
-            stmt.bindId(2, targetRelInfo.targetId);
-            stmt.bindId(3, this._targetClassNameToClassId(sourceRelInfo.classFullName));
-            if (stmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return undefined;
-            return stmt.getValue(0).getId();
-        });
-    }
-    _targetClassNameToClassIdCache = new Map();
-    _targetClassNameToClassId(classFullName) {
-        let classId = this._targetClassNameToClassIdCache.get(classFullName);
-        if (classId === undefined) {
-            classId = this._getRelClassId(this.targetDb, classFullName);
-            this._targetClassNameToClassIdCache.set(classFullName, classId);
-        }
-        return classId;
-    }
-    // NOTE: this doesn't handle remapped element classes,
-    // but is only used for relationships rn
-    _getRelClassId(db, classFullName) {
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        return db.withPreparedStatement(`
-      SELECT c.ECInstanceId
-      FROM ECDbMeta.ECClassDef c
-      JOIN ECDbMeta.ECSchemaDef s ON c.Schema.Id=s.ECInstanceId
-      WHERE s.Name=? AND c.Name=?
-    `, (stmt) => {
-            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)
-                return stmt.getValue(0).getId();
-            (0, core_bentley_1.assert)(false, "relationship was not found");
-        });
+    async getIsForwardSynchronization() {
+        return (await this._syncTypeResolver.getSyncType()) === "forward";
     }
-    _queryElemIdByFedGuid(db, fedGuid) {
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        return db.withPreparedStatement("SELECT ECInstanceId FROM Bis.Element WHERE FederationGuid=?", (stmt) => {
-            stmt.bindGuid(1, fedGuid);
-            if (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW)
-                return stmt.getValue(0).getId();
-            else
-                return undefined;
+    /**
+     * Updates the synchronization version on the scope ESA.
+     */
+    async updateSynchronizationVersion({ initializeReverseSyncVersion = false, } = {}) {
+        return this._provenanceManager.updateSynchronizationVersion({
+            initializeReverseSyncVersion,
+            sourceChangeDataState: this._sourceChangeDataState,
         });
     }
     /** 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 [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are provided and change history is known.
      */
-    shouldDetectDeletes() {
-        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 [[process]] when [[IModelTransformOptions.argsForProcessChanges]] is undefined and the option
-     * [[IModelTransformOptions.forceExternalSourceAspectProvenance]] is enabled. It is not
-     * necessary when calling [[process]] with [[IModelTransformOptions.argsForProcessChanges]] defined, since changeset information is sufficient.
-     * @note you do not need to call this directly unless processing a subset of an iModel.
-     * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
-     */
-    async detectElementDeletes() {
-        const sql = `
-      SELECT Identifier, Element.Id
-      FROM BisCore.ExternalSourceAspect
-      WHERE Scope.Id=:scopeId
-        AND Kind=:kind
-    `;
-        nodeAssert(!this.isReverseSynchronization, "synchronizations with processChanges already detect element deletes, don't call detectElementDeletes");
-        // Reported issue: https://github.com/iTwin/itwinjs-core/issues/7989
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        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.isValidId64(aspectIdentifier)) {
-                    continue;
-                }
-                const targetElemId = stmt.getValue(1).getId();
-                const wasDeletedInSource = !EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
-                    entityReference: `e${aspectIdentifier}`,
-                });
-                if (wasDeletedInSource)
-                    this.importer.deleteElement(targetElemId);
-            }
-        });
+    async shouldDetectDeletes() {
+        return (await this._syncTypeResolver.getSyncType()) === "not-sync";
     }
     /** Transform the specified sourceElement into ElementProps for the target iModel.
      * @param sourceElement The Element from the source iModel to transform.
@@ -895,9 +326,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @note A subclass can override this method to provide custom transform behavior.
      * @note This can be called more than once for an element in arbitrary order, so it should not have side-effects.
      */
-    onTransformElement(sourceElement) {
+    async onTransformElement(sourceElement) {
         core_bentley_1.Logger.logTrace(loggerCategory, `onTransformElement(${sourceElement.id}) "${sourceElement.getDisplayLabel()}"`);
-        const targetElementProps = this.context.cloneElement(sourceElement, { binaryGeometry: this._options.cloneUsingBinaryGeometry });
+        const targetElementProps = await 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);
@@ -918,8 +349,87 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 targetElementProps.jsonProperties.Subject.Job = undefined;
             }
         }
+        if (this._linearSpatialTransform !== undefined &&
+            sourceElement instanceof core_backend_1.GeometricElement3d) {
+            // can check the sourceElement since this IModelTransformer does not remap classes
+            const placement = core_common_1.Placement3d.fromJSON(targetElementProps.placement);
+            if (placement.isValid) {
+                placement.multiplyTransform(this._linearSpatialTransform);
+                targetElementProps.placement = placement;
+            }
+        }
         return targetElementProps;
     }
+    /**
+     * Calculate the transform between two ECEF locations
+     * @param srcDb
+     * @param targetDb
+     * @returns Transform that converts relative coordinates in the source iModel to relative coordinates in the target iModel.
+     * @note This can only be used if both source and target iModels are linearly located
+     */
+    calculateEcefTransform() {
+        const srcEcefLoc = this.sourceDb.ecefLocation;
+        const targetEcefLoc = this.targetDb.ecefLocation;
+        if (srcEcefLoc === undefined || targetEcefLoc === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Both source and target ECEF locations must be defined to calculate the transform.");
+        }
+        if (srcEcefLoc.getTransform().isAlmostEqual(targetEcefLoc.getTransform())) {
+            core_bentley_1.Logger.logTrace(loggerCategory, "ECEF data is already aligned. No spatial transforms needed.");
+            return undefined;
+        }
+        const srcSpatialToECEF = srcEcefLoc.getTransform(); // converts relative to ECEF in relation to source
+        const targetECEFToSpatial = targetEcefLoc.getTransform().inverse(); // converts ECEF to relative in relation to target
+        if (!targetECEFToSpatial) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Failed to invert target ECEF transform.");
+        }
+        const ecefTransform = targetECEFToSpatial.multiplyTransformTransform(srcSpatialToECEF); // chain both transforms
+        return ecefTransform;
+    }
+    static convertHelmertToTransform(helmert) {
+        if (!helmert) {
+            return core_geometry_1.Transform.createIdentity();
+        }
+        const rotationXY = core_geometry_1.Matrix3d.createRotationAroundAxisIndex(core_geometry_1.AxisIndex.Z, core_geometry_1.Angle.createDegrees(helmert?.rotDeg));
+        rotationXY.scaleColumnsInPlace(helmert.scale, helmert.scale, 1.0);
+        const translation = core_geometry_1.Vector3d.create(helmert.translationX, helmert.translationY, helmert.translationZ);
+        const helmertTransform = core_geometry_1.Transform.createRefs(translation, rotationXY);
+        return helmertTransform;
+    }
+    calculateTransformFromHelmertTransforms() {
+        if (this.sourceDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
+            this.sourceDb.geographicCoordinateSystem?.verticalCRS === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Source iModel does not have a geographic coordinate system defined.");
+        }
+        if (this.targetDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
+            this.targetDb.geographicCoordinateSystem.verticalCRS === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Target iModel does not have a geographic coordinate system defined.");
+        }
+        if (!this.sourceDb.geographicCoordinateSystem.horizontalCRS.equals(this.targetDb.geographicCoordinateSystem.horizontalCRS) ||
+            !this.sourceDb.geographicCoordinateSystem.verticalCRS.equals(this.targetDb.geographicCoordinateSystem.verticalCRS)) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.MismatchGcs, "Source and target geographic coordinate systems must match to calculate the spatial transform.");
+        }
+        if (this.sourceDb.geographicCoordinateSystem.additionalTransform ===
+            this.targetDb.geographicCoordinateSystem.additionalTransform) {
+            core_bentley_1.Logger.logTrace(loggerCategory, "Geolocation data is already aligned. No spatial transforms needed.");
+            return undefined;
+        }
+        const srcScale = this.sourceDb.geographicCoordinateSystem.additionalTransform
+            ?.helmert2DWithZOffset?.scale ?? 1;
+        const targetScale = this.targetDb.geographicCoordinateSystem.additionalTransform
+            ?.helmert2DWithZOffset?.scale ?? 1;
+        if (srcScale !== targetScale) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.MismatchGcs, "Spatial transform is non rigid. Source and target Helmert transforms must have the same scale to calculate a rigid spatial transform.");
+        }
+        const srcTransform = IModelTransformer.convertHelmertToTransform(this.sourceDb.geographicCoordinateSystem.additionalTransform
+            ?.helmert2DWithZOffset); // moves elements to where src helmert transform would move them at render time
+        const targetTransformInv = IModelTransformer.convertHelmertToTransform(this.targetDb.geographicCoordinateSystem.additionalTransform
+            ?.helmert2DWithZOffset).inverse(); // negates target helmert transform that is applied at render time
+        if (!targetTransformInv) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Failed to invert target Helmert transform.");
+        }
+        const combinedTransform = targetTransformInv.multiplyTransformTransform(srcTransform);
+        return combinedTransform;
+    }
     // if undefined, it can be initialized by calling [[this.processChangesets]]
     _deletedSourceRelationshipData = undefined;
     /** Returns true if a change within sourceElement is detected.
@@ -932,7 +442,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             sourceDbChanges.element.insertIds.has(sourceElement.id) ||
             sourceDbChanges.element.updateIds.has(sourceElement.id));
     }
-    completePartiallyCommittedElements() {
+    async completePartiallyCommittedElements() {
         for (const sourceElementId of this._partiallyCommittedElementIds) {
             const sourceElement = this.sourceDb.elements.getElement({
                 id: sourceElementId,
@@ -943,25 +453,25 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (core_bentley_1.Id64.isInvalid(targetId)) {
                 throw new Error(`source-target element mapping not found for element "${sourceElementId}" when completing partially committed elements. This is a bug.`);
             }
-            const targetProps = this.onTransformElement(sourceElement);
-            this.targetDb.elements.updateElement({ ...targetProps, id: targetId });
+            const targetProps = await this.onTransformElement(sourceElement);
+            this._targetEditTxn.updateElement({ ...targetProps, id: targetId });
         }
     }
-    completePartiallyCommittedAspects() {
+    async completePartiallyCommittedAspects() {
         for (const sourceAspectId of this._partiallyCommittedAspectIds) {
             const sourceAspect = this.sourceDb.elements.getAspect(sourceAspectId);
             const targetAspectId = this.context.findTargetAspectId(sourceAspectId);
             if (core_bentley_1.Id64.isInvalid(targetAspectId)) {
                 throw new Error(`source-target aspect mapping not found for aspect "${sourceAspectId}" when completing partially committed aspects. This is a bug.`);
             }
-            const targetAspectProps = this.onTransformElementAspect(sourceAspect);
-            this.targetDb.elements.updateAspect({
+            const targetAspectProps = await this.onTransformElementAspect(sourceAspect);
+            this._targetEditTxn.updateAspect({
                 ...targetAspectProps,
                 id: targetAspectId,
             });
         }
     }
-    doAllReferencesExistInTarget(entity) {
+    async doAllReferencesExistInTarget(entity) {
         let allReferencesExist = true;
         for (const referenceId of entity.getReferenceIds()) {
             const referencedEntityId = core_backend_1.EntityReferences.toId64(referenceId);
@@ -971,7 +481,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 continue;
             }
             if (allReferencesExist &&
-                !core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {
+                !core_backend_1.EntityReferences.isValid(await this.context.findTargetEntityId(referenceId))) {
                 // if we care about references existing then we cannot return early and must check all other references.
                 if (this._options.danglingReferencesBehavior === "ignore") {
                     return false;
@@ -979,13 +489,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 allReferencesExist = false;
             }
             if (this._options.danglingReferencesBehavior === "reject") {
-                this.assertReferenceExistsInSource(referenceId, entity);
+                await this.assertReferenceExistsInSource(referenceId, entity);
             }
         }
         return allReferencesExist;
     }
-    assertReferenceExistsInSource(referenceId, entity) {
-        const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
+    async assertReferenceExistsInSource(referenceId, entity) {
+        const referencedExistsInSource = await EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
             entityReference: referenceId,
         });
         if (!referencedExistsInSource) {
@@ -1019,7 +529,7 @@ 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) {
+    async shouldExportElement(_sourceElement) {
         return true;
     }
     /**
@@ -1027,6 +537,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @internal do not call, override or implement this, it will be removed
      */
     async preExportElement(sourceElement) {
+        if (!this.hasElementChanged(sourceElement)) {
+            core_bentley_1.Logger.logTrace(loggerCategory, `Skipping unchanged element (${sourceElement.id}, ${sourceElement.getDisplayLabel()}).`);
+            return;
+        }
         const elemClass = sourceElement.constructor;
         const unresolvedReferences = elemClass.requiredReferenceKeys
             .map((referenceKey) => {
@@ -1061,7 +575,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             .flat();
         if (unresolvedReferences.length > 0) {
             for (const reference of unresolvedReferences) {
-                const processState = this.getElemTransformState(reference);
+                const processState = await this.getElemTransformState(reference);
                 // must export element first
                 if (processState.needsElemImport)
                     await this.exporter.exportElement(reference);
@@ -1070,23 +584,43 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
         }
     }
-    getElemTransformState(elementId) {
-        const dbHasModel = (db, id) => {
+    async getElemTransformState(elementId) {
+        const dbHasModel = async (db, id) => {
             const maybeModelId = core_backend_1.EntityReferences.fromEntityType(id, core_common_1.ConcreteEntityTypes.Model);
             return EntityUnifier_1.EntityUnifier.exists(db, { entityReference: maybeModelId });
         };
-        const isSubModeled = dbHasModel(this.sourceDb, elementId);
+        const isSubModeled = await 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));
+            (!isElemInTarget || !(await dbHasModel(this.targetDb, idOfElemInTarget)));
         return { needsElemImport: !isElemInTarget, needsModelImport };
     }
+    // In iTwin js 5.x Elements.queryElementIdByCode() uses Code class to query id:
+    // https://github.com/iTwin/itwinjs-core/blob/master/core/backend/src/IModelDb.ts#L2779
+    // Code class constructor trims white spaces from code value.
+    // Custom implementation of queryElementIdByCode() was added to support querying elements with code values that have trailing whitespaces.
+    // It mimicks 4.x implementation: https://github.com/iTwin/itwinjs-core/blob/9c8b394ec3878a39764be81f928fd8b0b9115d31/core/backend/src/IModelDb.ts#L1882
+    async queryElementIdByCode(iModel, code) {
+        if (core_bentley_1.Id64.isInvalid(code.spec))
+            throw new Error("Invalid CodeSpec");
+        if (code.value === undefined)
+            throw new Error("Invalid Code");
+        const query = "SELECT ECInstanceId FROM BisCore:Element WHERE CodeSpec.Id=? AND CodeScope.Id=? AND CodeValue=?";
+        const queryBinder = new core_common_1.QueryBinder()
+            .bindId(1, code.spec)
+            .bindId(2, core_bentley_1.Id64.fromString(code.scope))
+            .bindString(3, code.value);
+        const queryReader = iModel.createQueryReader(query, queryBinder, {
+            usePrimaryConn: true,
+        });
+        return (await queryReader.step()) ? queryReader.current[0] : undefined;
+    }
     /** Override of [IModelExportHandler.onExportElement]($transformer) that imports an element into the target iModel when it is exported from the source iModel.
      * This override calls [[onTransformElement]] and then [IModelImporter.importElement]($transformer) to update the target iModel.
      */
-    onExportElement(sourceElement) {
-        let targetElementId;
+    async onExportElement(sourceElement) {
+        let targetElementId = core_bentley_1.Id64.invalid;
         let targetElementProps;
         if (this._options.wasSourceIModelCopiedToTarget) {
             targetElementId = sourceElement.id;
@@ -1095,14 +629,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         else {
             targetElementId = this.context.findTargetElementId(sourceElement.id);
-            targetElementProps = this.onTransformElement(sourceElement);
+            targetElementProps = await 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;
+                this.targetDb.elements.getIdFromFederationGuid(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
         }
@@ -1112,13 +646,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             // 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);
+            const maybeTargetElementId = await this.queryElementIdByCode(this.targetDb, 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
                     targetElementId = maybeTargetElementId;
                     this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found by Code
+                    this._targetElementIdsRemappedByCode.add(targetElementId);
                 }
                 else {
                     targetElementProps.code = core_common_1.Code.createEmpty(); // clear out invalid code
@@ -1129,7 +664,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             core_bentley_1.Logger.logTrace(loggerCategory, `Skipping unchanged element (${sourceElement.id}, ${sourceElement.getDisplayLabel()}).`);
             return;
         }
-        if (!this.doAllReferencesExistInTarget(sourceElement)) {
+        if (!(await this.doAllReferencesExistInTarget(sourceElement))) {
             this._partiallyCommittedElementIds.add(sourceElement.id);
         }
         // targetElementId will be valid (indicating update) or undefined (indicating insert)
@@ -1160,9 +695,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
         }
         if (!this._options.wasSourceIModelCopiedToTarget) {
-            this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
+            await this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
         }
-        this.context.remapElement(sourceElement.id, targetElementProps.id); // targetElementProps.id assigned by importElement
+        if (targetElementProps.id === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps.id should be assigned by importElement");
+        }
+        this.context.remapElement(sourceElement.id, targetElementProps.id);
         // the transformer does not currently 'split' or 'join' any elements, therefore, it does not
         // insert external source aspects because federation guids are sufficient for this.
         // Other transformer subclasses must insert the appropriate aspect (as provided by a TBD API)
@@ -1170,39 +708,43 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         // physical consolidation is an example of a 'joining' transform
         // 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
+        const provenanceDb = await this.getProvenanceDb();
+        const provenanceEditTxn = await this._provenanceManager.getProvenanceEditTxn();
         if (!this._options.noProvenance) {
-            let provenance = this._options.forceExternalSourceAspectProvenance ||
+            const provenance = this._options.forceExternalSourceAspectProvenance ||
                 this._elementsWithExplicitlyTrackedProvenance.has(sourceElement.id)
                 ? undefined
                 : sourceElement.federationGuid;
             if (!provenance) {
-                const aspectProps = this.initElementProvenance(sourceElement.id, targetElementProps.id);
-                const foundEsaProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, aspectProps);
+                const aspectProps = await this.initElementProvenance(sourceElement.id, targetElementProps.id);
+                const foundEsaProps = await ProvenanceManager_1.ProvenanceManager.queryScopeExternalSourceAspect(provenanceDb, aspectProps);
                 if (foundEsaProps === undefined)
-                    aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
+                    aspectProps.id = provenanceEditTxn.insertAspect(aspectProps);
                 else {
                     // 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);
+                    provenanceEditTxn.updateAspect(aspectProps);
                 }
-                provenance = aspectProps;
             }
-            this.markLastProvenance(provenance, { isRelationship: false });
         }
     }
     /** Override of [IModelExportHandler.onDeleteElement]($transformer) that is called when [IModelExporter]($transformer) detects that an Element has been deleted from the source iModel.
      * This override propagates the delete to the target iModel via [IModelImporter.deleteElement]($transformer).
      */
-    onDeleteElement(sourceElementId) {
+    async onDeleteElement(sourceElementId) {
         const targetElementId = this.context.findTargetElementId(sourceElementId);
         if (core_bentley_1.Id64.isValidId64(targetElementId)) {
-            this.importer.deleteElement(targetElementId);
+            // Skip deletion if new / updated source element was remapped to it by Code during
+            // this transformation pass.
+            if (!this._targetElementIdsRemappedByCode.has(targetElementId)) {
+                await this.importer.deleteElement(targetElementId);
+            }
         }
     }
     /** Override of [IModelExportHandler.onExportModel]($transformer) that is called when a Model should be exported from the source iModel.
      * This override calls [[onTransformModel]] and then [IModelImporter.importModel]($transformer) to update the target iModel.
      */
-    onExportModel(sourceModel) {
+    async onExportModel(sourceModel) {
         if (this._options.skipPropagateChangesToRootElements &&
             core_common_1.IModel.repositoryModelId === sourceModel.id)
             return; // The RepositoryModel should not be directly imported
@@ -1213,16 +755,27 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (isRemappedRootSubject)
             return;
         const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
-        this.importer.importModel(targetModelProps);
+        await this.importer.importModel(targetModelProps);
+        if (targetModelProps.id === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadModel, "targetModelProps.id should be assigned by now");
+        }
+        this._targetModelsImportedInCurrentTransform.add(targetModelProps.id);
     }
     /** Override of [IModelExportHandler.onDeleteModel]($transformer) that is called when [IModelExporter]($transformer) detects that a [Model]($backend) has been deleted from the source iModel. */
-    onDeleteModel(sourceModelId) {
+    async onDeleteModel(sourceModelId) {
         // It is possible and apparently occasionally sensical to delete a model without deleting its underlying element.
         // - If only the model is deleted, [[initFromExternalSourceAspects]] will have already remapped the underlying element since it still exists.
         // - If both were deleted, [[remapDeletedSourceEntities]] will find and remap the deleted element making this operation valid
         const targetModelId = this.context.findTargetElementId(sourceModelId);
         if (!core_bentley_1.Id64.isValidId64(targetModelId))
             return;
+        // This handles cases where model with a partition element was remapped to
+        //  new element by code value after recreation.
+        if (this._targetElementIdsRemappedByCode.has(targetModelId) &&
+            this._targetModelsImportedInCurrentTransform.has(targetModelId)) {
+            core_bentley_1.Logger.logTrace(loggerCategory, `Skipping delete operation for model (source id: ${sourceModelId}) because the target model (id: ${targetModelId}) was remapped by Code and re-imported during this transformation pass.`);
+            return;
+        }
         const sql = `
       SELECT 1
       FROM bis.DefinitionPartition
@@ -1233,19 +786,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
       WHERE ECInstanceId=:targetModelId
     `;
         if (this.exporter.sourceDbChanges?.element.deleteIds.has(sourceModelId)) {
-            // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-            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: '${JSON.stringify(stmt)}'`);
-                }
+            const params = new core_common_1.QueryBinder().bindId("targetModelId", targetModelId);
+            const reader = this.targetDb.createQueryReader(sql, params, {
+                usePrimaryConn: true,
             });
+            const isDefinitionPartition = await reader.step();
             if (isDefinitionPartition) {
                 // Skipping model deletion because model's partition will also be deleted.
                 // It expects that model will be present and will fail if it's missing.
@@ -1254,7 +799,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
         }
         try {
-            this.importer.deleteModel(targetModelId);
+            await this.importer.deleteModel(targetModelId);
         }
         catch (error) {
             const isDeletionProhibitedErr = error instanceof core_common_1.IModelError &&
@@ -1301,41 +846,24 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         await this.initialize();
         // import DefinitionModels first
         const childDefinitionPartitionSql = `SELECT ECInstanceId FROM ${core_backend_1.DefinitionPartition.classFullName} WHERE Parent.Id=:subjectId`;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        await this.sourceDb.withPreparedStatement(childDefinitionPartitionSql, 
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        async (statement) => {
-            statement.bindId("subjectId", sourceSubjectId);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                await this.processModel(statement.getValue(0).getId());
-            }
-        });
+        const params = new core_common_1.QueryBinder().bindId("subjectId", sourceSubjectId);
+        for await (const row of this.sourceDb.createQueryReader(childDefinitionPartitionSql, params, { usePrimaryConn: true })) {
+            await this.processModel(row.id);
+        }
         // import other partitions next
         const childPartitionSql = `SELECT ECInstanceId FROM ${core_backend_1.InformationPartitionElement.classFullName} WHERE Parent.Id=:subjectId`;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        await this.sourceDb.withPreparedStatement(childPartitionSql, 
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        async (statement) => {
-            statement.bindId("subjectId", sourceSubjectId);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const modelId = statement.getValue(0).getId();
-                const model = this.sourceDb.models.getModel(modelId);
-                if (!(model instanceof core_backend_1.DefinitionModel)) {
-                    await this.processModel(modelId);
-                }
+        for await (const row of this.sourceDb.createQueryReader(childPartitionSql, params, { usePrimaryConn: true })) {
+            const modelId = row.id;
+            const model = this.sourceDb.models.getModel(modelId);
+            if (!(model instanceof core_backend_1.DefinitionModel)) {
+                await this.processModel(modelId);
             }
-        });
+        }
         // recurse into child Subjects
         const childSubjectSql = `SELECT ECInstanceId FROM ${core_backend_1.Subject.classFullName} WHERE Parent.Id=:subjectId`;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        await this.sourceDb.withPreparedStatement(childSubjectSql, 
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        async (statement) => {
-            statement.bindId("subjectId", sourceSubjectId);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                await this.processSubjectSubModels(statement.getValue(0).getId());
-            }
-        });
+        for await (const row of this.sourceDb.createQueryReader(childSubjectSql, params, { usePrimaryConn: true })) {
+            await this.processSubjectSubModels(row.id);
+        }
     }
     /** Transform the specified sourceModel into ModelProps for the target iModel.
      * @param sourceModel The Model from the source iModel to be transformed.
@@ -1351,100 +879,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             id: targetModeledElementId,
         };
         targetModelProps.id = targetModeledElementId;
+        if (targetModelProps.parentModel === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps must have a defined parentModel");
+        }
         targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
         return targetModelProps;
     }
-    /**
-     * Called at the end of a transformation,
-     * updates the target scope element to say that transformation up through the
-     * source's changeset has been performed. Also stores all changesets that occurred
-     * during the transformation as "pending synchronization changeset indices" @see TargetScopeProvenanceJsonProps
-     *
-     * You generally should not call this function yourself and use [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided instead.
-     * It is public for unsupported use cases of custom synchronization transforms.
-     * @note If [[IModelTransformOptions.argsForProcessChanges]] is not defined in this transformation, this function will return early without updating the sync version,
-     * unless the `initializeReverseSyncVersion` option is set to `true`
-     *
-     * The `initializeReverseSyncVersion` is added to set the reverse synchronization version during a forward synchronization.
-     * When set to `true`, it saves the reverse sync version as the current changeset of the targetDb. This is typically used for the first transformation between a master and branch iModel.
-     * Setting `initializeReverseSyncVersion` to `true` has the effect of making it so any changesets in the branch iModel at the time of the first transformation will be ignored during any future reverse synchronizations from the branch to the master iModel.
-     *
-     * Note that typically, the reverseSyncVersion is saved as the last changeset merged from the branch into master.
-     * Setting initializeReverseSyncVersion to true during a forward transformation could overwrite this correct reverseSyncVersion and should only be done during the first transformation between a master and branch iModel.
-     */
-    updateSynchronizationVersion({ initializeReverseSyncVersion = false, } = {}) {
-        const shouldSkipSyncVersionUpdate = !initializeReverseSyncVersion &&
-            this._sourceChangeDataState !== "has-changes";
-        if (shouldSkipSyncVersionUpdate)
-            return;
-        nodeAssert(this._targetScopeProvenanceProps);
-        const sourceVersion = `${this.sourceDb.changeset.id};${this.sourceDb.changeset.index}`;
-        const targetVersion = `${this.targetDb.changeset.id};${this.targetDb.changeset.index}`;
-        if (this.isReverseSynchronization) {
-            const oldVersion = this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion;
-            core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse version from ${oldVersion} to ${sourceVersion}`);
-            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
-                sourceVersion;
-        }
-        else {
-            core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${this._targetScopeProvenanceProps.version} to ${sourceVersion}`);
-            this._targetScopeProvenanceProps.version = sourceVersion;
-            // save reverse sync version
-            if (initializeReverseSyncVersion) {
-                core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse sync version from ${this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion} to ${targetVersion}`);
-                this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
-                    targetVersion;
-            }
-        }
-        if (this._options.argsForProcessChanges ||
-            (this._startingChangesetIndices && initializeReverseSyncVersion)) {
-            nodeAssert(this.targetDb.changeset.index !== undefined &&
-                this._startingChangesetIndices !== undefined, "updateSynchronizationVersion was called without change history");
-            const jsonProps = this._targetScopeProvenanceProps.jsonProperties;
-            core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingReverseSyncChanges: ${jsonProps.pendingReverseSyncChangesetIndices}`);
-            core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingSyncChanges: ${jsonProps.pendingSyncChangesetIndices}`);
-            const pendingSyncChangesetIndicesKey = "pendingSyncChangesetIndices";
-            const pendingReverseSyncChangesetIndicesKey = "pendingReverseSyncChangesetIndices";
-            // Determine which keys to clear and update based on the synchronization direction
-            let syncChangesetsToClearKey;
-            let syncChangesetsToUpdateKey;
-            if (this.isReverseSynchronization) {
-                syncChangesetsToClearKey = pendingReverseSyncChangesetIndicesKey;
-                syncChangesetsToUpdateKey = pendingSyncChangesetIndicesKey;
-            }
-            else {
-                syncChangesetsToClearKey = pendingSyncChangesetIndicesKey;
-                syncChangesetsToUpdateKey = pendingReverseSyncChangesetIndicesKey;
-            }
-            // NOTE that as documented in [[processChanges]], this assumes that right after
-            // transformation finalization, the work will be saved immediately, otherwise we've
-            // just marked this changeset as a synchronization to ignore, and the user can add other
-            // stuff to it which would break future synchronizations
-            for (let i = this._startingChangesetIndices.target + 1; i <= this.targetDb.changeset.index + 1; i++)
-                jsonProps[syncChangesetsToUpdateKey].push(i);
-            // Only keep the changeset indices which are greater than the source, this means they haven't been processed yet.
-            jsonProps[syncChangesetsToClearKey] = jsonProps[syncChangesetsToClearKey].filter((csIndex) => {
-                return csIndex > this._startingChangesetIndices.source;
-            });
-            // if reverse sync then we may have received provenance changes which should be marked as sync changes
-            if (this.isReverseSynchronization) {
-                nodeAssert(this.sourceDb.changeset.index !== undefined, "changeset didn't exist");
-                for (let i = this._startingChangesetIndices.source + 1; i <= this.sourceDb.changeset.index + 1; i++)
-                    jsonProps.pendingReverseSyncChangesetIndices.push(i);
-            }
-            core_bentley_1.Logger.logTrace(loggerCategory, `new pendingReverseSyncChanges: ${jsonProps.pendingReverseSyncChangesetIndices}`);
-            core_bentley_1.Logger.logTrace(loggerCategory, `new pendingSyncChanges: ${jsonProps.pendingSyncChangesetIndices}`);
-        }
-        this.provenanceDb.elements.updateAspect({
-            ...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() {
+    async finalizeTransformation() {
         this.importer.finalize();
-        this.updateSynchronizationVersion({
+        await this.updateSynchronizationVersion({
             initializeReverseSyncVersion: this._isProvenanceInitTransform,
         });
         // TODO: ignore if we remove change cache usage
@@ -1471,38 +915,39 @@ 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) {
+    async 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.
      */
-    onExportRelationship(sourceRelationship) {
-        const sourceFedGuid = queryElemFedGuid(this.sourceDb, sourceRelationship.sourceId);
-        const targetFedGuid = queryElemFedGuid(this.sourceDb, sourceRelationship.targetId);
+    async onExportRelationship(sourceRelationship) {
+        const sourceFedGuid = this.sourceDb.elements.getFederationGuidFromId(sourceRelationship.sourceId);
+        const targetFedGuid = this.sourceDb.elements.getFederationGuidFromId(sourceRelationship.targetId);
         const targetRelationshipProps = this.onTransformRelationship(sourceRelationship);
-        const targetRelationshipInstanceId = this.importer.importRelationship(targetRelationshipProps);
+        const targetRelationshipInstanceId = await this.importer.importRelationship(targetRelationshipProps);
+        const provenanceDb = await this.getProvenanceDb();
+        const provenanceEditTxn = await this._provenanceManager.getProvenanceEditTxn();
         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);
-                const foundEsaProps = IModelTransformer.queryScopeExternalSourceAspect(this.provenanceDb, aspectProps);
+            const needsEsaProvenance = !this._options
+                .forceExternalSourceAspectProvenance
+                ? !(sourceFedGuid && targetFedGuid)
+                : true;
+            if (needsEsaProvenance) {
+                const aspectProps = await this._provenanceManager.initRelationshipProvenance(sourceRelationship.id, targetRelationshipInstanceId, this._forceOldRelationshipProvenanceMethod);
+                const foundEsaProps = await ProvenanceManager_1.ProvenanceManager.queryScopeExternalSourceAspect(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);
+                    aspectProps.id = provenanceEditTxn.insertAspect(aspectProps);
                 }
-                provenance = aspectProps;
             }
-            this.markLastProvenance(provenance, { isRelationship: true });
         }
     }
     /** Override of [IModelExportHandler.onDeleteRelationship]($transformer) that is called when [IModelExporter]($transformer) detects that a [Relationship]($backend) has been deleted from the source iModel.
      * This override propagates the delete to the target iModel via [IModelImporter.deleteRelationship]($transformer).
      */
-    onDeleteRelationship(sourceRelInstanceId) {
+    async onDeleteRelationship(sourceRelInstanceId) {
         nodeAssert(this._deletedSourceRelationshipData, "should be defined at initialization by now");
         const deletedRelData = this._deletedSourceRelationshipData.get(sourceRelInstanceId);
         if (!deletedRelData) {
@@ -1516,14 +961,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 targetId: deletedRelData.targetIdInTarget,
             })?.id;
         if (id) {
-            this.importer.deleteRelationship({
+            await this.importer.deleteRelationship({
                 id,
                 classFullName: deletedRelData.classFullName,
             });
         }
         if (deletedRelData.provenanceAspectId) {
             try {
-                this.provenanceDb.elements.deleteAspect(deletedRelData.provenanceAspectId);
+                (await this._provenanceManager.getProvenanceEditTxn()).deleteAspect(deletedRelData.provenanceAspectId);
             }
             catch (error) {
                 // This aspect may no longer exist if it was deleted at some other point during the transformation. This is fine.
@@ -1534,51 +979,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
     }
     _yieldManager = new core_bentley_1.YieldManager();
-    /** Detect Relationship deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against relationships in the source iModel.
-     * @deprecated in 1.x. Don't use this anymore
-     * @see [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided.
-     * @note This method is called from [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are undefined, so it only needs to be called directly when processing a subset of an iModel.
-     * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
-     */
-    async detectRelationshipDeletes() {
-        if (this.isReverseSynchronization) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
-        }
-        const aspectDeleteIds = [];
-        const sql = `
-      SELECT ECInstanceId, Identifier, JsonProperties
-      FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect
-      WHERE aspect.Scope.Id=:scopeId
-        AND aspect.Kind=:kind
-    `;
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        await this.targetDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-        async (statement) => {
-            statement.bindId("scopeId", this.targetScopeElementId);
-            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)) {
-                    // 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());
-                    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());
-                }
-                await this._yieldManager.allowYield();
-            }
-        });
-        this.targetDb.elements.deleteAspect(aspectDeleteIds);
-    }
     /** Transform the specified sourceRelationship into RelationshipProps for the target iModel.
      * @param sourceRelationship The Relationship from the source iModel to be transformed.
      * @returns RelationshipProps for the target iModel.
@@ -1589,16 +989,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         targetRelationshipProps.sourceId = this.context.findTargetElementId(sourceRelationship.sourceId);
         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]);
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- forEach deprecated in core 5.10, migration tracked separately
+        sourceRelationship.forEach((propertyName, property) => {
+            if (property.isPrimitive() && "Id" === property.extendedTypeName) {
+                targetRelationshipProps[core_common_1.ECJsNames.toJsName(propertyName)] =
+                    this.context.findTargetElementId(sourceRelationship.asAny[core_common_1.ECJsNames.toJsName(propertyName)]);
             }
         });
         return targetRelationshipProps;
     }
-    shouldExportElementAspect(aspect) {
+    async shouldExportElementAspect(aspect) {
         // This override is needed to ensure that aspects are not exported if their element is not exported.
         // This is needed in case DetachedExportElementAspectsStrategy is used.
         return this.context.findTargetElementId(aspect.element.id) !== core_bentley_1.Id64.invalid;
@@ -1606,28 +1006,28 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Override of [IModelExportHandler.onExportElementUniqueAspect]($transformer) that imports an ElementUniqueAspect into the target iModel when it is exported from the source iModel.
      * This override calls [[onTransformElementAspect]] and then [IModelImporter.importElementUniqueAspect]($transformer) to update the target iModel.
      */
-    onExportElementUniqueAspect(sourceAspect) {
-        const targetAspectProps = this.onTransformElementAspect(sourceAspect);
-        if (!this.doAllReferencesExistInTarget(sourceAspect)) {
+    async onExportElementUniqueAspect(sourceAspect) {
+        const targetAspectProps = await this.onTransformElementAspect(sourceAspect);
+        if (!(await this.doAllReferencesExistInTarget(sourceAspect))) {
             this._partiallyCommittedAspectIds.add(sourceAspect.id);
         }
-        const targetId = this.importer.importElementUniqueAspect(targetAspectProps);
+        const targetId = await this.importer.importElementUniqueAspect(targetAspectProps);
         this.context.remapElementAspect(sourceAspect.id, targetId);
     }
     /** Override of [IModelExportHandler.onExportElementMultiAspects]($transformer) that imports ElementMultiAspects into the target iModel when they are exported from the source iModel.
      * This override calls [[onTransformElementAspect]] for each ElementMultiAspect and then [IModelImporter.importElementMultiAspects]($transformer) to update the target iModel.
      * @note ElementMultiAspects are handled as a group to make it easier to differentiate between insert, update, and delete.
      */
-    onExportElementMultiAspects(sourceAspects) {
+    async onExportElementMultiAspects(sourceAspects) {
         // Transform source ElementMultiAspects into target ElementAspectProps
-        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA));
-        sourceAspects.forEach((a) => {
-            if (!this.doAllReferencesExistInTarget(a)) {
+        const targetAspectPropsArray = sourceAspects.map(async (srcA) => this.onTransformElementAspect(srcA));
+        for (const a of sourceAspects) {
+            if (!(await this.doAllReferencesExistInTarget(a))) {
                 this._partiallyCommittedAspectIds.add(a.id);
             }
-        });
+        }
         // const targetAspectsToImport = targetAspectPropsArray.filter((targetAspect, i) => hasEntityChanged(sourceAspects[i], targetAspect));
-        const targetIds = this.importer.importElementMultiAspects(targetAspectPropsArray, (a) => {
+        const targetIds = await this.importer.importElementMultiAspects(await Promise.all(targetAspectPropsArray), (a) => {
             const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect &&
                 a.scope?.id === this.targetScopeElementId;
             return (!this._options.includeSourceProvenance ||
@@ -1642,8 +1042,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @returns ElementAspectProps for the target iModel.
      * @note A subclass can override this method to provide custom transform behavior.
      */
-    onTransformElementAspect(sourceElementAspect) {
-        const targetElementAspectProps = this.context.cloneElementAspect(sourceElementAspect);
+    async onTransformElementAspect(sourceElementAspect) {
+        const targetElementAspectProps = await this.context.cloneElementAspect(sourceElementAspect);
         return targetElementAspectProps;
     }
     /** The directory where schemas will be exported, a random temporary directory */
@@ -1651,7 +1051,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Override of [IModelExportHandler.shouldExportSchema]($transformer) that is called to determine if a schema should be exported
      * @note the default behavior doesn't import schemas older than those already in the target
      */
-    shouldExportSchema(schemaKey) {
+    async shouldExportSchema(schemaKey) {
         const versionInTarget = this.targetDb.querySchemaVersion(schemaKey.name);
         if (versionInTarget === undefined)
             return true;
@@ -1685,7 +1085,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             nodeAssert(schemaFileName.length <= systemMaxPathSegmentSize, "Schema name was still long. This is a bug.");
             this._longNamedSchemasMap.set(schema.name, schemaFileName);
         }
-        /* eslint-disable-next-line deprecation/deprecation */
         this.sourceDb.exportSchema({
             schemaName: schema.name,
             outputDirectory: this._schemaExportDir,
@@ -1738,7 +1137,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         return this.exporter.exportFonts();
     }
     /** Override of [IModelExportHandler.onExportFont]($transformer) that imports a font into the target iModel when it is exported from the source iModel. */
-    onExportFont(font, _isUpdate) {
+    async onExportFont(font, _isUpdate) {
         this.context.importFont(font.id);
     }
     /** Cause all CodeSpecs to be exported from the source iModel and imported into the target iModel.
@@ -1758,11 +1157,11 @@ 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) {
+    async 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) {
+    async onExportCodeSpec(sourceCodeSpec) {
         this.context.importCodeSpec(sourceCodeSpec.id);
     }
     /** Recursively import all Elements and sub-Models that descend from the specified Subject */
@@ -1773,8 +1172,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.remapElement(sourceSubjectId, targetSubjectId);
         await this.processChildElements(sourceSubjectId);
         await this.processSubjectSubModels(sourceSubjectId);
-        this.completePartiallyCommittedElements();
-        this.completePartiallyCommittedAspects();
+        await this.completePartiallyCommittedElements();
+        await this.completePartiallyCommittedAspects();
     }
     /** state to prevent reinitialization, @see [[initialize]] */
     _initialized = false;
@@ -1790,11 +1189,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async initialize() {
         if (this._initialized)
             return;
-        this.initScopeProvenance();
+        this.assertEditTxnActive();
+        await this.initScopeProvenance();
         await this._tryInitChangesetData(this._options.argsForProcessChanges);
         await this.context.initialize();
         // need exporter initialized to do remapdeletedsourceentities.
-        await this.exporter.initialize(this.getExportInitOpts(this._options.argsForProcessChanges ?? {}));
+        await this.exporter.initialize(await this.getExportInitOpts(this._options.argsForProcessChanges ?? {}));
         // Exporter must be initialized prior to processing changesets in order to properly handle entity recreations (an entity delete followed by an insert of that same entity).
         await this.processChangesets();
         this._initialized = true;
@@ -1806,7 +1206,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @returns void
      */
     async processChangesets() {
-        this.forEachTrackedElement((sourceElementId, targetElementId) => {
+        await this._provenanceManager.forEachTrackedElement((sourceElementId, targetElementId) => {
             this.context.remapElement(sourceElementId, targetElementId);
         });
         if (this.exporter.sourceDbChanges)
@@ -1820,11 +1220,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 this._sourceChangeDataState = "has-changes";
         }
         const relationshipECClassIdsToSkip = new Set();
-        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)")) {
+        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)", undefined, { usePrimaryConn: true })) {
             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)")) {
+        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementRefersToElements)", undefined, { usePrimaryConn: true })) {
             relationshipECClassIds.add(row.ECInstanceId);
         }
         // For later use when processing deletes.
@@ -1842,18 +1242,23 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         });
         this._deletedSourceRelationshipData = new Map();
         for (const csFile of this._csFileProps ?? []) {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             const csReader = core_backend_1.SqliteChangesetReader.openFile({
                 fileName: csFile.pathname,
                 db: this.sourceDb,
                 disableSchemaCheck: true,
             });
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             const csAdaptor = new core_backend_1.ChangesetECAdaptor(csReader);
-            const ecChangeUnifier = new core_backend_1.PartialECChangeUnifier();
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            const ecChangeUnifier = new core_backend_1.PartialECChangeUnifier(this.sourceDb);
             while (csAdaptor.step()) {
                 ecChangeUnifier.appendFrom(csAdaptor);
             }
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             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 */
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             const elemIdToScopeEsa = new Map();
             for (const change of changes) {
                 if (change.ECClassId !== undefined &&
@@ -1903,10 +1308,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
      * @returns void
      */
-    async processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
+    async processDeletedOp(
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    change, 
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
         // we need a connected iModel with changes to remap elements with deletions
         const notConnectedModel = this.sourceDb.iTwinId === undefined;
-        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index &&
+        const noChanges = (await this.getSynchronizationVersion()).index ===
+            this.sourceDb.changeset.index &&
             (this.exporter.sourceDbChanges === undefined ||
                 !this.exporter.sourceDbChanges.hasChanges);
         if (notConnectedModel || noChanges)
@@ -1915,7 +1325,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
          * 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 changeDataInProvenanceDb = this.sourceDb === (await this.getProvenanceDb());
         const getTargetIdFromSourceId = async (id) => {
             let identifierValue;
             let element;
@@ -1931,7 +1341,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     this.targetScopeElementId,
                     core_backend_1.ExternalSourceAspect.Kind.Element,
                     id,
-                ]))) {
+                ]), { usePrimaryConn: true })) {
                     identifierValue = row.Identifier;
                 }
                 identifierValue =
@@ -1944,7 +1354,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
             // Check for targetId using sourceId's fedguid if we didn't find an esa.
             if (fedGuid) {
-                const targetId = this._queryElemIdByFedGuid(this.targetDb, fedGuid);
+                const targetId = this.targetDb.elements.getIdFromFederationGuid(fedGuid);
                 return targetId;
             }
             return undefined;
@@ -1957,20 +1367,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             const sourceIdOfRelationshipInTarget = await getTargetIdFromSourceId(sourceIdOfRelationshipInSource);
             const targetIdOfRelationshipInTarget = await getTargetIdFromSourceId(targetIdOfRelationshipInSource);
             if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
-                this._deletedSourceRelationshipData.set(changedInstanceId, {
+                this._deletedSourceRelationshipData?.set(changedInstanceId, {
                     classFullName: classFullName ?? "",
                     sourceIdInTarget: sourceIdOfRelationshipInTarget,
                     targetIdInTarget: targetIdOfRelationshipInTarget,
                 });
             }
-            else if (this.sourceDb === this.provenanceSourceDb) {
-                const relProvenance = this._queryProvenanceForRelationship(changedInstanceId, {
+            else if (this.sourceDb ===
+                (await this._provenanceManager.getProvenanceSourceDb())) {
+                const relProvenance = await this._provenanceManager.queryProvenanceForRelationship(changedInstanceId, {
                     classFullName: classFullName ?? "",
                     sourceId: sourceIdOfRelationshipInSource,
                     targetId: targetIdOfRelationshipInSource,
                 });
                 if (relProvenance && relProvenance.relationshipId)
-                    this._deletedSourceRelationshipData.set(changedInstanceId, {
+                    this._deletedSourceRelationshipData?.set(changedInstanceId, {
                         classFullName: classFullName ?? "",
                         relId: relProvenance.relationshipId,
                         provenanceAspectId: relProvenance.aspectId,
@@ -1979,14 +1390,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         else {
             let targetId = await getTargetIdFromSourceId(changedInstanceId);
-            if (targetId === undefined && this.sourceDb === this.provenanceSourceDb) {
-                targetId = this._queryProvenanceForElement(changedInstanceId);
+            if (targetId === undefined &&
+                this.sourceDb ===
+                    (await this._provenanceManager.getProvenanceSourceDb())) {
+                targetId =
+                    await this._provenanceManager.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;
+            if (targetId === undefined) {
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetId should be acquired from source id or element provenance");
+            }
             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.
@@ -2005,7 +1422,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this._sourceChangeDataState = "unconnected";
             return;
         }
-        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index;
+        const syncVersion = await this.getSynchronizationVersion();
+        const noChanges = syncVersion.index === this.sourceDb.changeset.index;
         if (noChanges) {
             this._sourceChangeDataState = "no-changes";
             this._csFileProps = [];
@@ -2014,38 +1432,28 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const startChangeset = "startChangeset" in args ? args.startChangeset : undefined;
         // NOTE: that we do NOT download the changesummary for the last transformed version, we want
         // to ignore those already processed changes
-        const startChangesetIndexOrId = startChangeset?.index ??
-            startChangeset?.id ??
-            this.synchronizationVersion.index + 1;
+        const startChangesetIndexOrId = startChangeset?.index ?? startChangeset?.id ?? syncVersion.index + 1;
         const endChangesetId = this.sourceDb.changeset.id;
         const [startChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetIndexOrId, endChangesetId].map(async (indexOrId) => typeof indexOrId === "number"
             ? indexOrId
-            : core_backend_1.BriefcaseManager
-                .queryChangeset({
+            : core_backend_1.BriefcaseManager.queryChangeset({
                 iModelId: this.sourceDb.iModelId,
-                // eslint-disable-next-line deprecation/deprecation
                 changeset: { id: indexOrId },
-            })
-                .then((changeset) => changeset.index)));
-        const missingChangesets = startChangesetIndex > this.synchronizationVersion.index + 1;
+            }).then((changeset) => changeset.index)));
+        const missingChangesets = startChangesetIndex > syncVersion.index + 1;
         if (!this._options.argsForProcessChanges
             ?.ignoreMissingChangesetsInSynchronizations &&
-            startChangesetIndex !== this.synchronizationVersion.index + 1 &&
-            this.synchronizationVersion.index !== -1) {
+            startChangesetIndex !== syncVersion.index + 1 &&
+            syncVersion.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;
+                ` but the previous synchronization for this targetScopeElem ${syncVersion.id}'` +
+                ` which is changeset #${syncVersion.index}. The transformer expected` +
+                ` #${syncVersion.index + 1}.`);
+        }
+        const changesetsToSkip = await this._provenanceManager.getChangesetsToSkip();
         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}`);
@@ -2064,6 +1472,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._sourceChangeDataState =
             this._csFileProps.length === 0 ? "no-changes" : "has-changes";
     }
+    /** Asserts that the EditTxn is active before any write operations. */
+    assertEditTxnActive() {
+        if (!this._targetEditTxn.isActive) {
+            throw new Error("The target EditTxn must be started before calling process(). Call targetEditTxn.start() before invoking the transformer.");
+        }
+        if (this._sourceEditTxn && !this._sourceEditTxn.isActive) {
+            throw new Error("The source EditTxn was provided but is not active. Call sourceEditTxn.start() before invoking the transformer.");
+        }
+    }
     /**
      * The behavior of process is influenced by [[IModelTransformOptions.argsForProcessChanges]] being defined or not defined during construction passed of the IModelTransformer.
      * @section When argsForProcessChanges are defined:
@@ -2098,6 +1515,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
      */
     async processAll() {
+        this._targetElementIdsRemappedByCode.clear();
+        this._targetModelsImportedInCurrentTransform.clear();
+        // processAll always has changes to process, so mark it as such for version tracking
+        this._sourceChangeDataState = "has-changes";
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
         if (this._options.skipPropagateChangesToRootElements) {
@@ -2109,36 +1530,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         else {
             await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
         }
-        this.completePartiallyCommittedElements();
+        await this.completePartiallyCommittedElements();
         await this.exporter["exportAllAspects"](); // eslint-disable-line @typescript-eslint/dot-notation
-        this.completePartiallyCommittedAspects();
+        await this.completePartiallyCommittedAspects();
         await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
         if (this._options.forceExternalSourceAspectProvenance &&
-            this.shouldDetectDeletes()) {
-            // eslint-disable-next-line deprecation/deprecation
-            await this.detectElementDeletes();
-            // eslint-disable-next-line deprecation/deprecation
-            await this.detectRelationshipDeletes();
+            (await this.shouldDetectDeletes())) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "This workflows was deprecated in v1 and is no longer supported");
         }
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        this.finalizeTransformation();
-    }
-    /** previous provenance, either a federation guid, a `${sourceFedGuid}/${targetFedGuid}` pair, or required aspect props */
-    _lastProvenanceEntityInfo = nullLastProvenanceEntityInfo;
-    markLastProvenance(sourceAspect, { isRelationship = false }) {
-        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,
-                };
+        await this.finalizeTransformation();
     }
     /** 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).
@@ -2150,23 +1553,25 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @note To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired range and open the source iModel as of the end (inclusive) of the desired range.
      */
     async processChanges(options) {
+        this._targetElementIdsRemappedByCode.clear();
+        this._targetModelsImportedInCurrentTransform.clear();
         // must wait for initialization of synchronization provenance data
-        await this.exporter.exportChanges(this.getExportInitOpts(options));
-        this.completePartiallyCommittedElements();
-        this.completePartiallyCommittedAspects();
+        await this.exporter.exportChanges(await this.getExportInitOpts(options));
+        await this.completePartiallyCommittedElements();
+        await this.completePartiallyCommittedAspects();
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        this.finalizeTransformation();
+        await this.finalizeTransformation();
         const defaultSaveTargetChanges = () => {
-            this.targetDb.saveChanges();
+            this._targetEditTxn.saveChanges();
         };
         await (options.saveTargetChanges ?? defaultSaveTargetChanges)(this);
     }
     /** Changeset data must be initialized in order to build correct changeOptions.
      * Call [[IModelTransformer.initialize]] for initialization of synchronization provenance data
      */
-    getExportInitOpts(opts) {
+    async getExportInitOpts(opts) {
         if (!this._options.argsForProcessChanges)
             return {};
         const startChangeset = "startChangeset" in opts ? opts.startChangeset : undefined;
@@ -2180,7 +1585,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                         ? { startChangeset }
                         : {
                             startChangeset: {
-                                index: this.synchronizationVersion.index + 1,
+                                index: (await this.getSynchronizationVersion()).index + 1,
                             },
                         }),
         };
@@ -2207,16 +1612,14 @@ class TemplateModelCloner extends IModelTransformer {
     /** Accumulates the mapping of sourceElementIds to targetElementIds from the elements in the template model that were cloned. */
     _sourceIdToTargetIdMap;
     /** Construct a new TemplateModelCloner
-     * @param sourceDb The source IModelDb that contains the templates to clone
-     * @param targetDb Optionally specify the target IModelDb where the cloned template will be inserted.
-     *                 Typically this is left unspecified, and the default is to use the sourceDb as the target
+     * @param editTxn The [[EditTxn]] to use for all read and write operations. The source and target db are both derived from `editTxn.iModel`. Must be started before constructing.
      * @note The expectation is that the template definitions are within the same iModel where instances will be placed.
      */
-    constructor(sourceDb, targetDb = sourceDb) {
-        const target = new IModelImporter_1.IModelImporter(targetDb, {
+    constructor(editTxn) {
+        const target = new IModelImporter_1.IModelImporter(editTxn, {
             autoExtendProjectExtents: false, // autoExtendProjectExtents is intended for transformation service use cases, not template --> instance cloning
         });
-        super(sourceDb, target, { noProvenance: true }); // WIP: need to decide the proper way to handle provenance
+        super({ source: editTxn.iModel, target }, { noProvenance: true }); // WIP: need to decide the proper way to handle provenance
     }
     /** Place a template from the sourceDb at the specified placement in the target model within the targetDb.
      * @param sourceTemplateModelId The Id of the template model in the sourceDb
@@ -2261,11 +1664,11 @@ class TemplateModelCloner extends IModelTransformer {
         return this._sourceIdToTargetIdMap; // return the sourceElementId -> targetElementId Map in case further post-processing is required.
     }
     /** Cloning from a template requires this override of onTransformElement. */
-    onTransformElement(sourceElement) {
+    async onTransformElement(sourceElement) {
         const referenceIds = sourceElement.getReferenceIds();
-        referenceIds.forEach((referenceId) => {
+        for (const referenceId of referenceIds) {
             // TODO: consider going through all definition elements at once and remapping them to themselves
-            if (!core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {
+            if (!core_backend_1.EntityReferences.isValid(await this.context.findTargetEntityId(referenceId))) {
                 if (this.context.isBetweenIModels) {
                     throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `Remapping for source dependency ${referenceId} not found for target iModel`);
                 }
@@ -2280,8 +1683,8 @@ class TemplateModelCloner extends IModelTransformer {
                     }
                 }
             }
-        });
-        const targetElementProps = super.onTransformElement(sourceElement);
+        }
+        const targetElementProps = await super.onTransformElement(sourceElement);
         targetElementProps.federationGuid = core_bentley_1.Guid.createValue(); // clone from template should create a new federationGuid
         targetElementProps.code = core_common_1.Code.createEmpty(); // clone from template should not maintain codes
         if (sourceElement instanceof core_backend_1.GeometricElement) {
@@ -2294,23 +1697,9 @@ class TemplateModelCloner extends IModelTransformer {
                 targetElementProps.placement = placement;
             }
         }
-        this._sourceIdToTargetIdMap.set(sourceElement.id, core_bentley_1.Id64.invalid); // keep track of (source) elementIds from the template model, but the target hasn't been inserted yet
+        this._sourceIdToTargetIdMap?.set(sourceElement.id, core_bentley_1.Id64.invalid); // keep track of (source) elementIds from the template model, but the target hasn't been inserted yet
         return targetElementProps;
     }
 }
 exports.TemplateModelCloner = TemplateModelCloner;
-function queryElemFedGuid(db, elemId) {
-    // eslint-disable-next-line @itwin/no-internal, deprecation/deprecation
-    return db.withPreparedStatement(`
-    SELECT FederationGuid
-    FROM bis.Element
-    WHERE ECInstanceId=?
-  `, (stmt) => {
-        stmt.bindId(1, elemId);
-        (0, core_bentley_1.assert)(stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW);
-        const result = stmt.getValue(0).getGuid();
-        (0, core_bentley_1.assert)(stmt.step() === core_bentley_1.DbResult.BE_SQLITE_DONE);
-        return result;
-    });
-}
 //# sourceMappingURL=IModelTransformer.js.map