@itwin/imodel-transformer 2.0.0-dev.7 → 2.0.0-dev.71

package/lib/cjs/IModelTransformer.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TemplateModelCloner = exports.IModelTransformer = void 0;
 /*---------------------------------------------------------------------------------------------
@@ -8,10 +41,11 @@ exports.TemplateModelCloner = exports.IModelTransformer = void 0;
 /** @packageDocumentation
  * @module iModels
  */
-const path = require("path");
-const Semver = require("semver");
-const nodeAssert = require("assert");
+const path = __importStar(require("node:path"));
+const Semver = __importStar(require("semver"));
+const node_assert_1 = require("node:assert");
 const core_bentley_1 = require("@itwin/core-bentley");
+const ECSchemaMetaData = __importStar(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");
@@ -19,15 +53,18 @@ const IModelExporter_1 = require("./IModelExporter");
 const IModelImporter_1 = require("./IModelImporter");
 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 SchemaProcessingStrategy_1 = require("./schema-processing/SchemaProcessingStrategy");
+const SchemaProcessingCoordinator_1 = require("./schema-processing/SchemaProcessingCoordinator");
+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,
-};
+/** Key of a relationship's source and target element ids. */
+function relationshipEndpointsKey(sourceId, targetId) {
+    return `${sourceId}|${targetId}`;
+}
 /**
  * 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 +90,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;
 }
@@ -67,6 +110,7 @@ function mapId64(idContainer, func) {
 class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** The IModelExporter that will export from the source iModel. */
     exporter;
+    _schemaProcessingCoordinator;
     /** The IModelImporter that will import into the target iModel. */
     importer;
     /** The normally read-only source iModel.
@@ -75,8 +119,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     sourceDb;
     /** The read/write target iModel. */
     targetDb;
-    /** The IModelTransformContext for this IModelTransformer. */
-    context;
+    /** The supported transformation context for this transformer. */
+    get context() {
+        return this._cloneContext;
+    }
+    /** The clone context used by the transformer implementation. */
+    _cloneContext;
     /** The transform to be applied to the placement of spatial elements
      * This transform should be applied when:
      * - source and target db have different ECEF locations
@@ -86,7 +134,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,132 +153,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 async 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
-    `;
-        // if (aspectProps.scope === undefined) return undefined;
-        // const params = new QueryBinder();
-        // params.bindId("elementId", aspectProps.element.id);
-        // params.bindId("scopeId", aspectProps.scope.id);
-        // params.bindString("kind", aspectProps.kind);
-        // params.bindString("identifier", aspectProps.identifier);
-        // const reader = dbToQuery.createQueryReader(sql, params, {usePrimaryConn: true});
-        // if (await reader.step()) {
-        //   const aspectId = reader.current.id;
-        //   const version = reader.current.version as string | undefined;
-        //   const jsonProperties = reader.current.jsonProperties as string | undefined;
-        //   return { aspectId, version, jsonProperties };
-        // }
-        // return undefined;
-        // 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 async 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 = await 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 = await 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);
-    }
-    async determineSyncType() {
-        if (this._isProvenanceInitTransform) {
-            return "forward";
-        }
-        if (!this._options.argsForProcessChanges) {
-            return "not-sync";
-        }
-        try {
-            return await IModelTransformer.determineSyncType(this.sourceDb, this.targetDb, this.targetScopeElementId);
-        }
-        catch (err) {
-            if (err instanceof Error &&
-                err.message === IModelTransformer.noEsaSyncDirectionErrorMessage &&
-                this._allowNoScopingESA) {
-                return "forward";
-            }
-            throw err;
-        }
-    }
-    async getIsReverseSynchronization() {
-        if (this._syncType === undefined)
-            this._syncType = await this.determineSyncType();
-        return this._syncType === "reverse";
-    }
-    async getIsForwardSynchronization() {
-        if (this._syncType === undefined)
-            this._syncType = await 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.
@@ -229,24 +176,19 @@ 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,
@@ -284,7 +226,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,
@@ -295,23 +237,22 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.validateSharedOptionsMatch();
         }
         this.targetDb = this.importer.targetDb;
+        this._targetEditTxn = this.importer.editTxn;
+        this._sourceEditTxn = options?.sourceEditTxn;
+        this._schemaProcessingCoordinator = new SchemaProcessingCoordinator_1.SchemaProcessingCoordinator({
+            exporter: this.exporter,
+            targetDb: this.targetDb,
+            getSchemaExportDirectory: () => this._schemaExportDir,
+            shouldExportSchema: async (schemaKey) => this.shouldExportSchema(schemaKey),
+            serializeSourceSchema: async (schema) => this.onExportSchema(schema),
+        });
+        this.exporter.elementAspectExportCoordinator.setPreparation(async (excludedClasses, elementIds) => this.prepareElementAspects(excludedClasses, elementIds));
         // 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)) {
-            this.sourceDb.codeValueBehavior = "exact";
-            this.targetDb.codeValueBehavior = "exact";
-        }
-        /* eslint-enable @itwin/no-internal */
+        this._cloneContext = new IModelCloneContext_1.IModelCloneContext(this.sourceDb, this.targetDb);
+        this.importer.registerEntityExistenceCache(this._cloneContext.existenceCache);
+        this.setCodeValueBehavior("exact");
+        this._syncTypeResolver = new SyncTypeResolver_1.SyncTypeResolver(this.sourceDb, this.targetDb, this._options.targetScopeElementId, !!this._isProvenanceInitTransform, !!this._options.argsForProcessChanges);
+        this._provenanceManager = new ProvenanceManager_1.ProvenanceManager(this._options.targetScopeElementId, this._options, this._cloneContext, this._syncTypeResolver, this._targetEditTxn, this._sourceEditTxn);
         if (this._options.tryAlignGeolocation) {
             if (this.sourceDb.geographicCoordinateSystem ||
                 this.targetDb.geographicCoordinateSystem) {
@@ -333,19 +274,31 @@ 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[Symbol.dispose]();
+        this.importer.unregisterEntityExistenceCache(this._cloneContext.existenceCache);
+        this._cloneContext.existenceCache.clear();
+        this._cloneContext[Symbol.dispose]();
     }
     /** Log current settings that affect IModelTransformer's behavior. */
     logSettings() {
@@ -362,79 +315,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]].
-     */
-    async provenanceDb() {
-        return (await this.getIsReverseSynchronization())
-            ? 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]].
-     */
-    async provenanceSourceDb() {
-        return (await this.getIsReverseSynchronization())
-            ? 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 async initRelationshipProvenanceOptions(sourceRelInstanceId, targetRelInstanceId, args) {
-        const provenanceDb = args.isReverseSynchronization
-            ? args.sourceDb
-            : args.targetDb;
-        const aspectIdentifier = args.isReverseSynchronization
-            ? targetRelInstanceId
-            : sourceRelInstanceId;
-        const provenanceRelInstanceId = args.isReverseSynchronization
-            ? sourceRelInstanceId
-            : targetRelInstanceId;
-        const sql = "SELECT SourceECInstanceId FROM bis.ElementRefersToElements WHERE ECInstanceId=?";
-        const params = new core_common_1.QueryBinder().bindId(1, provenanceRelInstanceId);
-        const reader = provenanceDb.createQueryReader(sql, params, {
-            usePrimaryConn: true,
-        });
-        nodeAssert(await reader.step(), "relationship provenance query returned no rows");
-        const elementId = reader.current[0];
-        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
@@ -444,42 +324,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     _forceOldRelationshipProvenanceMethod = false;
     /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
     async initElementProvenance(sourceElementId, targetElementId) {
-        return IModelTransformer.initElementProvenanceOptions(sourceElementId, targetElementId, {
-            isReverseSynchronization: await this.getIsReverseSynchronization(),
-            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.
-     */
-    async initRelationshipProvenance(sourceRelationship, targetRelInstanceId) {
-        return IModelTransformer.initRelationshipProvenanceOptions(sourceRelationship.id, targetRelInstanceId, {
-            sourceDb: this.sourceDb,
-            targetDb: this.targetDb,
-            isReverseSynchronization: await this.getIsReverseSynchronization(),
-            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;
+        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
@@ -488,439 +333,60 @@ 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"
      */
-    async synchronizationVersion() {
-        if (this._cachedSynchronizationVersion === undefined) {
-            const provenanceScopeAspect = await this.tryGetProvenanceScopeAspect();
-            if (!provenanceScopeAspect) {
-                return { index: -1, id: "" }; // first synchronization.
-            }
-            const version = (await this.getIsReverseSynchronization())
-                ? 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.
      */
     async tryGetProvenanceScopeAspect() {
-        const scopeProvenanceAspectProps = await IModelTransformer.queryScopeExternalSourceAspect(await 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: (await this.provenanceSourceDb()).iModelId,
-        });
-        return scopeProvenanceAspectProps !== undefined
-            ? (await this.provenanceDb()).elements.getAspect(scopeProvenanceAspectProps.aspectId)
-            : undefined;
+        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)
      */
     async initScopeProvenance() {
-        const provenanceDb = await this.provenanceDb();
-        const sourceProvenanceDb = await this.provenanceSourceDb();
-        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: sourceProvenanceDb.iModelId,
-            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
-            jsonProperties: undefined,
-        };
-        const foundEsaProps = await IModelTransformer.queryScopeExternalSourceAspect(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
-      `;
-            const params = new core_common_1.QueryBinder();
-            params.bindId("elementId", aspectProps.element.id);
-            params.bindId("scopeId", aspectProps.scope.id); // this scope.id can never be invalid, we create it above
-            params.bindString("kind", aspectProps.kind);
-            const reader = provenanceDb.createQueryReader(sql, params, {
-                usePrimaryConn: true,
-            });
-            const hasConflictingScope = await reader.step();
-            if (hasConflictingScope) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Provenance scope conflict");
-            }
-            if (!this._options.noProvenance) {
-                const id = 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 });
-                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;
+        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 async 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...
-        const sourceReader = sourceDb.createQueryReader(elementIdByFedGuidQuery);
-        const targetReader = targetDb.createQueryReader(elementIdByFedGuidQuery);
-        let hasSourceRow = await sourceReader.step();
-        let hasTargetRow = await targetReader.step();
-        while (hasSourceRow && hasTargetRow) {
-            const sourceFedGuid = sourceReader.current.federationGuid;
-            const targetFedGuid = targetReader.current.federationGuid;
-            if (sourceFedGuid !== undefined &&
-                targetFedGuid !== undefined &&
-                sourceFedGuid === targetFedGuid) {
-                // data flow direction is always sourceDb -> targetDb and it does not depend on where the explicit element provenance is stored
-                args.fn(sourceReader.current.id, targetReader.current.id);
-            }
-            if (targetFedGuid === undefined ||
-                (sourceFedGuid !== undefined && sourceFedGuid >= targetFedGuid)) {
-                hasTargetRow = await targetReader.step();
-            }
-            if (sourceFedGuid === undefined ||
-                (targetFedGuid !== undefined && sourceFedGuid <= targetFedGuid)) {
-                hasSourceRow = await sourceReader.step();
-            }
-        }
-        // 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
-        const runFnInDataFlowDirection = (sourceId, targetId) => args.isReverseSynchronization
-            ? args.fn(sourceId, targetId)
-            : args.fn(targetId, sourceId);
-        const params = new core_common_1.QueryBinder();
-        params.bindId("scopeId", args.targetScopeElementId);
-        params.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
-        const provenanceReader = args.provenanceDb.createQueryReader(provenanceAspectsQuery, params);
-        for await (const row of provenanceReader) {
-            // ExternalSourceAspect.Identifier is of type string
-            const aspectIdentifier = row[0];
-            const elementId = row.id;
-            runFnInDataFlowDirection(elementId, aspectIdentifier);
-        }
-    }
-    async forEachTrackedElement(fn) {
-        return IModelTransformer.forEachTrackedElement({
-            provenanceSourceDb: await this.provenanceSourceDb(),
-            provenanceDb: await this.provenanceDb(),
-            targetScopeElementId: this.targetScopeElementId,
-            isReverseSynchronization: await this.getIsReverseSynchronization(),
-            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.
      */
-    async _queryProvenanceForElement(entityInProvenanceSourceId) {
-        const sql = `
-        SELECT esa.Element.Id
-        FROM Bis.ExternalSourceAspect esa
-        WHERE esa.Kind=?
-          AND esa.Scope.Id=?
-          AND esa.Identifier=?
-      `;
-        const params = new core_common_1.QueryBinder();
-        params.bindString(1, core_backend_1.ExternalSourceAspect.Kind.Element);
-        params.bindId(2, this.targetScopeElementId);
-        params.bindString(3, entityInProvenanceSourceId);
-        const result = (await this.provenanceDb()).createQueryReader(sql, params);
-        if (await result.step()) {
-            return result.current.id;
-        }
-        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.
      */
-    async _queryProvenanceForRelationship(entityInProvenanceSourceId, sourceRelInfo) {
-        const sql = `
-      SELECT
-        ECInstanceId,
-        JSON_EXTRACT(JsonProperties, '$.provenanceRelInstanceId') AS provenanceRelInstId
-      FROM Bis.ExternalSourceAspect
-      WHERE Kind=?
-        AND Scope.Id=?
-        AND Identifier=?
-    `;
-        const params = new core_common_1.QueryBinder();
-        params.bindString(1, core_backend_1.ExternalSourceAspect.Kind.Relationship);
-        params.bindId(2, this.targetScopeElementId);
-        params.bindString(3, entityInProvenanceSourceId);
-        const result = (await this.provenanceDb()).createQueryReader(sql, params);
-        if (await result.step()) {
-            const aspectId = result.current.id;
-            const provenanceRelInstId = result.current.provenanceRelInstId;
-            const provenanceRelInstanceId = provenanceRelInstId !== undefined
-                ? provenanceRelInstId
-                : await this._queryTargetRelId(sourceRelInfo);
-            return {
-                aspectId,
-                relationshipId: provenanceRelInstanceId,
-            };
-        }
-        else
-            return undefined;
-    }
-    async _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
-        const sql = `
-      select ecinstanceid
-      from bis.elementreferstoelements
-      where sourceecinstanceid=?
-        and targetecinstanceid=?
-        and ecclassid=?
-    `;
-        const params = new core_common_1.QueryBinder();
-        params.bindId(1, targetRelInfo.sourceId);
-        params.bindId(2, targetRelInfo.targetId);
-        params.bindId(3, await this._targetClassNameToClassId(sourceRelInfo.classFullName));
-        const result = this.targetDb.createQueryReader(sql, params);
-        if (await result.step())
-            return result.current.id;
-        else
-            return undefined;
-    }
-    _targetClassNameToClassIdCache = new Map();
-    async _targetClassNameToClassId(classFullName) {
-        let classId = this._targetClassNameToClassIdCache.get(classFullName);
-        if (classId === undefined) {
-            classId = await this._getRelClassId(this.targetDb, classFullName);
-            this._targetClassNameToClassIdCache.set(classFullName, classId);
-        }
-        return classId;
+    async getIsForwardSynchronization() {
+        return (await this._syncTypeResolver.getSyncType()) === "forward";
     }
-    // NOTE: this doesn't handle remapped element classes,
-    // but is only used for relationships rn
-    async _getRelClassId(db, classFullName) {
-        const sql = `
-      SELECT c.ECInstanceId
-      FROM ECDbMeta.ECClassDef c
-      JOIN ECDbMeta.ECSchemaDef s ON c.Schema.Id=s.ECInstanceId
-      WHERE s.Name=? AND c.Name=?
-    `;
-        const params = new core_common_1.QueryBinder();
-        const [schemaName, className] = classFullName.indexOf(".") !== -1
-            ? classFullName.split(".")
-            : classFullName.split(":");
-        params.bindString(1, schemaName);
-        params.bindString(2, className);
-        const result = db.createQueryReader(sql, params);
-        if (await result.step())
-            return result.current.id;
-        (0, core_bentley_1.assert)(false, "relationship was not found");
-    }
-    // Deprecate?
-    async _queryElemIdByFedGuid(db, fedGuid) {
-        const sql = "SELECT ECInstanceId FROM Bis.Element WHERE FederationGuid=:fedGuid";
-        const params = new core_common_1.QueryBinder().bindString("fedGuid", fedGuid);
-        const reader = db.createQueryReader(sql, params);
-        if (await reader.step()) {
-            return reader.current.ecinstanceid;
-        }
-        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";
+    async shouldDetectDeletes() {
+        return (await this._syncTypeResolver.getSyncType()) === "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.
-     */
-    // public async detectElementDeletes(): Promise<void> {
-    //   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
-    //   this.provenanceDb.withPreparedStatement(sql, (stmt) => {
-    //     stmt.bindId("scopeId", this.targetScopeElementId);
-    //     stmt.bindString("kind", ExternalSourceAspect.Kind.Element);
-    //     while (DbResult.BE_SQLITE_ROW === stmt.step()) {
-    //       // ExternalSourceAspect.Identifier is of type string
-    //       const aspectIdentifier = stmt.getValue(0).getString();
-    //       if (!Id64.isValidId64(aspectIdentifier)) {
-    //         continue;
-    //       }
-    //       const targetElemId = stmt.getValue(1).getId();
-    //       const wasDeletedInSource = !EntityUnifier.exists(this.sourceDb, {
-    //         entityReference: `e${aspectIdentifier}`,
-    //       });
-    //       if (wasDeletedInSource) this.importer.deleteElement(targetElemId);
-    //     }
-    //   });
-    // }
     /** Transform the specified sourceElement into ElementProps for the target iModel.
      * @param sourceElement The Element from the source iModel to transform.
      * @returns ElementProps for the target iModel.
@@ -929,7 +395,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      */
     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._cloneContext.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);
@@ -972,7 +440,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.");
@@ -981,7 +455,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;
@@ -999,15 +479,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) {
@@ -1019,23 +517,44 @@ 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;
     }
-    // if undefined, it can be initialized by calling [[this.processChangesets]]
+    // if undefined, it can be initialized by calling [[this.prepareSourceChanges]]
     _deletedSourceRelationshipData = undefined;
+    /** Target relationship ids and target endpoint keys of [[_deletedSourceRelationshipData]] entries, for fast matching in [[onExportRelationship]]. */
+    _pendingRelationshipDeleteTargets = new Set();
+    /** Target relationships that this run imported from a source relationship and that a pending relationship delete also resolves to.
+     * A source relationship deleted and recreated with the same endpoints maps to the same target relationship, which must not be deleted.
+     */
+    _reimportedTargetRelationshipIds = new Set();
     /** 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;
@@ -1055,7 +574,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 throw new Error(`source-target element mapping not found for element "${sourceElementId}" when completing partially committed elements. This is a bug.`);
             }
             const targetProps = await this.onTransformElement(sourceElement);
-            this.targetDb.elements.updateElement({ ...targetProps, id: targetId });
+            this._targetEditTxn.updateElement({ ...targetProps, id: targetId });
         }
     }
     async completePartiallyCommittedAspects() {
@@ -1066,14 +585,23 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 throw new Error(`source-target aspect mapping not found for aspect "${sourceAspectId}" when completing partially committed aspects. This is a bug.`);
             }
             const targetAspectProps = await this.onTransformElementAspect(sourceAspect);
-            this.targetDb.elements.updateAspect({
+            this._targetEditTxn.updateAspect({
                 ...targetAspectProps,
                 id: targetAspectId,
             });
         }
     }
+    /** An exported source element or model exists, so later references to it need no source query.
+     * Aspects are not recorded: they are rarely referenced, and they are usually the largest group.
+     */
+    markSourceEntityExists(entity) {
+        if (this._options.danglingReferencesBehavior !== "reject")
+            return;
+        this._cloneContext.existenceCache.markExists(this.sourceDb, core_backend_1.EntityReferences.from(entity));
+    }
     async doAllReferencesExistInTarget(entity) {
         let allReferencesExist = true;
+        const checkedReferences = [];
         for (const referenceId of entity.getReferenceIds()) {
             const referencedEntityId = core_backend_1.EntityReferences.toId64(referenceId);
             if (referencedEntityId === core_common_1.IModel.repositoryModelId ||
@@ -1090,47 +618,70 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 allReferencesExist = false;
             }
             if (this._options.danglingReferencesBehavior === "reject") {
-                await this.assertReferenceExistsInSource(referenceId, entity);
+                checkedReferences.push(referenceId);
             }
         }
+        if (checkedReferences.length > 0) {
+            await this.assertReferencesExistInSource(checkedReferences, entity);
+        }
         return allReferencesExist;
     }
-    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"));
+    /** Assert that all `referenceIds` exist in the source iModel, batching the existence
+     * queries by entity type and caching positive results for the rest of the run.
+     */
+    async assertReferencesExistInSource(referenceIds, entity) {
+        const found = await this._cloneContext.existenceCache.existsAll(this.sourceDb, referenceIds);
+        for (const referenceId of referenceIds) {
+            if (!found.has(referenceId)) {
+                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.
      * @param sourceElementId Identifies the Element from the source iModel to import.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
      */
     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);
+        return this.processScopedElementExport(async () => this.exporter.exportElement(sourceElementId));
     }
     /** Import child elements into the target IModelDb
      * @param sourceElementId Import the child elements of this element in the source IModelDb.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
      */
     async processChildElements(sourceElementId) {
         await this.initialize();
-        return this.exporter.exportChildElements(sourceElementId);
+        return this.processScopedElementExport(async () => this.exporter.exportChildElements(sourceElementId));
+    }
+    async processScopedElementExport(exportElements) {
+        await this.exporter.elementAspectExportCoordinator.run(exportElements);
     }
     /** 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;
     }
     /**
@@ -1145,7 +696,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const elemClass = sourceElement.constructor;
         const unresolvedReferences = elemClass.requiredReferenceKeys
             .map((referenceKey) => {
-            const idContainer = sourceElement[referenceKey];
+            const idContainer = sourceElement.asAny[referenceKey];
             const referenceType = elemClass.requiredReferenceKeyTypeMap[referenceKey];
             // For now we just consider all required references to be elements (as they are in biscore), and do not support
             // entities that refuse to be inserted without a different kind of entity (e.g. aspect or relationship) first being inserted
@@ -1177,18 +728,95 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (unresolvedReferences.length > 0) {
             for (const reference of unresolvedReferences) {
                 const processState = await this.getElemTransformState(reference);
-                // must export element first
                 if (processState.needsElemImport)
-                    await this.exporter.exportElement(reference);
+                    await this.resolveRequiredElement(sourceElement.id, reference);
                 if (processState.needsModelImport)
                     await this.exporter.exportModel(reference);
             }
         }
     }
+    /** Makes sure an element that a changed element requires is mapped in the target before the changed element is imported.
+     * A changed required element is exported. An unchanged one is only looked up in the target: change processing does not insert it, and exporting it would visit its children, which can include the element that requires it.
+     * @throws [[IModelTransformerError.DependencyMappingMissing]] if the required element is still not mapped.
+     */
+    async resolveRequiredElement(elementId, referenceId) {
+        const changes = this.exporter.sourceDbChanges;
+        const referenceChanged = changes === undefined ||
+            changes.element.insertIds.has(referenceId) ||
+            changes.element.updateIds.has(referenceId);
+        let accepted = true;
+        if (referenceChanged) {
+            await this.exporter.exportElement(referenceId);
+        }
+        else {
+            const reference = this.sourceDb.elements.getElement({
+                id: referenceId,
+                wantGeometry: this.exporter.wantGeometry,
+                wantBRepData: this.exporter.wantGeometry,
+            });
+            // A required parent reached by the traversal has already been filtered.
+            accepted =
+                this.exporter.getUnchangedAncestorFilterResult(referenceId) ??
+                    (await this.exporter.shouldExportElement(reference));
+            if (accepted)
+                await this.findExistingTargetElement(reference, await this.onTransformElement(reference));
+        }
+        if (core_bentley_1.Id64.isValid(this.context.findTargetElementId(referenceId)))
+            return;
+        let message;
+        if (referenceChanged)
+            message = `Element ${elementId} requires element ${referenceId}, which was not exported because the export filter rejects it or one of its ancestors. Accept element ${referenceId} and its ancestors, or reject element ${elementId}.`;
+        else if (accepted)
+            message = `Element ${elementId} requires unchanged element ${referenceId}, which is not in the target iModel. Change processing does not insert unchanged elements; to insert element ${referenceId}, add it in addCustomChanges.`;
+        else
+            message = `Element ${elementId} requires element ${referenceId}, which the export filter rejects. Accept element ${referenceId}, or reject element ${elementId} and every element that requires it.`;
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.DependencyMappingMissing,
+            },
+            message,
+        });
+    }
+    /** Finds the existing target element for a source element by FederationGuid, then by Code, and records the mapping.
+     * @note Updates `targetElementProps.code` as the Code lookup requires.
+     * @returns the target element's id, or `Id64.invalid` if none is found.
+     */
+    async findExistingTargetElement(sourceElement, targetElementProps) {
+        if (this.context.isBetweenIModels &&
+            sourceElement.federationGuid !== undefined) {
+            const targetElementId = this.targetDb.elements.getIdFromFederationGuid(sourceElement.federationGuid);
+            if (targetElementId !== undefined && core_bentley_1.Id64.isValid(targetElementId)) {
+                this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found
+                return targetElementId;
+            }
+        }
+        // check by Code as long as the CodeScope is valid (invalid means a missing reference so not worth checking)
+        if (!core_bentley_1.Id64.isValidId64(targetElementProps.code.scope))
+            return core_bentley_1.Id64.invalid;
+        // 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 ?? "";
+        // empty code values are stored as NULL and are never unique, so they cannot identify an existing target element
+        if (core_common_1.Code.isEmpty(targetElementProps.code))
+            return core_bentley_1.Id64.invalid;
+        const maybeTargetElementId = this.queryElementIdByCode(this.targetDb, targetElementProps.code);
+        if (maybeTargetElementId === undefined)
+            return core_bentley_1.Id64.invalid;
+        const maybeTargetElem = this.targetDb.elements.getElement(maybeTargetElementId);
+        if (maybeTargetElem.classFullName !== targetElementProps.classFullName) {
+            targetElementProps.code = core_common_1.Code.createEmpty(); // clear out invalid code
+            return core_bentley_1.Id64.invalid;
+        }
+        // ensure code remapping doesn't change the target class
+        this.context.remapElement(sourceElement.id, maybeTargetElementId); // record that the targetElement was found by Code
+        this._targetElementIdsRemappedByCode.add(maybeTargetElementId);
+        return maybeTargetElementId;
+    }
     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 });
+            return this._cloneContext.existenceCache.exists(db, maybeModelId);
         };
         const isSubModeled = await dbHasModel(this.sourceDb, elementId);
         const idOfElemInTarget = this.context.findTargetElementId(elementId);
@@ -1197,10 +825,42 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             (!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 queries bis_Element through a cached SQLite statement, because creating an ECSQL reader per element is slow
+    // and the cached ECSQL API (withPreparedStatement) is deprecated. Results match the ECSQL query because CodeValue
+    // is COLLATE NOCASE, ix_bis_Element_Code is unique, and the primary connection sees uncommitted target inserts.
+    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",
+            });
+        return iModel.withPreparedSqliteStatement("SELECT Id FROM bis_Element WHERE CodeSpecId=? AND CodeScopeId=? AND CodeValue=?", (stmt) => {
+            stmt.bindId(1, code.spec);
+            stmt.bindId(2, core_bentley_1.Id64.fromString(code.scope));
+            stmt.bindString(3, code.value);
+            return stmt.nextRow() ? stmt.getValueId(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.
      */
     async onExportElement(sourceElement) {
+        this.markSourceEntityExists(sourceElement);
         let targetElementId = core_bentley_1.Id64.invalid;
         let targetElementProps;
         if (this._options.wasSourceIModelCopiedToTarget) {
@@ -1212,34 +872,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             targetElementId = this.context.findTargetElementId(sourceElement.id);
             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.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
-        }
-        // if an existing remapping was not yet found, check by Code as long as the CodeScope is valid (invalid means a missing reference so not worth checking)
-        if (!core_bentley_1.Id64.isValidId64(targetElementId) &&
-            core_bentley_1.Id64.isValidId64(targetElementProps.code.scope)) {
-            // respond the same way to undefined code value as the @see Code class, but don't use that class because it trims
-            // whitespace from the value, and there are iModels out there with untrimmed whitespace that we ought not to trim
-            targetElementProps.code.value = targetElementProps.code.value ?? "";
-            const maybeTargetElementId = this.targetDb.elements.queryElementIdByCode(targetElementProps.code);
-            if (undefined !== maybeTargetElementId) {
-                const maybeTargetElem = this.targetDb.elements.getElement(maybeTargetElementId);
-                if (maybeTargetElem.classFullName === targetElementProps.classFullName) {
-                    // ensure code remapping doesn't change the target class
-                    targetElementId = maybeTargetElementId;
-                    this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found by Code
-                }
-                else {
-                    targetElementProps.code = core_common_1.Code.createEmpty(); // clear out invalid code
-                }
-            }
-        }
+        // if an existing remapping was not yet found, check by FederationGuid and then by Code
+        if (!core_bentley_1.Id64.isValid(targetElementId))
+            targetElementId = await this.findExistingTargetElement(sourceElement, targetElementProps);
         if (!this.hasElementChanged(sourceElement)) {
             core_bentley_1.Logger.logTrace(loggerCategory, `Skipping unchanged element (${sourceElement.id}, ${sourceElement.getDisplayLabel()}).`);
             return;
@@ -1255,7 +890,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)
@@ -1266,7 +907,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
@@ -1275,12 +922,15 @@ 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);
+        if (this.sourceDb === this.targetDb) {
+            this._cloneContext.existenceCache.markExists(this.targetDb, core_backend_1.EntityReferences.fromEntityType(targetElementProps.id, core_common_1.ConcreteEntityTypes.Element));
+        }
         // the transformer does not currently 'split' or 'join' any elements, therefore, it does not
         // insert external source aspects because federation guids are sufficient for this.
         // Other transformer subclasses must insert the appropriate aspect (as provided by a TBD API)
@@ -1288,40 +938,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.provenanceDb();
+        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 = await this.initElementProvenance(sourceElement.id, targetElementProps.id);
-                const foundEsaProps = await IModelTransformer.queryScopeExternalSourceAspect(provenanceDb, aspectProps);
+                const foundEsaProps = await ProvenanceManager_1.ProvenanceManager.queryScopeExternalSourceAspect(provenanceDb, aspectProps);
                 if (foundEsaProps === undefined)
-                    aspectProps.id = 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;
-                    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) {
-        const targetElementId = this.context.findTargetElementId(sourceElementId);
-        if (core_bentley_1.Id64.isValidId64(targetElementId)) {
-            this.importer.deleteElement(targetElementId);
+    /** Maps the deleted source element IDs and passes the target IDs to the importer as one set. */
+    async onDeleteElements(sourceElementIds) {
+        const targetElementIds = new Set();
+        for (const sourceElementId of sourceElementIds) {
+            const targetElementId = this.context.findTargetElementId(sourceElementId);
+            if (core_bentley_1.Id64.isValidId64(targetElementId) &&
+                !this._targetElementIdsRemappedByCode.has(targetElementId)) {
+                targetElementIds.add(targetElementId);
+            }
         }
+        await this.importer.deleteElements(targetElementIds);
     }
     /** 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) {
+        this.markSourceEntityExists(sourceModel);
         if (this._options.skipPropagateChangesToRootElements &&
             core_common_1.IModel.repositoryModelId === sourceModel.id)
             return; // The RepositoryModel should not be directly imported
@@ -1332,7 +985,12 @@ 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._cloneContext.existenceCache.markExists(this.targetDb, core_backend_1.EntityReferences.fromEntityType(targetModelProps.id, core_common_1.ConcreteEntityTypes.Model));
+        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. */
     async onDeleteModel(sourceModelId) {
@@ -1342,6 +1000,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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
@@ -1353,7 +1018,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     `;
         if (this.exporter.sourceDbChanges?.element.deleteIds.has(sourceModelId)) {
             const params = new core_common_1.QueryBinder().bindId("targetModelId", targetModelId);
-            const reader = this.targetDb.createQueryReader(sql, params);
+            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.
@@ -1371,9 +1038,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                     error.errorNumber === core_bentley_1.IModelStatus.ForeignKeyConstraint);
             if (!isDeletionProhibitedErr)
                 throw error;
-            // Transformer tries to delete models before it deletes elements. Definition models cannot be deleted unless all of their modeled elements are deleted first.
-            // In case a definition model needs to be deleted we need to skip it for now and register its modeled partition for deletion.
-            // The `OnDeleteElement` calls `DeleteElementTree` Which deletes the model together with its partition after deleting all of the modeled elements.
+            // Models are processed before elements, but a definition model cannot be deleted while it contains elements.
+            // Add its partition to the element deletion set. Bulk cascade deletion will remove the contents, model, and partition together.
             this.scheduleModeledPartitionDeletion(sourceModelId);
         }
     }
@@ -1388,22 +1054,24 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Cause the model container, contents, and sub-models to be exported from the source iModel and imported into the target iModel.
      * @param sourceModeledElementId Import this [Model]($backend) from the source IModelDb.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
      */
     async processModel(sourceModeledElementId) {
         await this.initialize();
-        return this.exporter.exportModel(sourceModeledElementId);
+        return this.processScopedElementExport(async () => this.exporter.exportModel(sourceModeledElementId));
     }
     /** Cause the model contents to be exported from the source iModel and imported into the target iModel.
      * @param sourceModelId Import the contents of this model from the source IModelDb.
      * @param targetModelId Import into this model in the target IModelDb. The target model must exist prior to this call.
      * @param elementClassFullName Optional classFullName of an element subclass to limit import query against the source model.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
      */
     async processModelContents(sourceModelId, targetModelId, elementClassFullName = core_backend_1.Element.classFullName) {
         await this.initialize();
         this.targetDb.models.getModel(targetModelId); // throws if Model does not exist
         this.context.remapElement(sourceModelId, targetModelId); // set remapping in case importModelContents is called directly
-        return this.exporter.exportModelContents(sourceModelId, elementClassFullName);
+        return this.processScopedElementExport(async () => this.exporter.exportModelContents(sourceModelId, elementClassFullName));
     }
     /** Cause all sub-models that recursively descend from the specified Subject to be exported from the source iModel and imported into the target iModel. */
     async processSubjectSubModels(sourceSubjectId) {
@@ -1411,12 +1079,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         // import DefinitionModels first
         const childDefinitionPartitionSql = `SELECT ECInstanceId FROM ${core_backend_1.DefinitionPartition.classFullName} WHERE Parent.Id=:subjectId`;
         const params = new core_common_1.QueryBinder().bindId("subjectId", sourceSubjectId);
-        for await (const row of this.sourceDb.createQueryReader(childDefinitionPartitionSql, params)) {
+        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`;
-        for await (const row of this.sourceDb.createQueryReader(childPartitionSql, params)) {
+        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)) {
@@ -1425,7 +1093,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         // recurse into child Subjects
         const childSubjectSql = `SELECT ECInstanceId FROM ${core_backend_1.Subject.classFullName} WHERE Parent.Id=:subjectId`;
-        for await (const row of this.sourceDb.createQueryReader(childSubjectSql, params)) {
+        for await (const row of this.sourceDb.createQueryReader(childSubjectSql, params, { usePrimaryConn: true })) {
             await this.processSubjectSubModels(row.id);
         }
     }
@@ -1444,103 +1112,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.
-     */
-    async 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 (await this.getIsReverseSynchronization()) {
-            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 (await this.getIsReverseSynchronization()) {
-                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 (await this.getIsReverseSynchronization()) {
-                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}`);
-        }
-        (await 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)
+    /** Complete a high-level transformation after all export operations finish. */
     async finalizeTransformation() {
         this.importer.finalize();
+        this._cloneContext.existenceCache.clear();
         await this.updateSynchronizationVersion({
             initializeReverseSyncVersion: this._isProvenanceInitTransform,
         });
@@ -1549,17 +1135,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
                 core_backend_1.ChangeSummaryManager.detachChangeCache(this.sourceDb);
         }
-        // this internal is guaranteed stable for just transformer usage
-        /* eslint-disable @itwin/no-internal */
-        if (("codeValueBehavior" in this.sourceDb)) {
-            this.sourceDb.codeValueBehavior = "trim-unicode-whitespace";
-            this.targetDb.codeValueBehavior = "trim-unicode-whitespace";
-        }
-        /* eslint-enable @itwin/no-internal */
+        this.setCodeValueBehavior("trim-unicode-whitespace");
+    }
+    setCodeValueBehavior(behavior) {
+        this.sourceDb.codeValueBehavior = behavior;
+        this.targetDb.codeValueBehavior = behavior;
     }
     /** Imports all relationships that subclass from the specified base class.
      * @param baseRelClassFullName The specified base relationship class.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
      */
     async processRelationships(baseRelClassFullName) {
         await this.initialize();
@@ -1568,40 +1153,55 @@ 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.
+     * @param endpointFedGuids The FederationGuids of the relationship's source and target elements, as supplied by [[IModelExporter]]. If `undefined`, both are looked up in the source iModel when provenance needs them.
+     * @note Overrides should pass `endpointFedGuids` to `super`. If it is omitted, the transformer looks up both endpoint FederationGuids for every relationship, which is slower.
      */
-    async onExportRelationship(sourceRelationship) {
-        const sourceFedGuid = this.sourceDb.elements.getFederationGuidFromId(sourceRelationship.sourceId);
-        const targetFedGuid = this.sourceDb.elements.getFederationGuidFromId(sourceRelationship.targetId);
+    async onExportRelationship(sourceRelationship, _isUpdate, endpointFedGuids) {
         const targetRelationshipProps = this.onTransformRelationship(sourceRelationship);
-        const targetRelationshipInstanceId = this.importer.importRelationship(targetRelationshipProps);
-        const provenanceDb = await this.provenanceDb();
+        const targetRelationshipInstanceId = await this.importer.importRelationship(targetRelationshipProps);
+        if (this._pendingRelationshipDeleteTargets.size > 0 &&
+            core_bentley_1.Id64.isValid(targetRelationshipInstanceId) &&
+            (this._pendingRelationshipDeleteTargets.has(targetRelationshipInstanceId) ||
+                this._pendingRelationshipDeleteTargets.has(relationshipEndpointsKey(targetRelationshipProps.sourceId, targetRelationshipProps.targetId)))) {
+            this._reimportedTargetRelationshipIds.add(targetRelationshipInstanceId);
+        }
+        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 = await this.initRelationshipProvenance(sourceRelationship, targetRelationshipInstanceId);
-                const foundEsaProps = await IModelTransformer.queryScopeExternalSourceAspect(provenanceDb, aspectProps);
+            const needsEsaProvenance = this._options.forceExternalSourceAspectProvenance ||
+                !this.relationshipEndpointsHaveFedGuids(sourceRelationship, endpointFedGuids);
+            if (needsEsaProvenance) {
+                const aspectProps = await this._provenanceManager.initRelationshipProvenance(sourceRelationship.id, targetRelationshipInstanceId, this._forceOldRelationshipProvenanceMethod, {
+                    sourceRelSourceElementId: sourceRelationship.sourceId,
+                    targetRelSourceElementId: targetRelationshipProps.sourceId,
+                });
+                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 = provenanceDb.elements.insertAspect(aspectProps);
+                    aspectProps.id = provenanceEditTxn.insertAspect(aspectProps);
                 }
-                provenance = aspectProps;
             }
-            this.markLastProvenance(provenance, { isRelationship: true });
         }
     }
+    /** Returns whether both relationship endpoints have a FederationGuid, looking them up only when the caller did not supply them. */
+    relationshipEndpointsHaveFedGuids(relationship, endpointFedGuids) {
+        if (endpointFedGuids !== undefined)
+            return !!endpointFedGuids.source && !!endpointFedGuids.target;
+        const elements = this.sourceDb.elements;
+        return (!!elements.getFederationGuidFromId(relationship.sourceId) &&
+            !!elements.getFederationGuidFromId(relationship.targetId));
+    }
     /** 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).
      */
     async onDeleteRelationship(sourceRelInstanceId) {
-        nodeAssert(this._deletedSourceRelationshipData, "should be defined at initialization by now");
+        (0, node_assert_1.strict)(this._deletedSourceRelationshipData, "should be defined at initialization by now");
         const deletedRelData = this._deletedSourceRelationshipData.get(sourceRelInstanceId);
         if (!deletedRelData) {
             // this can occur if both the source and target deleted it
@@ -1613,15 +1213,19 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 sourceId: deletedRelData.sourceIdInTarget,
                 targetId: deletedRelData.targetIdInTarget,
             })?.id;
-        if (id) {
-            this.importer.deleteRelationship({
+        if (id && this._reimportedTargetRelationshipIds.has(id)) {
+            // The source relationship was recreated with the same endpoints and already imported into this target relationship.
+            core_bentley_1.Logger.logTrace(loggerCategory, `Skipping delete of target relationship ${id} because source relationship ${sourceRelInstanceId} was recreated`);
+        }
+        else if (id) {
+            await this.importer.deleteRelationship({
                 id,
                 classFullName: deletedRelData.classFullName,
             });
         }
         if (deletedRelData.provenanceAspectId) {
             try {
-                (await 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.
@@ -1631,59 +1235,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.
-     */
-    // public async detectRelationshipDeletes(): Promise<void> {
-    //   if (this.isReverseSynchronization) {
-    //     throw new IModelError(
-    //       IModelStatus.BadRequest,
-    //       "Cannot detect deletes when isReverseSynchronization=true"
-    //     );
-    //   }
-    //   const aspectDeleteIds: Id64String[] = [];
-    //   const sql = `
-    //     SELECT ECInstanceId, Identifier, JsonProperties
-    //     FROM ${ExternalSourceAspect.classFullName} aspect
-    //     WHERE aspect.Scope.Id=:scopeId
-    //       AND aspect.Kind=:kind
-    //   `;
-    //   const params = new QueryBinder().bindId(
-    //     "scopeId",
-    //     this.targetScopeElementId
-    //   );
-    //   params.bindString("kind", ExternalSourceAspect.Kind.Relationship);
-    //   for await (const row of this.targetDb.createQueryReader(sql, params)) {
-    //     const sourceRelInstanceId: Id64String = Id64.fromJSON(row[1]);
-    //     if (
-    //       undefined ===
-    //       this.sourceDb.relationships.tryGetInstanceProps(
-    //         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: any = JSON.parse(row[2]);
-    //       const targetRelInstanceId =
-    //         json.targetRelInstanceId ?? json.provenanceRelInstanceId;
-    //       if (targetRelInstanceId) {
-    //         this.importer.deleteRelationship({
-    //           id: targetRelInstanceId,
-    //           classFullName: ElementRefersToElements.classFullName,
-    //         });
-    //       }
-    //       aspectDeleteIds.push(row.id);
-    //     }
-    //     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.
@@ -1694,19 +1245,36 @@ 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.forEach((propertyName, property) => {
+        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) {
-        // 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.
+    async shouldExportElementAspect(aspect) {
+        // An aspect cannot be exported when its owner has no source-to-target
+        // mapping.
         return this.context.findTargetElementId(aspect.element.id) !== core_bentley_1.Id64.invalid;
     }
+    async prepareElementAspects(excludedElementAspectClassFullNames, elementIds) {
+        if (!this.exporter.visitElements)
+            return;
+        if (elementIds === undefined)
+            return;
+        const targetElementIds = new Set();
+        for (const sourceElementId of elementIds) {
+            const targetElementId = this.context.findTargetElementId(sourceElementId);
+            if (core_bentley_1.Id64.isValid(targetElementId)) {
+                targetElementIds.add(targetElementId);
+            }
+        }
+        await this.importer.elementAspectCleanup.delete(targetElementIds, excludedElementAspectClassFullNames, this.targetScopeElementId);
+    }
     /** 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.
      */
@@ -1715,7 +1283,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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.
@@ -1725,13 +1293,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async onExportElementMultiAspects(sourceAspects) {
         // Transform source ElementMultiAspects into target ElementAspectProps
         const targetAspectPropsArray = sourceAspects.map(async (srcA) => this.onTransformElementAspect(srcA));
-        sourceAspects.forEach(async (a) => {
+        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(await Promise.all(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 ||
@@ -1747,7 +1314,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @note A subclass can override this method to provide custom transform behavior.
      */
     async onTransformElementAspect(sourceElementAspect) {
-        const targetElementAspectProps = await this.context.cloneElementAspect(sourceElementAspect);
+        const targetElementAspectProps = await this._cloneContext.cloneElementAspect(sourceElementAspect);
         return targetElementAspectProps;
     }
     /** The directory where schemas will be exported, a random temporary directory */
@@ -1755,82 +1322,27 @@ 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;
         return Semver.gt(`${schemaKey.version.read}.${schemaKey.version.write}.${schemaKey.version.minor}`, core_backend_1.Schema.toSemverString(versionInTarget));
     }
-    _longNamedSchemasMap = new Map();
-    /** Override of [IModelExportHandler.onExportSchema]($transformer) that serializes a schema to disk for [[processSchemas]] to import into
-     * the target iModel when it is exported from the source iModel.
-     * @returns {Promise<ExportSchemaResult>} Although the type is possibly void for backwards compatibility of subclasses,
-     *                                        `IModelTransformer.onExportSchema` always returns an[[IModelExportHandler.ExportSchemaResult]]
-     *                                        with a defined `schemaPath` property, for subclasses to know where the schema was written.
-     *                                        Schemas are *not* guaranteed to be written to [[IModelTransformer._schemaExportDir]] by a
-     *                                        known pattern derivable from the schema's name, so you must use this to find it.
+    /** Serialize a source schema to the temporary directory used by [[processSchemas]].
+     * @returns A path to the serialized schema file.
+     * @note The file name is not derived reliably from the schema name. Use the returned path when a subclass calls `super`.
      */
     async onExportSchema(schema) {
-        const ext = ".ecschema.xml";
-        let schemaFileName = schema.name + ext;
-        // many file systems have a max file-name/path-segment size of 255, so we workaround that on all systems
-        const systemMaxPathSegmentSize = 255;
-        // windows usually has a limit for the total path length of 260
-        const windowsMaxPathLimit = 260;
-        if (schemaFileName.length > systemMaxPathSegmentSize ||
-            path.join(this._schemaExportDir, schemaFileName).length >=
-                windowsMaxPathLimit) {
-            // this name should be well under 255 bytes
-            // ( 100 + (Number.MAX_SAFE_INTEGER.toString().length = 16) + (ext.length = 13) ) = 129 which is less than 255
-            // You'd have to be past 2**53-1 (Number.MAX_SAFE_INTEGER) long named schemas in order to hit decimal formatting,
-            // and that's on the scale of at least petabytes. `Map.prototype.size` shouldn't return floating points, and even
-            // if they do they're in scientific notation, size bound and contain no invalid windows path chars
-            schemaFileName = `${schema.name.slice(0, 100)}${this._longNamedSchemasMap.size}${ext}`;
-            nodeAssert(schemaFileName.length <= systemMaxPathSegmentSize, "Schema name was still long. This is a bug.");
-            this._longNamedSchemasMap.set(schema.name, schemaFileName);
-        }
-        this.sourceDb.exportSchema({
-            schemaName: schema.name,
-            outputDirectory: this._schemaExportDir,
-            outputFileName: schemaFileName,
-        });
-        return { schemaPath: path.join(this._schemaExportDir, schemaFileName) };
-    }
-    _makeLongNameResolvingSchemaCtx() {
-        const result = new core_backend_1.ECSchemaXmlContext();
-        result.setSchemaLocater((key) => {
-            const match = this._longNamedSchemasMap.get(key.name);
-            if (match !== undefined)
-                return path.join(this._schemaExportDir, match);
-            return undefined;
-        });
-        return result;
+        return this._schemaProcessingCoordinator.serializeSourceSchema(schema);
     }
-    /** Cause all schemas to be exported from the source iModel and imported into the target iModel.
+    /** Process source schemas and import selected or generated definitions into the target iModel.
+     * @param options Selects the schema processing strategy.
+     * @note When no strategy is supplied, [[NewerVersionSchemaImportStrategy]] is used.
      * @note For performance reasons, it is recommended that [IModelDb.saveChanges]($backend) be called after `processSchemas` is complete.
      * It is more efficient to process *data* changes after the schema changes have been saved.
      */
-    async processSchemas() {
-        // we do not need to initialize for this since no entities are exported
-        try {
-            core_backend_1.IModelJsFs.mkdirSync(this._schemaExportDir);
-            this._longNamedSchemasMap.clear();
-            await this.exporter.exportSchemas();
-            const exportedSchemaFiles = core_backend_1.IModelJsFs.readdirSync(this._schemaExportDir);
-            if (exportedSchemaFiles.length === 0)
-                return;
-            const schemaFullPaths = exportedSchemaFiles.map((s) => path.join(this._schemaExportDir, s));
-            const maybeLongNameResolvingSchemaCtx = this._longNamedSchemasMap.size > 0
-                ? this._makeLongNameResolvingSchemaCtx()
-                : undefined;
-            return await this.targetDb.importSchemas(schemaFullPaths, {
-                ecSchemaXmlContext: maybeLongNameResolvingSchemaCtx,
-            });
-        }
-        finally {
-            core_backend_1.IModelJsFs.removeSync(this._schemaExportDir);
-            this._longNamedSchemasMap.clear();
-        }
+    async processSchemas(options) {
+        return this._schemaProcessingCoordinator.process(options?.strategy ?? new SchemaProcessingStrategy_1.NewerVersionSchemaImportStrategy());
     }
     /** Cause all fonts to be exported from the source iModel and imported into the target iModel.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
@@ -1841,8 +1353,8 @@ 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) {
-        this.context.importFont(font.id);
+    async onExportFont(font, _isUpdate) {
+        this._cloneContext.importFont(font.id);
     }
     /** Cause all CodeSpecs to be exported from the source iModel and imported into the target iModel.
      * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
@@ -1861,29 +1373,32 @@ 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) {
-        this.context.importCodeSpec(sourceCodeSpec.id);
+    async onExportCodeSpec(sourceCodeSpec) {
+        this._cloneContext.importCodeSpec(sourceCodeSpec.id);
     }
-    /** Recursively import all Elements and sub-Models that descend from the specified Subject */
+    /** Recursively import all Elements and sub-Models that descend from the specified Subject.
+     * @note After composing subset processing calls, call [[IModelImporter.finalize]] before saving target changes.
+     */
     async processSubject(sourceSubjectId, targetSubjectId) {
         await this.initialize();
         this.sourceDb.elements.getElement(sourceSubjectId, core_backend_1.Subject); // throws if sourceSubjectId is not a Subject
         this.targetDb.elements.getElement(targetSubjectId, core_backend_1.Subject); // throws if targetSubjectId is not a Subject
         this.context.remapElement(sourceSubjectId, targetSubjectId);
-        await this.processChildElements(sourceSubjectId);
-        await this.processSubjectSubModels(sourceSubjectId);
+        await this.processScopedElementExport(async () => {
+            await this.processChildElements(sourceSubjectId);
+            await this.processSubjectSubModels(sourceSubjectId);
+        });
         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;
+    _deletionBatches;
     /**
      * 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.
@@ -1893,28 +1408,80 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async initialize() {
         if (this._initialized)
             return;
+        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(await this.getExportInitOpts(this._options.argsForProcessChanges ?? {}));
-        // Exporter must be initialized prior to processing changesets in order to properly handle entity recreations (an entity delete followed by an insert of that same entity).
-        await this.processChangesets();
+        await this._cloneContext.initialize();
+        const exporterInitOptions = await this.getExportInitOpts(this._options.argsForProcessChanges ?? {});
+        await this.initializeChangesetScanAndExporter(exporterInitOptions);
+        // Exporter must be initialized prior to remapping deletions in order to properly handle entity recreations (an entity delete followed by an insert of that same entity).
+        await this.prepareSourceChanges();
         this._initialized = true;
     }
+    async initializeChangesetScanAndExporter(exporterInitOptions) {
+        const ranges = this._changesetRanges;
+        if (ranges !== undefined &&
+            ranges.length > 0 &&
+            this.sourceDb.isBriefcaseDb()) {
+            let changedInstanceIds = this.exporter.sourceDbChanges ??
+                ("changedInstanceIds" in exporterInitOptions
+                    ? exporterInitOptions.changedInstanceIds
+                    : undefined);
+            if (changedInstanceIds !== undefined) {
+                // The caller supplied changed IDs, so only deletion metadata is read.
+                this._deletionBatches = await ChangesetScanner_1.ChangesetScanner.scan(this.sourceDb, await ChangesetScanner_1.ChangesetScanner.download(this.sourceDb, ranges), {});
+            }
+            else {
+                const scanResult = await this.collectChanges(ranges);
+                changedInstanceIds = scanResult.changedInstanceIds;
+                this._deletionBatches = scanResult.deletionBatches;
+            }
+            await this.exporter.initialize({
+                changedInstanceIds,
+                skipPropagateChangesToRootElements: exporterInitOptions.skipPropagateChangesToRootElements,
+            });
+        }
+        else {
+            await this.exporter.initialize(exporterInitOptions);
+        }
+    }
+    /**
+     * Reads the source changes for the changeset ranges being processed. Override to supply changes from another
+     * source, such as a precomputed cache, instead of downloading and reading changesets.
+     *
+     * An override can supply some ranges itself and pass the rest to `super.collectChanges()`. Pass the same
+     * `changedInstanceIds` to every call and handle the ranges in order, so that changes to the same instance in
+     * different ranges combine correctly. Use [[ChangedInstanceIds.addChangeRecord]] to add each supplied change.
+     * See [Supplying source changes]($docs/learning/transformer/change-scanning.md) for the full contract and an example.
+     * @param ranges Ordered, inclusive `[first, last]` changeset index ranges. They already exclude changesets
+     * that must be skipped, such as those pushed by a previous synchronization in the other direction, so an
+     * override must cover exactly these ranges.
+     * @param changedInstanceIds Receives the changes read from the ranges. Defaults to a new, empty instance.
+     * @returns The changed instance IDs to export and the records used to find the targets of deleted instances.
+     * See [[CollectedChanges]] for what the result must include.
+     * @note The default implementation downloads the changesets, reads them with `ChangesetReader`, and returns one
+     * deletion batch per range.
+     * @note Not called when the exporter already has changed instance IDs, for example when `changedInstanceIds`
+     * is passed in [[IModelTransformOptions.argsForProcessChanges]]. The transformer then still downloads and reads
+     * the changesets to find deletion records.
+     * @beta
+     */
+    async collectChanges(ranges, changedInstanceIds = new IModelExporter_1.ChangedInstanceIds(this.sourceDb)) {
+        const deletionBatches = await ChangesetScanner_1.ChangesetScanner.scan(this.sourceDb, await ChangesetScanner_1.ChangesetScanner.download(this.sourceDb, ranges), { changedInstanceIds });
+        return { changedInstanceIds, deletionBatches };
+    }
     /**
-     * Reads all the changeset files in the private member of the transformer: _csFileProps
-     * and finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
-     * This function returns early if csFileProps is undefined or is of length 0.
-     * @returns void
+     * Remaps tracked elements, adds custom changes, and remaps deleted source entities to their targets using the
+     * deletion batches read for the changeset ranges being processed.
      */
-    async processChangesets() {
-        await this.forEachTrackedElement((sourceElementId, targetElementId) => {
+    async prepareSourceChanges() {
+        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 ranges = this._changesetRanges;
+        if (ranges === undefined || ranges.length === 0) {
             if (this.exporter.sourceDbChanges === undefined ||
                 !this.exporter.sourceDbChanges.hasChanges)
                 return;
@@ -1922,14 +1489,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (this._sourceChangeDataState === "no-changes")
                 this._sourceChangeDataState = "has-changes";
         }
-        const relationshipECClassIdsToSkip = new Set();
-        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)")) {
-            relationshipECClassIdsToSkip.add(row.ECInstanceId);
-        }
-        const relationshipECClassIds = new Set();
-        for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementRefersToElements)")) {
-            relationshipECClassIds.add(row.ECInstanceId);
-        }
+        const deletionBatches = this._deletionBatches;
+        if (deletionBatches === undefined)
+            return;
         // For later use when processing deletes.
         const alreadyImportedElementInserts = new Set();
         const alreadyImportedModelInserts = new Set();
@@ -1944,48 +1506,28 @@ 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];
-            /** a map of element ids to this transformation scope's ESA data for that element, in case the ESA is deleted in the target */
-            const elemIdToScopeEsa = new Map();
-            for (const change of changes) {
-                if (change.ECClassId !== undefined &&
-                    relationshipECClassIdsToSkip.has(change.ECClassId))
-                    continue;
-                const changeType = change.$meta?.op;
-                if (changeType === "Deleted" &&
-                    change?.$meta?.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
-                    change.Scope.Id === this.targetScopeElementId &&
-                    change.Kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
-                    elemIdToScopeEsa.set(change.Element.Id, change);
-                }
+        this._pendingRelationshipDeleteTargets.clear();
+        this._reimportedTargetRelationshipIds.clear();
+        for (const batch of deletionBatches) {
+            // Deletion records can only resolve targets within their own batch, so these lookups are rebuilt for each batch.
+            // They cover elements and scope ESAs deleted in the source, which can no longer be read from it.
+            const deletedScopeEsaByElementId = new Map();
+            for (const aspect of batch.externalSourceAspects) {
+                if (aspect.scopeId === this.targetScopeElementId &&
+                    aspect.kind === core_backend_1.ExternalSourceAspect.Kind.Element)
+                    deletedScopeEsaByElementId.set(aspect.elementId, aspect);
             }
-            // Loop to process deletes.
-            for (const change of changes) {
-                const changeType = change.$meta?.op;
-                const ecClassId = change.ECClassId ?? change.$meta?.fallbackClassId;
-                if (ecClassId === undefined)
-                    throw new Error(`ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`);
-                if (changeType === undefined)
-                    throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
-                if (changeType !== "Deleted" ||
-                    relationshipECClassIdsToSkip.has(ecClassId))
-                    continue;
-                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
-            }
-            csReader.close();
+            const deletedFederationGuidByElementId = new Map();
+            for (const element of batch.elements)
+                if (element.federationGuid)
+                    deletedFederationGuidByElementId.set(element.ecInstanceId, element.federationGuid);
+            for (const relationship of batch.relationships)
+                await this.processDeletedRelationship(relationship, deletedScopeEsaByElementId, deletedFederationGuidByElementId);
+            for (const element of batch.elements)
+                await this.processDeletedElement(element.ecInstanceId, element.federationGuid, deletedScopeEsaByElementId, alreadyImportedElementInserts, alreadyImportedModelInserts);
+            for (const model of batch.models)
+                await this.processDeletedElement(model.ecInstanceId, undefined, deletedScopeEsaByElementId, alreadyImportedElementInserts, alreadyImportedModelInserts);
         }
-        return;
     }
     /**
      * This will be called when transformer is called with [[IModelTransformOptions.argsForProcessChanges]] to process changes.
@@ -1997,113 +1539,110 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      */
     async addCustomChanges(_sourceDbChanges) { }
     /**
-     * Helper function for processChangesets. Remaps the id of element deleted found in the 'change' to an element in the targetDb.
-     * @param change the change to process, must be of changeType "Deleted"
-     * @param mapOfDeletedElemIdToScopeEsas a map of elementIds to changedECInstances (which are ESAs). the elementId is not the id of the esa itself, but the elementid that the esa was stored on before the esa's deletion.
-     * All ESAs in this map are part of the transformer's scope / ESA data and are tracked in case the ESA is deleted in the target.
-     * @param isRelationship is relationship or not
-     * @param alreadyImportedElementInserts used to handle entity recreation and not delete already handled element inserts.
-     * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
-     * @returns void
-     */
-    async processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
-        // we need a connected iModel with changes to remap elements with deletions
-        const notConnectedModel = this.sourceDb.iTwinId === undefined;
-        const noChanges = (await this.synchronizationVersion()).index ===
-            this.sourceDb.changeset.index &&
-            (this.exporter.sourceDbChanges === undefined ||
-                !this.exporter.sourceDbChanges.hasChanges);
-        if (notConnectedModel || noChanges)
-            return;
+     * Finds the target ID of a source element while processing deletions, first through the transformation's
+     * ExternalSourceAspects when the source holds the provenance, then through the federation GUID. The element may be
+     * deleted itself, or be a surviving endpoint of a deleted relationship.
+     * @param sourceId the source element ID.
+     * @param federationGuid the source element's federation GUID, if known.
+     * @param deletedScopeEsaByElementId this transformation scope's deleted ESAs in the same batch, keyed by the ID of the element that owned each one.
+     */
+    async findTargetElementIdForDeletion(sourceId, federationGuid, deletedScopeEsaByElementId) {
         /**
-         * 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 === (await this.provenanceDb());
-        const getTargetIdFromSourceId = async (id) => {
+        if (this.sourceDb === (await this.getProvenanceDb())) {
             let identifierValue;
-            let element;
-            if (isRelationship) {
-                element = this.sourceDb.elements.tryGetElement(id);
-            }
-            const fedGuid = isRelationship
-                ? element?.federationGuid
-                : change.FederationGuid;
-            if (changeDataInProvenanceDb) {
-                // TODO: clarify what happens if there are multiple (e.g. elements were merged)
-                for await (const row of this.sourceDb.createQueryReader("SELECT esa.Identifier FROM bis.ExternalSourceAspect esa WHERE Scope.Id=:scopeId AND Kind=:kind AND Element.Id=:relatedElementId LIMIT 1", core_common_1.QueryBinder.from([
-                    this.targetScopeElementId,
-                    core_backend_1.ExternalSourceAspect.Kind.Element,
-                    id,
-                ]))) {
-                    identifierValue = row.Identifier;
-                }
-                identifierValue =
-                    identifierValue ?? mapOfDeletedElemIdToScopeEsas.get(id)?.Identifier;
+            // 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,
+                sourceId,
+            ]), { usePrimaryConn: true })) {
+                identifierValue = row.Identifier;
             }
+            identifierValue =
+                identifierValue ?? deletedScopeEsaByElementId.get(sourceId)?.identifier;
             // Check for targetId by an esa first
-            if (changeDataInProvenanceDb && identifierValue) {
-                const targetId = identifierValue;
-                return targetId;
-            }
-            // Check for targetId using sourceId's fedguid if we didn't find an esa.
-            if (fedGuid) {
-                const targetId = this.targetDb.elements.getIdFromFederationGuid(fedGuid);
-                return targetId;
-            }
-            return undefined;
-        };
-        const changedInstanceId = change.ECInstanceId;
-        if (isRelationship) {
-            const sourceIdOfRelationshipInSource = change.SourceECInstanceId;
-            const targetIdOfRelationshipInSource = change.TargetECInstanceId;
-            const classFullName = change.$meta?.classFullName;
-            const sourceIdOfRelationshipInTarget = await getTargetIdFromSourceId(sourceIdOfRelationshipInSource);
-            const targetIdOfRelationshipInTarget = await getTargetIdFromSourceId(targetIdOfRelationshipInSource);
-            if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
-                this._deletedSourceRelationshipData?.set(changedInstanceId, {
-                    classFullName: classFullName ?? "",
-                    sourceIdInTarget: sourceIdOfRelationshipInTarget,
-                    targetIdInTarget: targetIdOfRelationshipInTarget,
-                });
-            }
-            else if (this.sourceDb === (await this.provenanceSourceDb())) {
-                const relProvenance = await this._queryProvenanceForRelationship(changedInstanceId, {
-                    classFullName: classFullName ?? "",
-                    sourceId: sourceIdOfRelationshipInSource,
-                    targetId: targetIdOfRelationshipInSource,
+            if (identifierValue)
+                return identifierValue;
+        }
+        // Check for targetId using sourceId's fedguid if we didn't find an esa.
+        if (federationGuid)
+            return this.targetDb.elements.getIdFromFederationGuid(federationGuid);
+        return undefined;
+    }
+    /**
+     * Helper function for [[prepareSourceChanges]]. Records how to find the target relationship of a deleted source relationship.
+     * @param deletion the deleted source relationship.
+     * @param deletedScopeEsaByElementId this transformation scope's deleted ESAs in the same batch, keyed by the ID of the element that owned each one.
+     * @param deletedFederationGuidByElementId federation GUIDs of the elements deleted in the same batch, for endpoints that no longer exist in the source.
+     */
+    async processDeletedRelationship(deletion, deletedScopeEsaByElementId, deletedFederationGuidByElementId) {
+        const { ecInstanceId } = deletion;
+        const classFullName = this.sourceDb.getClassNameFromId(deletion.ecClassId);
+        const getEndpointInTarget = async (sourceId) => this.findTargetElementIdForDeletion(sourceId, this.sourceDb.elements.tryGetElement(sourceId)?.federationGuid ??
+            deletedFederationGuidByElementId.get(sourceId), deletedScopeEsaByElementId);
+        const sourceIdInTarget = await getEndpointInTarget(deletion.sourceECInstanceId);
+        const targetIdInTarget = await getEndpointInTarget(deletion.targetECInstanceId);
+        const isProvenanceSource = this.sourceDb === (await this._provenanceManager.getProvenanceSourceDb());
+        const queryRelationshipProvenance = async () => this._provenanceManager.queryProvenanceForRelationship(ecInstanceId, {
+            classFullName,
+            sourceId: deletion.sourceECInstanceId,
+            targetId: deletion.targetECInstanceId,
+        });
+        if (sourceIdInTarget && targetIdInTarget) {
+            // relationships with ESA provenance must have their aspect deleted too, even when the target relationship is found by endpoints
+            const provenanceAspectId = this._options.forceExternalSourceAspectProvenance && isProvenanceSource
+                ? (await queryRelationshipProvenance())?.aspectId
+                : undefined;
+            this._deletedSourceRelationshipData?.set(ecInstanceId, {
+                classFullName,
+                sourceIdInTarget,
+                targetIdInTarget,
+                provenanceAspectId,
+            });
+            this._pendingRelationshipDeleteTargets.add(relationshipEndpointsKey(sourceIdInTarget, targetIdInTarget));
+        }
+        else if (isProvenanceSource) {
+            const relProvenance = await queryRelationshipProvenance();
+            if (relProvenance && relProvenance.relationshipId) {
+                this._deletedSourceRelationshipData?.set(ecInstanceId, {
+                    classFullName,
+                    relId: relProvenance.relationshipId,
+                    provenanceAspectId: relProvenance.aspectId,
                 });
-                if (relProvenance && relProvenance.relationshipId)
-                    this._deletedSourceRelationshipData?.set(changedInstanceId, {
-                        classFullName: classFullName ?? "",
-                        relId: relProvenance.relationshipId,
-                        provenanceAspectId: relProvenance.aspectId,
-                    });
+                this._pendingRelationshipDeleteTargets.add(relProvenance.relationshipId);
             }
         }
-        else {
-            let targetId = await getTargetIdFromSourceId(changedInstanceId);
-            if (targetId === undefined &&
-                this.sourceDb === (await this.provenanceSourceDb())) {
-                targetId = await this._queryProvenanceForElement(changedInstanceId);
-            }
-            // since we are processing one changeset at a time, we can see local source deletes
-            // of entities that were never synced and can be safely ignored
-            const deletionNotInTarget = !targetId;
-            if (deletionNotInTarget)
-                return;
-            if (targetId === undefined) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetId should aquired from source id or element provenance");
-            }
-            this.context.remapElement(changedInstanceId, targetId);
-            // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
-            // In such case an entity update will be triggered and we no longer need to delete the entity.
-            if (alreadyImportedElementInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.element.deleteIds.delete(changedInstanceId);
-            }
-            if (alreadyImportedModelInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.model.deleteIds.delete(changedInstanceId);
-            }
+    }
+    /**
+     * Helper function for [[prepareSourceChanges]]. Remaps a deleted source element or model to its target.
+     * @param sourceId the deleted source element or model.
+     * @param federationGuid the deleted source element's federation GUID, if it had one. Undefined for models.
+     * @param deletedScopeEsaByElementId this transformation scope's deleted ESAs in the same batch, keyed by the ID of the element that owned each one.
+     * @param alreadyImportedElementInserts used to handle entity recreation and not delete already handled element inserts.
+     * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
+     */
+    async processDeletedElement(sourceId, federationGuid, deletedScopeEsaByElementId, alreadyImportedElementInserts, alreadyImportedModelInserts) {
+        let targetId = await this.findTargetElementIdForDeletion(sourceId, federationGuid, deletedScopeEsaByElementId);
+        if (targetId === undefined &&
+            this.sourceDb === (await this._provenanceManager.getProvenanceSourceDb())) {
+            const contextTargetId = this.context.findTargetElementId(sourceId);
+            if (core_bentley_1.Id64.isValidId64(contextTargetId))
+                targetId = contextTargetId;
+        }
+        // Entities inserted and deleted since the last synchronization were never synced and can be safely ignored.
+        if (!targetId)
+            return;
+        this.context.remapElement(sourceId, targetId);
+        // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
+        // In such case an entity update will be triggered and we no longer need to delete the entity.
+        if (alreadyImportedElementInserts.has(targetId)) {
+            this.exporter.sourceDbChanges?.element.deleteIds.delete(sourceId);
+        }
+        if (alreadyImportedModelInserts.has(targetId)) {
+            this.exporter.sourceDbChanges?.model.deleteIds.delete(sourceId);
         }
     }
     async _tryInitChangesetData(args) {
@@ -2113,11 +1652,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this._sourceChangeDataState = "unconnected";
             return;
         }
-        const syncVersion = await this.synchronizationVersion();
+        const syncVersion = await this.getSynchronizationVersion();
         const noChanges = syncVersion.index === this.sourceDb.changeset.index;
         if (noChanges) {
             this._sourceChangeDataState = "no-changes";
-            this._csFileProps = [];
+            this._changesetRanges = [];
             return;
         }
         const startChangeset = "startChangeset" in args ? args.startChangeset : undefined;
@@ -2136,37 +1675,48 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             ?.ignoreMissingChangesetsInSynchronizations &&
             startChangesetIndex !== syncVersion.index + 1 &&
             syncVersion.index !== -1) {
-            throw Error(`synchronization is ${missingChangesets ? "missing changesets" : ""},` +
-                " startChangesetId should be" +
-                " exactly the first changeset *after* the previous synchronization to not miss data." +
-                ` You specified '${startChangesetIndexOrId}' which is changeset #${startChangesetIndex}` +
-                ` but the previous synchronization for this targetScopeElem ${syncVersion.id}'` +
-                ` which is changeset #${syncVersion.index}. The transformer expected` +
-                ` #${syncVersion.index + 1}.`);
-        }
-        nodeAssert(this._targetScopeProvenanceProps, "_targetScopeProvenanceProps should be set by now");
-        const changesetsToSkip = (await this.getIsReverseSynchronization())
-            ? this._targetScopeProvenanceProps.jsonProperties
-                .pendingReverseSyncChangesetIndices
-            : this._targetScopeProvenanceProps.jsonProperties
-                .pendingSyncChangesetIndices;
+            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}`);
-        const csFileProps = [];
-        for (const [first, end] of this._changesetRanges) {
-            // TODO: should the first changeset in a reverse sync really be included even though its 'initialized branch provenance'? The answer is no, its a bug that needs to be fixed.
-            const fileProps = await core_backend_1.BriefcaseManager.downloadChangesets({
-                iModelId: this.sourceDb.iModelId,
-                targetDir: core_backend_1.BriefcaseManager.getChangeSetsPath(this.sourceDb.iModelId),
-                range: { first, end },
+        /** Skipping indices found in the pendingSync and pendingReverseSync arrays can leave no ranges to process. */
+        this._sourceChangeDataState =
+            this._changesetRanges.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.",
             });
-            csFileProps.push(...fileProps);
         }
-        this._csFileProps = csFileProps;
-        /** Theres a possibility that our csFileProps length is still 0 here, since we skip cs indices found in the pendingSync and pendingReverseSync indices arrays. */
-        this._sourceChangeDataState =
-            this._csFileProps.length === 0 ? "no-changes" : "has-changes";
     }
     /**
      * The behavior of process is influenced by [[IModelTransformOptions.argsForProcessChanges]] being defined or not defined during construction passed of the IModelTransformer.
@@ -2202,47 +1752,35 @@ 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) {
-            // The RepositoryModel and root Subject of the target iModel should not be transformed.
-            await this.exporter.exportChildElements(core_common_1.IModel.rootSubjectId); // start below the root Subject
-            await this.exporter.exportModelContents(core_common_1.IModel.repositoryModelId, core_backend_1.Element.classFullName, true); // after the Subject hierarchy, process the other elements of the RepositoryModel
-            await this.exporter.exportSubModels(core_common_1.IModel.repositoryModelId); // start below the RepositoryModel
-        }
-        else {
-            await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
-        }
-        await this.completePartiallyCommittedElements();
-        await this.exporter["exportAllAspects"](); // eslint-disable-line @typescript-eslint/dot-notation
+        await this.exporter.elementAspectExportCoordinator.run(async () => {
+            if (this._options.skipPropagateChangesToRootElements) {
+                // The RepositoryModel and root Subject of the target iModel should not be transformed.
+                await this.exporter.exportChildElements(core_common_1.IModel.rootSubjectId); // start below the root Subject
+                await this.exporter.exportModelContents(core_common_1.IModel.repositoryModelId, core_backend_1.Element.classFullName, true); // after the Subject hierarchy, process the other elements of the RepositoryModel
+                await this.exporter.exportSubModels(core_common_1.IModel.repositoryModelId); // start below the RepositoryModel
+            }
+            else {
+                await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
+            }
+            await this.completePartiallyCommittedElements();
+        });
         await this.completePartiallyCommittedAspects();
         await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
         if (this._options.forceExternalSourceAspectProvenance &&
-            this.shouldDetectDeletes()) {
+            (await this.shouldDetectDeletes())) {
             core_bentley_1.Logger.logWarning(loggerCategory, "This workflows was deprecated in v1 and is no longer supported");
-            //   await this.detectElementDeletes();
-            //   await this.detectRelationshipDeletes();
         }
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
         await 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,
-                };
-    }
     /** Export changes from the source iModel and import the transformed entities into the target iModel.
      * Inserts, updates, and deletes are determined by inspecting the changeset(s).
      * @note the transformer assumes that you saveChanges after processing changes. You should not
@@ -2253,6 +1791,8 @@ 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(await this.getExportInitOpts(options));
         await this.completePartiallyCommittedElements();
@@ -2262,7 +1802,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.importer.computeProjectExtents();
         await this.finalizeTransformation();
         const defaultSaveTargetChanges = () => {
-            this.targetDb.saveChanges();
+            this._targetEditTxn.saveChanges();
         };
         await (options.saveTargetChanges ?? defaultSaveTargetChanges)(this);
     }
@@ -2272,20 +1812,24 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     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,
-            ...(this._csFileProps
-                ? { csFileProps: this._csFileProps }
-                : this._changesetRanges
-                    ? { changesetRanges: this._changesetRanges }
-                    : startChangeset
-                        ? { startChangeset }
-                        : {
-                            startChangeset: {
-                                index: (await this.synchronizationVersion()).index + 1,
-                            },
-                        }),
+            ...(this._changesetRanges
+                ? { changesetRanges: this._changesetRanges }
+                : startChangeset
+                    ? { startChangeset }
+                    : {
+                        startChangeset: {
+                            index: (await this.getSynchronizationVersion()).index + 1,
+                        },
+                    }),
         };
     }
     /** Combine an array of source elements into a single target element.
@@ -2310,16 +1854,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
@@ -2370,7 +1912,13 @@ class TemplateModelCloner extends IModelTransformer {
             // TODO: consider going through all definition elements at once and remapping them to themselves
             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);
@@ -2379,7 +1927,13 @@ 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`,
+                        });
                     }
                 }
             }
@@ -2392,7 +1946,7 @@ class TemplateModelCloner extends IModelTransformer {
             const placementClass = is3d ? core_common_1.Placement3d : core_common_1.Placement2d;
             const placement = placementClass.fromJSON(targetElementProps.placement);
             if (placement.isValid) {
-                nodeAssert(this._transform3d);
+                (0, node_assert_1.strict)(this._transform3d);
                 placement.multiplyTransform(this._transform3d);
                 targetElementProps.placement = placement;
             }
@@ -2402,17 +1956,4 @@ class TemplateModelCloner extends IModelTransformer {
     }
 }
 exports.TemplateModelCloner = TemplateModelCloner;
-//Deprecate in preference of imodeldb.elements.getFederationGuidFromId()?
-async function queryElemFedGuid(db, elemId) {
-    const sql = `
-    SELECT FederationGuid
-    FROM bis.Element
-    WHERE ECInstanceId=?
-  `;
-    const params = new core_common_1.QueryBinder().bindId(1, elemId);
-    const reader = db.createQueryReader(sql, params);
-    (0, core_bentley_1.assert)(await reader.step(), "element not found");
-    const result = reader.current.federationGuid;
-    return result;
-}
 //# sourceMappingURL=IModelTransformer.js.map