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

package/lib/cjs/IModelTransformer.d.ts

@@ -1,11 +1,23 @@
-import { Id64Array, Id64Set, Id64String } from "@itwin/core-bentley";
+import { GuidString, Id64Array, Id64Set, Id64String } from "@itwin/core-bentley";
 import * as ECSchemaMetaData from "@itwin/ecschema-metadata";
 import { Transform } from "@itwin/core-geometry";
-import { Element, ElementAspect, ElementMultiAspect, ElementUniqueAspect, Entity, ExternalSourceAspect, IModelDb, Model, Relationship, RelationshipProps } from "@itwin/core-backend";
+import { EditTxn, Element, ElementAspect, ElementMultiAspect, ElementUniqueAspect, Entity, ExternalSourceAspect, IModelDb, Model, Relationship, RelationshipProps } from "@itwin/core-backend";
 import { ChangesetIndexAndId, CodeSpec, ElementAspectProps, ElementProps, ExternalSourceAspectProps, FontProps, Helmert2DWithZOffset, ModelProps, Placement2d, Placement3d } from "@itwin/core-common";
 import { ChangedInstanceIds, ExportChangesOptions, ExportSchemaResult, IModelExporter, IModelExportHandler } from "./IModelExporter";
 import { IModelImporter, OptimizeGeometryOptions } from "./IModelImporter";
-import { IModelCloneContext } from "./IModelCloneContext";
+import type { IModelTransformContext } from "./IModelTransformContext";
+import { ProvenanceManager } from "./ProvenanceManager";
+import { ProcessSchemasOptions } from "./schema-processing/SchemaProcessingStrategy";
+import { CollectedChanges } from "./ChangesetScanner";
+/** Required arguments for the [[IModelTransformer]] constructor.
+ * @beta
+ */
+export interface IModelTransformArgs {
+    /** The source iModel or exporter to read elements from. */
+    source: IModelDb | IModelExporter;
+    /** The target for the transformation. Pass an [[EditTxn]] to have the transformer create a default [[IModelImporter]], or pass a pre-configured [[IModelImporter]]. */
+    target: EditTxn | IModelImporter;
+}
 /** Options provided to the [[IModelTransformer]] constructor.
  * @beta
  * @note if adding an option, you must explicitly add its serialization to [[IModelTransformer.saveStateToFile]]!
@@ -122,6 +134,13 @@ export interface IModelTransformOptions {
      * @default false
      */
     tryAlignGeolocation?: boolean;
+    /** An optional [[EditTxn]] for write operations on the **source** iModel.
+     * Only needed for reverse synchronization workflows where provenance must be written back to the source.
+     * If not provided, the source iModel is treated as read-only.
+     * Must be started before calling [[IModelTransformer.process]].
+     * @beta
+     */
+    sourceEditTxn?: EditTxn;
 }
 /**
  * Data type for persisting change version information within provenance Scope ExternalSourceAspect.
@@ -164,7 +183,7 @@ export interface InitOptions {
  * @beta
  */
 export type ProcessChangesOptions = ExportChangesOptions & {
-    /** how to call saveChanges on the target. Must call targetDb.saveChanges, should not edit the iModel */
+    /** how to save changes on the target. Must call `editTxn.saveChanges()` on the target EditTxn, should not edit the iModel */
     saveTargetChanges?: (transformer: IModelTransformer) => Promise<void>;
     /**
      * The forward sync 'version' to set on the scoping ESA @see ExternalSourceAspectProps upon startup, if the version property on the scoping ESA is undefined or empty string.
@@ -202,6 +221,7 @@ export interface RelationshipPropsForDelete {
 export declare class IModelTransformer extends IModelExportHandler {
     /** The IModelExporter that will export from the source iModel. */
     readonly exporter: IModelExporter;
+    private readonly _schemaProcessingCoordinator;
     /** The IModelImporter that will import into the target iModel. */
     readonly importer: IModelImporter;
     /** The normally read-only source iModel.
@@ -210,8 +230,10 @@ export declare class IModelTransformer extends IModelExportHandler {
     readonly sourceDb: IModelDb;
     /** The read/write target iModel. */
     readonly targetDb: IModelDb;
-    /** The IModelTransformContext for this IModelTransformer. */
-    readonly context: IModelCloneContext;
+    /** The supported transformation context for this transformer. */
+    get context(): IModelTransformContext;
+    /** The clone context used by the transformer implementation. */
+    private readonly _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
@@ -221,47 +243,38 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @beta
      */
     private _linearSpatialTransform?;
-    private _syncType?;
+    /** The [[EditTxn]] used for write operations on the target iModel.
+     * The caller is responsible for starting, committing or abandoning this transaction.
+     * @beta
+     */
+    protected readonly _targetEditTxn: EditTxn;
+    /** The optional [[EditTxn]] used for write operations on the source iModel during reverse synchronization.
+     * @beta
+     */
+    protected readonly _sourceEditTxn?: EditTxn;
+    private _syncTypeResolver;
+    protected _provenanceManager: 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(): Id64String;
     /** a set of elements for which source provenance will be explicitly tracked by ExternalSourceAspects */
     protected _elementsWithExplicitlyTrackedProvenance: Set<string>;
     protected _partiallyCommittedElementIds: Id64Set;
     protected _partiallyCommittedAspectIds: Id64Set;
-    /** the options that were used to initialize this transformer */
-    private readonly _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).
      */
-    private _allowNoScopingESA;
-    static noEsaSyncDirectionErrorMessage: string;
-    /**
-     * Queries for an esa which matches the props in the provided aspectProps.
-     * @param dbToQuery db to run the query on for scope external source
-     * @param aspectProps aspectProps to search for @see ExternalSourceAspectProps
-     */
-    static queryScopeExternalSourceAspect(dbToQuery: IModelDb, aspectProps: ExternalSourceAspectProps): Promise<{
-        aspectId: Id64String;
-        version?: string;
-        /** stringified json */
-        jsonProperties?: string;
-    } | undefined>;
+    private _targetElementIdsRemappedByCode;
     /**
-     * Determines the sync direction "forward" or "reverse" of a given sourceDb and targetDb by looking for the scoping ESA.
-     * If the sourceDb's iModelId is found as the identifier of the expected scoping ESA in the targetDb, then it is a forward synchronization.
-     * If the targetDb's iModelId is found as the identifier of the expected scoping ESA in the sourceDb, then it is a reverse synchronization.
-     * @throws if no scoping ESA can be found in either the sourceDb or targetDb which describes a master branch relationship between the two databases.
-     * @returns "forward" or "reverse"
-     */
-    static determineSyncType(sourceDb: IModelDb, targetDb: IModelDb, 
-    /** @see [[IModelTransformOptions.targetScopeElementId]] */
-    targetScopeElementId: Id64String): Promise<"forward" | "reverse">;
-    private determineSyncType;
-    getIsReverseSynchronization(): Promise<boolean>;
-    getIsForwardSynchronization(): Promise<boolean>;
+     * 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).
+     */
+    private _targetModelsImportedInCurrentTransform;
+    /** the options that were used to initialize this transformer */
+    private readonly _options;
     private _changesetRanges;
     /**
      * Set if the transformer is being used to perform the provenance initialization step of a fork initialization.
@@ -273,11 +286,10 @@ export declare class IModelTransformer extends IModelExportHandler {
     /** The element aspect classes that are considered to define provenance in the iModel */
     static get provenanceElementAspectClasses(): (typeof Entity)[];
     /** 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: IModelDb | IModelExporter, target: IModelDb | IModelImporter, options?: IModelTransformOptions);
+    constructor(args: IModelTransformArgs, options?: IModelTransformOptions);
     /** validates that the importer set on the transformer has the same values for its shared options as the transformer.
      *  @note This expects that the importer is already set on the transformer.
      */
@@ -286,28 +298,6 @@ export declare class IModelTransformer extends IModelExportHandler {
     dispose(): void;
     /** Log current settings that affect IModelTransformer's behavior. */
     private logSettings;
-    /** 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]].
-     */
-    provenanceDb(): Promise<IModelDb>;
-    /** 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]].
-     */
-    provenanceSourceDb(): Promise<IModelDb>;
-    /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
-    static initElementProvenanceOptions(sourceElementId: Id64String, targetElementId: Id64String, args: {
-        sourceDb: IModelDb;
-        targetDb: IModelDb;
-        isReverseSynchronization: boolean;
-        targetScopeElementId: Id64String;
-    }): ExternalSourceAspectProps;
-    static initRelationshipProvenanceOptions(sourceRelInstanceId: Id64String, targetRelInstanceId: Id64String, args: {
-        sourceDb: IModelDb;
-        targetDb: IModelDb;
-        isReverseSynchronization: boolean;
-        targetScopeElementId: Id64String;
-        forceOldRelationshipProvenanceMethod: boolean;
-    }): Promise<ExternalSourceAspectProps>;
     /**
      * 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
@@ -317,26 +307,6 @@ export declare class IModelTransformer extends IModelExportHandler {
     private _forceOldRelationshipProvenanceMethod;
     /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
     initElementProvenance(sourceElementId: Id64String, targetElementId: Id64String): Promise<ExternalSourceAspectProps>;
-    /** 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.
-     */
-    private initRelationshipProvenance;
-    /** NOTE: the json properties must be converted to string before insertion */
-    private _targetScopeProvenanceProps;
-    /**
-     * 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.
-     */
-    private _startingChangesetIndices;
-    private _cachedSynchronizationVersion;
-    /**
-     * 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.
-     */
-    private clearCachedSynchronizationVersion;
     /** the changeset in the scoping element's source version found for this transformation
      * @note the version depends on whether this is a reverse synchronization or not, as
      * it is stored separately for both synchronization directions.
@@ -344,7 +314,7 @@ export declare class IModelTransformer extends 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"
      */
-    protected synchronizationVersion(): Promise<ChangesetIndexAndId>;
+    protected getSynchronizationVersion(): Promise<ChangesetIndexAndId>;
     /**
      * @returns provenance scope aspect if it exists in the provenanceDb.
      * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
@@ -353,63 +323,32 @@ export declare class IModelTransformer extends IModelExportHandler {
     /**
      * 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)
      */
     protected initScopeProvenance(): Promise<void>;
-    /** Returns true if a change was made to the aspectProps. */
-    private handleUnsafeMigrate;
     /**
-     * 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
-     */
-    static forEachTrackedElement(args: {
-        provenanceSourceDb: IModelDb;
-        provenanceDb: IModelDb;
-        targetScopeElementId: Id64String;
-        isReverseSynchronization: boolean;
-        fn: (sourceElementId: Id64String, targetElementId: Id64String) => void;
-        skipPropagateChangesToRootElements: boolean;
-    }): Promise<void>;
-    private forEachTrackedElement;
+     * 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.
+     */
+    getProvenanceDb(): Promise<IModelDb>;
     /**
-     * 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.
      */
-    private _queryProvenanceForElement;
+    getIsReverseSynchronization(): Promise<boolean>;
+    /**
+     * Get whether this is a forward synchronization.
+     */
+    getIsForwardSynchronization(): Promise<boolean>;
     /**
-     * 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
-     */
-    private _queryProvenanceForRelationship;
-    private _queryTargetRelId;
-    private _targetClassNameToClassIdCache;
-    private _targetClassNameToClassId;
-    private _getRelClassId;
-    private _queryElemIdByFedGuid;
+     * Updates the synchronization version on the scope ESA.
+     */
+    updateSynchronizationVersion({ initializeReverseSyncVersion, }?: {
+        initializeReverseSyncVersion?: boolean | undefined;
+    }): Promise<void>;
     /** 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.
      */
-    protected shouldDetectDeletes(): boolean;
-    /**
-     * 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.
-     */
+    protected shouldDetectDeletes(): Promise<boolean>;
     /** 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.
@@ -428,47 +367,75 @@ export declare class IModelTransformer extends IModelExportHandler {
     static convertHelmertToTransform(helmert: Helmert2DWithZOffset | undefined): Transform;
     calculateTransformFromHelmertTransforms(): Transform | undefined;
     private _deletedSourceRelationshipData?;
+    /** Target relationship ids and target endpoint keys of [[_deletedSourceRelationshipData]] entries, for fast matching in [[onExportRelationship]]. */
+    private _pendingRelationshipDeleteTargets;
+    /** 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.
+     */
+    private _reimportedTargetRelationshipIds;
     /** 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.
      */
     protected hasElementChanged(sourceElement: Element): boolean;
     protected completePartiallyCommittedElements(): Promise<void>;
     protected completePartiallyCommittedAspects(): Promise<void>;
+    /** 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.
+     */
+    private markSourceEntityExists;
     private doAllReferencesExistInTarget;
-    private assertReferenceExistsInSource;
+    /** 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.
+     */
+    private assertReferencesExistInSource;
     /** 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.
      */
     processElement(sourceElementId: Id64String): Promise<void>;
     /** 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.
      */
     processChildElements(sourceElementId: Id64String): Promise<void>;
+    private processScopedElementExport;
     /** 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: Element): boolean;
+    shouldExportElement(_sourceElement: Element): Promise<boolean>;
     /**
      * If they haven't been already, import all of the required references
      * @internal do not call, override or implement this, it will be removed
      */
     preExportElement(sourceElement: Element): Promise<void>;
+    /** 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.
+     */
+    private resolveRequiredElement;
+    /** 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.
+     */
+    private findExistingTargetElement;
     private getElemTransformState;
+    private queryElementIdByCode;
     /** Override of [IModelExportHandler.onExportElement]($transformer) that imports an element into the target iModel when it is exported from the source iModel.
      * This override calls [[onTransformElement]] and then [IModelImporter.importElement]($transformer) to update the target iModel.
      */
     onExportElement(sourceElement: Element): Promise<void>;
-    /** 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: Id64String): void;
+    /** Maps the deleted source element IDs and passes the target IDs to the importer as one set. */
+    onDeleteElements(sourceElementIds: ReadonlySet<Id64String>): Promise<void>;
     /** 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: Model): void;
+    onExportModel(sourceModel: Model): Promise<void>;
     /** Override of [IModelExportHandler.onDeleteModel]($transformer) that is called when [IModelExporter]($transformer) detects that a [Model]($backend) has been deleted from the source iModel. */
     onDeleteModel(sourceModelId: Id64String): Promise<void>;
     /** Schedule modeled partition deletion */
@@ -476,6 +443,7 @@ export declare class IModelTransformer extends 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.
      */
     processModel(sourceModeledElementId: Id64String): Promise<void>;
     /** Cause the model contents to be exported from the source iModel and imported into the target iModel.
@@ -483,6 +451,7 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @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.
      */
     processModelContents(sourceModelId: Id64String, targetModelId: Id64String, elementClassFullName?: string): Promise<void>;
     /** Cause all sub-models that recursively descend from the specified Subject to be exported from the source iModel and imported into the target iModel. */
@@ -494,59 +463,35 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @note A subclass can override this method to provide custom transform behavior.
      */
     onTransformModel(sourceModel: Model, targetModeledElementId: Id64String): ModelProps;
-    /**
-     * Called at the end of a transformation,
-     * updates the target scope element to say that transformation up through the
-     * source's changeset has been performed. Also stores all changesets that occurred
-     * during the transformation as "pending synchronization changeset indices" @see TargetScopeProvenanceJsonProps
-     *
-     * You generally should not call this function yourself and use [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided instead.
-     * It is public for unsupported use cases of custom synchronization transforms.
-     * @note If [[IModelTransformOptions.argsForProcessChanges]] is not defined in this transformation, this function will return early without updating the sync version,
-     * unless the `initializeReverseSyncVersion` option is set to `true`
-     *
-     * The `initializeReverseSyncVersion` is added to set the reverse synchronization version during a forward synchronization.
-     * When set to `true`, it saves the reverse sync version as the current changeset of the targetDb. This is typically used for the first transformation between a master and branch iModel.
-     * Setting `initializeReverseSyncVersion` to `true` has the effect of making it so any changesets in the branch iModel at the time of the first transformation will be ignored during any future reverse synchronizations from the branch to the master iModel.
-     *
-     * Note that typically, the reverseSyncVersion is saved as the last changeset merged from the branch into master.
-     * Setting initializeReverseSyncVersion to true during a forward transformation could overwrite this correct reverseSyncVersion and should only be done during the first transformation between a master and branch iModel.
-     */
-    updateSynchronizationVersion({ initializeReverseSyncVersion, }?: {
-        initializeReverseSyncVersion?: boolean | undefined;
-    }): Promise<void>;
+    /** Complete a high-level transformation after all export operations finish. */
     private finalizeTransformation;
+    private setCodeValueBehavior;
     /** 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.
      */
     processRelationships(baseRelClassFullName: string): Promise<void>;
     /** 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: Relationship): boolean;
+    shouldExportRelationship(_sourceRelationship: Relationship): Promise<boolean>;
     /** Override of [IModelExportHandler.onExportRelationship]($transformer) that imports a relationship into the target iModel when it is exported from the source iModel.
      * This override calls [[onTransformRelationship]] and then [IModelImporter.importRelationship]($transformer) to update the target iModel.
      */
-    onExportRelationship(sourceRelationship: Relationship): Promise<void>;
+    onExportRelationship(sourceRelationship: Relationship, _isUpdate?: boolean, sourceFedGuid?: GuidString, targetFedGuid?: GuidString): Promise<void>;
     /** Override of [IModelExportHandler.onDeleteRelationship]($transformer) that is called when [IModelExporter]($transformer) detects that a [Relationship]($backend) has been deleted from the source iModel.
      * This override propagates the delete to the target iModel via [IModelImporter.deleteRelationship]($transformer).
      */
     onDeleteRelationship(sourceRelInstanceId: Id64String): Promise<void>;
-    private _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.
-     */
     /** 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.
      * @note A subclass can override this method to provide custom transform behavior.
      */
     protected onTransformRelationship(sourceRelationship: Relationship): RelationshipProps;
-    shouldExportElementAspect(aspect: ElementAspect): boolean;
+    shouldExportElementAspect(aspect: ElementAspect): Promise<boolean>;
+    private prepareElementAspects;
     /** 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.
      */
@@ -567,29 +512,25 @@ export declare class IModelTransformer extends 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: ECSchemaMetaData.SchemaKey): boolean;
-    private _longNamedSchemasMap;
-    /** 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.
+    shouldExportSchema(schemaKey: ECSchemaMetaData.SchemaKey): Promise<boolean>;
+    /** 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`.
      */
     onExportSchema(schema: ECSchemaMetaData.Schema): Promise<void | ExportSchemaResult>;
-    private _makeLongNameResolvingSchemaCtx;
-    /** 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.
      */
-    processSchemas(): Promise<void>;
+    processSchemas(options?: ProcessSchemasOptions): Promise<void>;
     /** 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.
      */
     processFonts(): Promise<void>;
     /** Override of [IModelExportHandler.onExportFont]($transformer) that imports a font into the target iModel when it is exported from the source iModel. */
-    onExportFont(font: FontProps, _isUpdate: boolean | undefined): void;
+    onExportFont(font: FontProps, _isUpdate: boolean | undefined): Promise<void>;
     /** 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.
      */
@@ -601,16 +542,17 @@ export declare class IModelTransformer extends 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: CodeSpec): boolean;
+    shouldExportCodeSpec(_sourceCodeSpec: CodeSpec): Promise<boolean>;
     /** Override of [IModelExportHandler.onExportCodeSpec]($transformer) that imports a CodeSpec into the target iModel when it is exported from the source iModel. */
-    onExportCodeSpec(sourceCodeSpec: CodeSpec): void;
-    /** Recursively import all Elements and sub-Models that descend from the specified Subject */
+    onExportCodeSpec(sourceCodeSpec: CodeSpec): Promise<void>;
+    /** 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.
+     */
     processSubject(sourceSubjectId: Id64String, targetSubjectId: Id64String): Promise<void>;
     /** state to prevent reinitialization, @see [[initialize]] */
     private _initialized;
     private _sourceChangeDataState;
-    /** length === 0 when _changeDataState = "no-change", length > 0 means "has-changes", otherwise undefined  */
-    private _csFileProps?;
+    private _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.
@@ -618,13 +560,34 @@ export declare class IModelTransformer extends IModelExportHandler {
      * Overriders must call `super.initialize()` first
      */
     initialize(): Promise<void>;
+    private initializeChangesetScanAndExporter;
     /**
-     * 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
+     * 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
+     */
+    protected collectChanges(ranges: readonly (readonly [number, number])[], changedInstanceIds?: ChangedInstanceIds): Promise<CollectedChanges>;
+    /**
+     * 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.
      */
-    private processChangesets;
+    private prepareSourceChanges;
     /**
      * This will be called when transformer is called with [[IModelTransformOptions.argsForProcessChanges]] to process changes.
      * It will be executed after changes in changesets are populated into `sourceDbChanges` and before data processing begins.
@@ -635,17 +598,33 @@ export declare class IModelTransformer extends IModelExportHandler {
      */
     protected addCustomChanges(_sourceDbChanges: ChangedInstanceIds): Promise<void>;
     /**
-     * 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
+     * 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.
+     */
+    private findTargetElementIdForDeletion;
+    /**
+     * 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.
+     */
+    private processDeletedRelationship;
+    /**
+     * 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.
-     * @returns void
      */
-    private processDeletedOp;
+    private processDeletedElement;
     private _tryInitChangesetData;
+    /** Asserts that the EditTxn is active before any write operations. */
+    private assertEditTxnActive;
     /**
      * The behavior of process is influenced by [[IModelTransformOptions.argsForProcessChanges]] being defined or not defined during construction passed of the IModelTransformer.
      * @section When argsForProcessChanges are defined:
@@ -674,9 +653,6 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
      */
     private processAll;
-    /** previous provenance, either a federation guid, a `${sourceFedGuid}/${targetFedGuid}` pair, or required aspect props */
-    private _lastProvenanceEntityInfo;
-    private markLastProvenance;
     /** 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
@@ -707,12 +683,10 @@ export declare class TemplateModelCloner extends IModelTransformer {
     /** Accumulates the mapping of sourceElementIds to targetElementIds from the elements in the template model that were cloned. */
     private _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: IModelDb, targetDb?: IModelDb);
+    constructor(editTxn: EditTxn);
     /** 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
      * @param targetModelId The Id of the target model (must be a subclass of GeometricModel3d) where the cloned component will be inserted.