@itwin/imodel-transformer 2.0.0-dev.3 → 2.0.0-dev.30

package/lib/cjs/IModelTransformer.js

@@ -12,6 +12,7 @@ const path = require("path");
 const Semver = require("semver");
 const nodeAssert = require("assert");
 const core_bentley_1 = require("@itwin/core-bentley");
+const ECSchemaMetaData = require("@itwin/ecschema-metadata");
 const core_geometry_1 = require("@itwin/core-geometry");
 const core_backend_1 = require("@itwin/core-backend");
 const core_common_1 = require("@itwin/core-common");
@@ -21,13 +22,11 @@ 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 ChangesetScanner_1 = require("./ChangesetScanner");
+const IModelTransformerError_1 = require("./IModelTransformerError");
 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,
@@ -53,10 +52,16 @@ function mapId64(idContainer, func) {
         results.push(func(idContainer.id));
     }
     else {
-        throw Error([
-            `Id64 container '${JSON.stringify(idContainer)}' is unsupported.`,
-            "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
-        ].join("\n"));
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.InvalidEntityReference,
+            },
+            message: [
+                `Id64 container '${JSON.stringify(idContainer)}' is unsupported.`,
+                "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
+            ].join("\n"),
+        });
     }
     return results;
 }
@@ -86,7 +91,17 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @beta
      */
     _linearSpatialTransform;
-    _syncType;
+    /** 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;
@@ -95,118 +110,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.
+     * 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).
      */
-    _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.";
+    _targetElementIdsRemappedByCode = new Set();
     /**
-     * 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 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 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, @typescript-eslint/no-deprecated
-        return dbToQuery.withPreparedStatement(sql, (statement) => {
-            statement.bindId("elementId", aspectProps.element.id);
-            if (aspectProps.scope === undefined)
-                return undefined; // return instead of binding an invalid id
-            statement.bindId("scopeId", aspectProps.scope.id);
-            statement.bindString("kind", aspectProps.kind);
-            statement.bindString("identifier", aspectProps.identifier);
-            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== statement.step())
-                return undefined;
-            const aspectId = statement.getValue(0).getId();
-            const versionValue = statement.getValue(1);
-            const version = versionValue.isNull
-                ? undefined
-                : versionValue.getString();
-            const jsonPropsValue = statement.getValue(2);
-            const jsonProperties = jsonPropsValue.isNull
-                ? undefined
-                : jsonPropsValue.getString();
-            return { aspectId, version, jsonProperties };
-        });
-    }
-    /**
-     * Determines the sync direction "forward" or "reverse" of a given sourceDb and targetDb by looking for the scoping ESA.
-     * If the sourceDb's iModelId is found as the identifier of the expected scoping ESA in the targetDb, then it is a forward synchronization.
-     * If the targetDb's iModelId is found as the identifier of the expected scoping ESA in the sourceDb, then it is a reverse synchronization.
-     * @throws if no scoping ESA can be found in either the sourceDb or targetDb which describes a master branch relationship between the two databases.
-     * @returns "forward" or "reverse"
-     */
-    static determineSyncType(sourceDb, targetDb, 
-    /** @see [[IModelTransformOptions.targetScopeElementId]] */
-    targetScopeElementId) {
-        const aspectProps = {
-            id: undefined,
-            version: undefined,
-            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
-            element: {
-                id: targetScopeElementId,
-                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
-            },
-            scope: { id: core_common_1.IModel.rootSubjectId }, // the root Subject scopes scope elements
-            identifier: sourceDb.iModelId,
-            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
-            jsonProperties: undefined,
-        };
-        /** First check if the targetDb is the branch (branch is the @see provenanceDb) */
-        const esaPropsFromTargetDb = this.queryScopeExternalSourceAspect(targetDb, aspectProps);
-        if (esaPropsFromTargetDb !== undefined) {
-            return "forward"; // we found an esa assuming targetDb is the provenanceDb/branch so this is a forward sync.
-        }
-        // Now check if the sourceDb is the branch
-        aspectProps.identifier = targetDb.iModelId;
-        const esaPropsFromSourceDb = this.queryScopeExternalSourceAspect(sourceDb, aspectProps);
-        if (esaPropsFromSourceDb !== undefined) {
-            return "reverse"; // we found an esa assuming sourceDb is the provenanceDb/branch so this is a reverse sync.
-        }
-        throw new Error(this.noEsaSyncDirectionErrorMessage);
-    }
-    determineSyncType() {
-        if (this._isProvenanceInitTransform) {
-            return "forward";
-        }
-        if (!this._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.
@@ -215,31 +133,25 @@ 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 @typescript-eslint/no-deprecated
             danglingReferencesBehavior: options?.danglingReferencesBehavior ?? "reject",
             branchRelationshipDataBehavior: options?.branchRelationshipDataBehavior ?? "reject",
             skipPropagateChangesToRootElements: options?.skipPropagateChangesToRootElements ?? true,
@@ -271,7 +183,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,
@@ -282,16 +194,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)) {
@@ -299,6 +205,8 @@ 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) {
@@ -320,19 +228,29 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     validateSharedOptionsMatch() {
         if (Boolean(this._options.preserveElementIdsForFiltering) !==
             this.importer.options.preserveElementIdsForFiltering) {
-            const errMessage = "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.";
-            throw new Error(errMessage);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ImporterOptionMismatch,
+                },
+                message: "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.",
+            });
         }
         if (Boolean(this._options.skipPropagateChangesToRootElements) !==
             this.importer.options.skipPropagateChangesToRootElements) {
-            const errMessage = "A custom importer was passed as a target but its 'skipPropagateChangesToRootElements' option is out of sync with the transformer's option.";
-            throw new Error(errMessage);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ImporterOptionMismatch,
+                },
+                message: "A custom importer was passed as a target but its 'skipPropagateChangesToRootElements' option is out of sync with the transformer's option.",
+            });
         }
     }
     /** 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() {
@@ -349,74 +267,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, @typescript-eslint/no-deprecated
-        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
@@ -425,43 +275,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
@@ -470,448 +285,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, @typescript-eslint/no-deprecated
-            const hasConflictingScope = this.provenanceDb.withPreparedStatement(sql, 
-            // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-            (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, @typescript-eslint/no-deprecated
-        sourceDb.withStatement(elementIdByFedGuidQuery, (sourceStmt) => 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        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,
-            };
-        });
+    async getIsForwardSynchronization() {
+        return (await this._syncTypeResolver.getSyncType()) === "forward";
     }
-    _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, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        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");
-        });
-    }
-    _queryElemIdByFedGuid(db, fedGuid) {
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        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.
@@ -919,9 +345,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);
@@ -964,7 +390,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "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.");
@@ -973,7 +405,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "Failed to invert target ECEF transform.",
+            });
         }
         const ecefTransform = targetECEFToSpatial.multiplyTransformTransform(srcSpatialToECEF); // chain both transforms
         return ecefTransform;
@@ -991,15 +429,33 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemUnavailable,
+                },
+                message: "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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemUnavailable,
+                },
+                message: "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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemMismatch,
+                },
+                message: "Source and target geographic coordinate systems must match to calculate the spatial transform.",
+            });
         }
         if (this.sourceDb.geographicCoordinateSystem.additionalTransform ===
             this.targetDb.geographicCoordinateSystem.additionalTransform) {
@@ -1011,14 +467,26 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemMismatch,
+                },
+                message: "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.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "Failed to invert target Helmert transform.",
+            });
         }
         const combinedTransform = targetTransformInv.multiplyTransformTransform(srcTransform);
         return combinedTransform;
@@ -1028,6 +496,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Returns true if a change within sourceElement is detected.
      * @param sourceElement The Element from the source iModel
      * @note A subclass can override this method to provide custom change detection behavior.
+     * @note During change processing, elements not present in the changeset are short-circuited
+     * in the exporter before reaching this method. To add elements to the changeset programmatically,
+     * use [[addCustomChanges]] rather than overriding this method to expand processing.
      */
     hasElementChanged(sourceElement) {
         const sourceDbChanges = this.exporter.sourceDbChanges;
@@ -1035,7 +506,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,
@@ -1046,25 +517,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);
@@ -1074,7 +545,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;
@@ -1082,22 +553,28 @@ 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) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
-                `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
-                "This must have been caused by an upstream application that changed the iModel.",
-                "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this,",
-                `and the referenceId found on "${entity.id}" will not be carried over to corresponding target element.`,
-            ].join("\n"));
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.DanglingReference,
+                },
+                message: [
+                    `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
+                    "This must have been caused by an upstream application that changed the iModel.",
+                    "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this,",
+                    `and the referenceId found on "${entity.id}" will not be carried over to corresponding target element.`,
+                ].join("\n"),
+            });
         }
     }
     /** Cause the specified Element and its child Elements (if applicable) to be exported from the source iModel and imported into the target iModel.
@@ -1107,7 +584,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async processElement(sourceElementId) {
         await this.initialize();
         if (sourceElementId === core_common_1.IModel.rootSubjectId) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "The root Subject should not be directly imported");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.RootSubjectNotProcessable,
+                },
+                message: "The root Subject should not be directly imported",
+            });
         }
         return this.exporter.exportElement(sourceElementId);
     }
@@ -1122,7 +605,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;
     }
     /**
@@ -1130,6 +613,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) => {
@@ -1164,7 +651,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);
@@ -1173,23 +660,55 @@ 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))
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidCode,
+                },
+                message: "Invalid CodeSpec",
+            });
+        if (code.value === undefined)
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidCode,
+                },
+                message: "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;
@@ -1198,14 +717,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
         }
@@ -1215,13 +734,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
@@ -1232,7 +752,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)
@@ -1243,7 +763,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             const isValid = core_bentley_1.Id64.isValid(targetElementId);
             if (isValid && targetElementId !== sourceElement.id) {
                 // Element found with different id
-                throw new Error(`Element id(${sourceElement.id}) cannot be preserved. Found a different mapping(${targetElementId}) from source element`);
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ElementIdNotPreservable,
+                    },
+                    message: `Element id(${sourceElement.id}) cannot be preserved. Found a different mapping(${targetElementId}) from source element`,
+                });
             }
             else if (isValid && targetElementId === sourceElement.id) {
                 // targetElementId is valid (indicating update)
@@ -1254,7 +780,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 // if we don't find mapping for source element in target(invalid) but another element with source id exists in target
                 if (sourceInTargetElemProps) {
                     // Element id is already taken by another element
-                    throw new Error(`Element id(${sourceElement.id}) cannot be preserved. An unrelated element in the target already uses id: ${sourceElement.id}`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.ElementIdNotPreservable,
+                        },
+                        message: `Element id(${sourceElement.id}) cannot be preserved. An unrelated element in the target already uses id: ${sourceElement.id}`,
+                    });
                 }
                 else {
                     // Element id in target is available to be remapped
@@ -1263,10 +795,10 @@ 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
         }
         if (targetElementProps.id === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps.id should be assigned by importElement");
+            throw new Error("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
@@ -1276,39 +808,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
@@ -1319,16 +855,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 Error("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
@@ -1339,19 +886,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, @typescript-eslint/no-deprecated
-            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.
@@ -1360,7 +899,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 &&
@@ -1407,41 +946,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, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(childDefinitionPartitionSql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(childPartitionSql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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, @typescript-eslint/no-deprecated
-        await this.sourceDb.withPreparedStatement(childSubjectSql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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.
@@ -1458,104 +980,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         };
         targetModelProps.id = targetModeledElementId;
         if (targetModelProps.parentModel === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps must have a defined parentModel");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ParentModelRequired,
+                },
+                message: "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");
-            // Store in a local variable, so typescript knows it's defined (due to the assert above)
-            const startingChangesetIndices = this._startingChangesetIndices;
-            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 = 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 > 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 = 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
@@ -1582,38 +1021,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) {
@@ -1627,14 +1067,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.
@@ -1645,51 +1085,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, @typescript-eslint/no-deprecated
-        await this.targetDb.withPreparedStatement(sql, 
-        // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-        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.
@@ -1700,16 +1095,18 @@ 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]);
+        const relationshipClass = sourceRelationship.iModel.schemaContext.getSchemaItemSync(sourceRelationship.schemaItemKey, ECSchemaMetaData.RelationshipClass);
+        (0, core_bentley_1.assert)(relationshipClass !== undefined, `Cannot get metadata for ${sourceRelationship.classFullName}.`);
+        for (const property of relationshipClass.getPropertiesSync()) {
+            const propertyName = property.name;
+            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;
@@ -1717,28 +1114,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 ||
@@ -1753,8 +1150,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 */
@@ -1762,7 +1159,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;
@@ -1796,7 +1193,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 @typescript-eslint/no-deprecated */
         this.sourceDb.exportSchema({
             schemaName: schema.name,
             outputDirectory: this._schemaExportDir,
@@ -1849,7 +1245,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.
@@ -1869,11 +1265,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 */
@@ -1884,14 +1280,15 @@ 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;
     _sourceChangeDataState = "uninited";
     /** length === 0 when _changeDataState = "no-change", length > 0 means "has-changes", otherwise undefined  */
     _csFileProps = undefined;
+    _deletionRecordsByChangeset;
     /**
      * Initialize prerequisites of processing, you must initialize with an [[InitOptions]] if you
      * are intending to process changes. Callers may wish to explicitly call initialize if they need to execute code after initialize but before [[process]] is called.
@@ -1901,15 +1298,37 @@ 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 ?? {}));
+        const exporterInitOptions = await this.getExportInitOpts(this._options.argsForProcessChanges ?? {});
+        await this.initializeChangesetScanAndExporter(exporterInitOptions);
         // 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;
     }
+    async initializeChangesetScanAndExporter(exporterInitOptions) {
+        if (this._csFileProps !== undefined &&
+            this._csFileProps.length > 0 &&
+            this.sourceDb.isBriefcaseDb()) {
+            const changedInstanceIds = this.exporter.sourceDbChanges ??
+                ("changedInstanceIds" in exporterInitOptions
+                    ? exporterInitOptions.changedInstanceIds
+                    : new IModelExporter_1.ChangedInstanceIds(this.sourceDb));
+            this._deletionRecordsByChangeset = await ChangesetScanner_1.ChangesetScanner.scan(this.sourceDb, this._csFileProps, changedInstanceIds, {
+                populateChangedInstanceIds: this.exporter.sourceDbChanges === undefined &&
+                    !("changedInstanceIds" in exporterInitOptions),
+            });
+            await this.exporter.initialize({
+                changedInstanceIds,
+                skipPropagateChangesToRootElements: exporterInitOptions.skipPropagateChangesToRootElements,
+            });
+        }
+        else {
+            await this.exporter.initialize(exporterInitOptions);
+        }
+    }
     /**
      * Reads all the changeset files in the private member of the transformer: _csFileProps
      * and finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
@@ -1917,12 +1336,13 @@ 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)
             await this.addCustomChanges(this.exporter.sourceDbChanges);
-        if (this._csFileProps === undefined || this._csFileProps.length === 0) {
+        const csFileProps = this._csFileProps;
+        if (csFileProps === undefined || csFileProps.length === 0) {
             if (this.exporter.sourceDbChanges === undefined ||
                 !this.exporter.sourceDbChanges.hasChanges)
                 return;
@@ -1930,12 +1350,15 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (this._sourceChangeDataState === "no-changes")
                 this._sourceChangeDataState = "has-changes";
         }
+        const deletionRecordsByChangeset = this._deletionRecordsByChangeset;
+        if (deletionRecordsByChangeset === undefined)
+            return;
         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.
@@ -1952,46 +1375,25 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 alreadyImportedModelInserts.add(targetModelId);
         });
         this._deletedSourceRelationshipData = new Map();
-        for (const csFile of this._csFileProps ?? []) {
-            const csReader = core_backend_1.SqliteChangesetReader.openFile({
-                fileName: csFile.pathname,
-                db: this.sourceDb,
-                disableSchemaCheck: true,
-            });
-            const csAdaptor = new core_backend_1.ChangesetECAdaptor(csReader);
-            const ecChangeUnifier = new core_backend_1.PartialECChangeUnifier(this.sourceDb);
-            while (csAdaptor.step()) {
-                ecChangeUnifier.appendFrom(csAdaptor);
-            }
-            const changes = [...ecChangeUnifier.instances];
+        for (const changes of deletionRecordsByChangeset) {
             /** a map of element ids to this transformation scope's ESA data for that element, in case the ESA is deleted in the target */
             const elemIdToScopeEsa = new Map();
             for (const change of changes) {
-                if (change.ECClassId !== undefined &&
-                    relationshipECClassIdsToSkip.has(change.ECClassId))
+                if (relationshipECClassIdsToSkip.has(change.ecClassId))
                     continue;
-                const changeType = change.$meta?.op;
-                if (changeType === "Deleted" &&
-                    change?.$meta?.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
-                    change.Scope.Id === this.targetScopeElementId &&
-                    change.Kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
-                    elemIdToScopeEsa.set(change.Element.Id, change);
+                if (change.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
+                    change.scopeId === this.targetScopeElementId &&
+                    change.kind === core_backend_1.ExternalSourceAspect.Kind.Element &&
+                    change.elementId !== undefined) {
+                    elemIdToScopeEsa.set(change.elementId, change);
                 }
             }
             // Loop to process deletes.
             for (const change of changes) {
-                const changeType = change.$meta?.op;
-                const ecClassId = change.ECClassId ?? change.$meta?.fallbackClassId;
-                if (ecClassId === undefined)
-                    throw new Error(`ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`);
-                if (changeType === undefined)
-                    throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
-                if (changeType !== "Deleted" ||
-                    relationshipECClassIdsToSkip.has(ecClassId))
+                if (relationshipECClassIdsToSkip.has(change.ecClassId))
                     continue;
-                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
+                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(change.ecClassId), alreadyImportedElementInserts, alreadyImportedModelInserts);
             }
-            csReader.close();
         }
         return;
     }
@@ -2017,16 +1419,17 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
         // we need a connected iModel with changes to remap elements with deletions
         const notConnectedModel = this.sourceDb.iTwinId === undefined;
-        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index &&
+        const noChanges = (await this.getSynchronizationVersion()).index ===
+            this.sourceDb.changeset.index &&
             (this.exporter.sourceDbChanges === undefined ||
                 !this.exporter.sourceDbChanges.hasChanges);
         if (notConnectedModel || noChanges)
             return;
         /**
-         * if our ChangedECInstance is in the provenanceDb, then we can use the ids we find in the ChangedECInstance to query for ESAs.
+         * If the deleted source entity is in the provenanceDb, then we can use its ids 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;
@@ -2035,18 +1438,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
             const fedGuid = isRelationship
                 ? element?.federationGuid
-                : change.FederationGuid;
+                : change.federationGuid;
             if (changeDataInProvenanceDb) {
                 // TODO: clarify what happens if there are multiple (e.g. elements were merged)
                 for await (const row of this.sourceDb.createQueryReader("SELECT esa.Identifier FROM bis.ExternalSourceAspect esa WHERE Scope.Id=:scopeId AND Kind=:kind AND Element.Id=:relatedElementId LIMIT 1", core_common_1.QueryBinder.from([
                     this.targetScopeElementId,
                     core_backend_1.ExternalSourceAspect.Kind.Element,
                     id,
-                ]))) {
+                ]), { usePrimaryConn: true })) {
                     identifierValue = row.Identifier;
                 }
                 identifierValue =
-                    identifierValue ?? mapOfDeletedElemIdToScopeEsas.get(id)?.Identifier;
+                    identifierValue ?? mapOfDeletedElemIdToScopeEsas.get(id)?.identifier;
             }
             // Check for targetId by an esa first
             if (changeDataInProvenanceDb && identifierValue) {
@@ -2055,16 +1458,26 @@ 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;
         };
-        const changedInstanceId = change.ECInstanceId;
+        const changedInstanceId = change.ecInstanceId;
         if (isRelationship) {
-            const sourceIdOfRelationshipInSource = change.SourceECInstanceId;
-            const targetIdOfRelationshipInSource = change.TargetECInstanceId;
-            const classFullName = change.$meta?.classFullName;
+            const sourceIdOfRelationshipInSource = change.sourceECInstanceId;
+            const targetIdOfRelationshipInSource = change.targetECInstanceId;
+            const classFullName = change.classFullName;
+            if (sourceIdOfRelationshipInSource === undefined ||
+                targetIdOfRelationshipInSource === undefined) {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                    },
+                    message: `Relationship deletion ${changedInstanceId} is missing an endpoint.`,
+                });
+            }
             const sourceIdOfRelationshipInTarget = await getTargetIdFromSourceId(sourceIdOfRelationshipInSource);
             const targetIdOfRelationshipInTarget = await getTargetIdFromSourceId(targetIdOfRelationshipInSource);
             if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
@@ -2074,8 +1487,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     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,
@@ -2090,8 +1504,11 @@ 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
@@ -2099,7 +1516,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (deletionNotInTarget)
                 return;
             if (targetId === undefined) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetId should aquired from source id or element provenance");
+                throw new Error("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.
@@ -2119,7 +1536,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 = [];
@@ -2128,36 +1546,34 @@ 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({
                 iModelId: this.sourceDb.iModelId,
-                // eslint-disable-next-line @typescript-eslint/no-deprecated
                 changeset: { id: indexOrId },
             }).then((changeset) => changeset.index)));
-        const missingChangesets = startChangesetIndex > this.synchronizationVersion.index + 1;
+        const missingChangesets = startChangesetIndex > syncVersion.index + 1;
         if (!this._options.argsForProcessChanges
             ?.ignoreMissingChangesetsInSynchronizations &&
-            startChangesetIndex !== this.synchronizationVersion.index + 1 &&
-            this.synchronizationVersion.index !== -1) {
-            throw Error(`synchronization is ${missingChangesets ? "missing changesets" : ""},` +
-                " startChangesetId should be" +
-                " exactly the first changeset *after* the previous synchronization to not miss data." +
-                ` You specified '${startChangesetIndexOrId}' which is changeset #${startChangesetIndex}` +
-                ` but the previous synchronization for this targetScopeElement was '${this.synchronizationVersion.id}'` +
-                ` which is changeset #${this.synchronizationVersion.index}. The transformer expected` +
-                ` #${this.synchronizationVersion.index + 1}.`);
-        }
-        nodeAssert(this._targetScopeProvenanceProps, "_targetScopeProvenanceProps should be set by now");
-        const changesetsToSkip = this.isReverseSynchronization
-            ? this._targetScopeProvenanceProps.jsonProperties
-                .pendingReverseSyncChangesetIndices
-            : this._targetScopeProvenanceProps.jsonProperties
-                .pendingSyncChangesetIndices;
+            startChangesetIndex !== syncVersion.index + 1 &&
+            syncVersion.index !== -1) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.SynchronizationRangeInvalid,
+                },
+                message: `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 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}`);
@@ -2176,6 +1592,27 @@ 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) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.EditTxnNotActive,
+                },
+                message: "The target EditTxn must be started before calling process(). Call targetEditTxn.start() before invoking the transformer.",
+            });
+        }
+        if (this._sourceEditTxn && !this._sourceEditTxn.isActive) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.EditTxnNotActive,
+                },
+                message: "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:
@@ -2210,6 +1647,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) {
@@ -2221,36 +1662,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 @typescript-eslint/no-deprecated
-            await this.detectElementDeletes();
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            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).
@@ -2262,25 +1685,33 @@ 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 {};
+        if ("changedInstanceIds" in opts) {
+            return {
+                changedInstanceIds: opts.changedInstanceIds,
+                skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
+            };
+        }
         const startChangeset = "startChangeset" in opts ? opts.startChangeset : undefined;
         return {
             skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
@@ -2292,7 +1723,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                         ? { startChangeset }
                         : {
                             startChangeset: {
-                                index: this.synchronizationVersion.index + 1,
+                                index: (await this.getSynchronizationVersion()).index + 1,
                             },
                         }),
         };
@@ -2319,16 +1750,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
@@ -2373,13 +1802,19 @@ 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`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.DependencyMappingMissing,
+                        },
+                        message: `Remapping for source dependency ${referenceId} not found for target iModel`,
+                    });
                 }
                 else {
                     const definitionElement = this.sourceDb.elements.tryGetElement(referenceId, core_backend_1.DefinitionElement);
@@ -2388,12 +1823,18 @@ class TemplateModelCloner extends IModelTransformer {
                         this.context.remapElement(referenceId, referenceId); // when in the same iModel, can use existing DefinitionElements without remapping
                     }
                     else {
-                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `Remapping for dependency ${referenceId} not found`);
+                        core_bentley_1.ITwinError.throwError({
+                            iTwinErrorId: {
+                                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                                key: IModelTransformerError_1.IModelTransformerError.DependencyMappingMissing,
+                            },
+                            message: `Remapping for dependency ${referenceId} not found`,
+                        });
                     }
                 }
             }
-        });
-        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) {
@@ -2411,18 +1852,4 @@ class TemplateModelCloner extends IModelTransformer {
     }
 }
 exports.TemplateModelCloner = TemplateModelCloner;
-function queryElemFedGuid(db, elemId) {
-    // eslint-disable-next-line @itwin/no-internal, @typescript-eslint/no-deprecated
-    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