@itwin/imodel-transformer 0.1.3-dev.0 → 0.1.4

package/lib/cjs/IModelTransformer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TemplateModelCloner = exports.IModelTransformer = void 0;
+exports.TemplateModelCloner = exports.IModelTransformer = exports.TransformerEvent = void 0;
 /*---------------------------------------------------------------------------------------------
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
@@ -9,6 +9,7 @@ exports.TemplateModelCloner = exports.IModelTransformer = void 0;
  * @module iModels
  */
 const path = require("path");
+const events_1 = require("events");
 const Semver = require("semver");
 const nodeAssert = require("assert");
 const core_bentley_1 = require("@itwin/core-bentley");
@@ -85,39 +86,74 @@ function mapId64(idContainer, func) {
     }
     return results;
 }
+/** events that the transformer emits, e.g. for signaling profilers @internal */
+var TransformerEvent;
+(function (TransformerEvent) {
+    TransformerEvent["beginProcessSchemas"] = "beginProcessSchemas";
+    TransformerEvent["endProcessSchemas"] = "endProcessSchemas";
+    TransformerEvent["beginProcessAll"] = "beginProcessAll";
+    TransformerEvent["endProcessAll"] = "endProcessAll";
+    TransformerEvent["beginProcessChanges"] = "beginProcessChanges";
+    TransformerEvent["endProcessChanges"] = "endProcessChanges";
+})(TransformerEvent = exports.TransformerEvent || (exports.TransformerEvent = {}));
 /** Base class used to transform a source iModel into a different target iModel.
  * @see [iModel Transformation and Data Exchange]($docs/learning/transformer/index.md), [IModelExporter]($transformer), [IModelImporter]($transformer)
  * @beta
  */
 class IModelTransformer extends IModelExporter_1.IModelExportHandler {
+    /** 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;
+    }
+    /** 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];
+    }
+    /** The element aspect classes that are considered to define provenance in the iModel */
+    static get provenanceElementAspectClasses() {
+        return [core_backend_1.ExternalSourceAspect];
+    }
     /** 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 options The options that specify how the transformation should be done.
      */
     constructor(source, target, options) {
-        var _a, _b, _c, _d, _e;
         super();
         /** map of (unprocessed element, referencing processed element) pairs to the partially committed element that needs the reference resolved
          * and have some helper methods below for now */
         this._pendingReferences = new PendingReferenceMap_1.PendingReferenceMap();
         /** map of partially committed entities to their partial commit progress */
         this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
+        /**
+         * Internal event emitter that is used by the transformer to signal events to profilers
+         * @internal
+         */
+        this.events = new events_1.EventEmitter();
+        this._targetScopeProvenanceProps = undefined;
+        this._cachedTargetScopeVersion = undefined;
+        // if undefined, it can be initialized by calling [[this._cacheSourceChanges]]
+        this._hasElementChangedCache = undefined;
+        this._deletedSourceRelationshipData = undefined;
         this._yieldManager = new core_bentley_1.YieldManager();
         /** The directory where schemas will be exported, a random temporary directory */
         this._schemaExportDir = path.join(core_backend_1.KnownLocations.tmpdir, core_bentley_1.Guid.createValue());
         this._longNamedSchemasMap = new Map();
         /** state to prevent reinitialization, @see [[initialize]] */
         this._initialized = false;
+        /** length === 0 when _changeDataState = "no-change", length > 0 means "has-changes", otherwise undefined  */
+        this._changeSummaryIds = undefined;
+        this._changeDataState = "uninited";
+        /** previous provenance, either a federation guid, a `${sourceFedGuid}/${targetFedGuid}` pair, or required aspect props */
         this._lastProvenanceEntityInfo = nullLastProvenanceEntityInfo;
         // initialize IModelTransformOptions
         this._options = {
             ...options,
             // non-falsy defaults
-            cloneUsingBinaryGeometry: (_a = options === null || options === void 0 ? void 0 : options.cloneUsingBinaryGeometry) !== null && _a !== void 0 ? _a : true,
-            targetScopeElementId: (_b = options === null || options === void 0 ? void 0 : options.targetScopeElementId) !== null && _b !== void 0 ? _b : core_common_1.IModel.rootSubjectId,
+            cloneUsingBinaryGeometry: options?.cloneUsingBinaryGeometry ?? true,
+            targetScopeElementId: options?.targetScopeElementId ?? core_common_1.IModel.rootSubjectId,
             // eslint-disable-next-line deprecation/deprecation
-            danglingReferencesBehavior: (_d = (_c = options === null || options === void 0 ? void 0 : options.danglingReferencesBehavior) !== null && _c !== void 0 ? _c : options === null || options === void 0 ? void 0 : options.danglingPredecessorsBehavior) !== null && _d !== void 0 ? _d : "reject",
+            danglingReferencesBehavior: options?.danglingReferencesBehavior ?? options?.danglingPredecessorsBehavior ?? "reject",
         };
         this._isFirstSynchronization = this._options.wasSourceIModelCopiedToTarget ? true : undefined;
         // initialize exporter and sourceDb
@@ -129,7 +165,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         this.sourceDb = this.exporter.sourceDb;
         this.exporter.registerHandler(this);
-        this.exporter.wantGeometry = (_e = options === null || options === void 0 ? void 0 : options.loadSourceGeometry) !== null && _e !== void 0 ? _e : false; // optimization to not load source GeometryStreams by default
+        this.exporter.wantGeometry = options?.loadSourceGeometry ?? false; // optimization to not load source GeometryStreams by default
         if (!this._options.includeSourceProvenance) { // clone provenance from the source iModel into the target iModel?
             IModelTransformer.provenanceElementClasses.forEach((cls) => this.exporter.excludeElementClass(cls.classFullName));
             IModelTransformer.provenanceElementAspectClasses.forEach((cls) => this.exporter.excludeElementAspectClass(cls.classFullName));
@@ -156,18 +192,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.targetDb = this.importer.targetDb;
         // create the IModelCloneContext, it must be initialized later
         this.context = new IModelCloneContext_1.IModelCloneContext(this.sourceDb, this.targetDb);
+        this._registerEvents();
     }
-    /** 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;
-    }
-    /** 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];
-    }
-    /** The element aspect classes that are considered to define provenance in the iModel */
-    static get provenanceElementAspectClasses() {
-        return [core_backend_1.ExternalSourceAspect];
+    /** @internal */
+    _registerEvents() {
+        this.events.on(TransformerEvent.beginProcessAll, () => {
+            core_bentley_1.Logger.logTrace(loggerCategory, "processAll()");
+        });
+        this.events.on(TransformerEvent.beginProcessChanges, () => {
+            core_bentley_1.Logger.logTrace(loggerCategory, "processChanges()");
+        });
     }
     /** Dispose any native resources associated with this IModelTransformer. */
     dispose() {
@@ -196,7 +230,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     get provenanceDb() {
         return this._options.isReverseSynchronization ? this.sourceDb : this.targetDb;
     }
-    /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
+    /** Return the IModelDb where IModelTransformer will NOT store its provenance.
+     * @note This will be [[sourceDb]] except when it is a reverse synchronization. In that case it be [[targetDb]].
+     */
+    get provenanceSourceDb() {
+        return this._options.isReverseSynchronization ? this.targetDb : this.sourceDb;
+    }
     initElementProvenance(sourceElementId, targetElementId) {
         const elementId = this._options.isReverseSynchronization ? sourceElementId : targetElementId;
         const aspectIdentifier = this._options.isReverseSynchronization ? targetElementId : sourceElementId;
@@ -227,10 +266,30 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             kind: core_backend_1.ExternalSourceAspect.Kind.Relationship,
             jsonProperties: JSON.stringify({ targetRelInstanceId }),
         };
-        aspectProps.id = this.queryExternalSourceAspectId(aspectProps);
+        [aspectProps.id] = this.queryScopeExternalSource(aspectProps);
         return aspectProps;
     }
-    validateScopeProvenance() {
+    /** the changeset in the scoping element's source version found for this transformation
+     * @note: empty string and -1 for changeset and index if it has never been transformed
+     */
+    get _targetScopeVersion() {
+        if (!this._cachedTargetScopeVersion) {
+            nodeAssert(this._targetScopeProvenanceProps?.version !== undefined, "_targetScopeProvenanceProps was not set yet, or contains no version");
+            const [id, index] = this._targetScopeProvenanceProps.version === ""
+                ? ["", -1]
+                : this._targetScopeProvenanceProps.version.split(";");
+            this._cachedTargetScopeVersion = { index: Number(index), id, };
+            nodeAssert(!Number.isNaN(this._cachedTargetScopeVersion.index), "bad parse: invalid index in version");
+        }
+        return this._cachedTargetScopeVersion;
+    }
+    /**
+     * Make sure there are no conflicting other scope-type external source aspects on the *target scope element*,
+     * If there are none at all, insert one, then this must be a first synchronization.
+     * @returns the last synced version (changesetId) on the target scope's external source aspect,
+     *          (if this was a [BriefcaseDb]($backend))
+     */
+    initScopeProvenance() {
         const aspectProps = {
             classFullName: core_backend_1.ExternalSourceAspect.classFullName,
             element: { id: this.targetScopeElementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
@@ -238,10 +297,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             identifier: this._options.isReverseSynchronization ? this.targetDb.iModelId : this.sourceDb.iModelId,
             kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
         };
-        aspectProps.id = this.queryExternalSourceAspectId(aspectProps); // this query includes "identifier"
+        // FIXME: handle older transformed iModels
+        let version;
+        [aspectProps.id, version] = this.queryScopeExternalSource(aspectProps) ?? []; // this query includes "identifier"
+        aspectProps.version = version;
         if (undefined === aspectProps.id) {
+            aspectProps.version = ""; // empty since never before transformed. Will be updated in [[finalizeTransformation]]
             // 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 sql = `
+        SELECT ECInstanceId
+        FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+        WHERE Element.Id=:elementId
+          AND Scope.Id=:scopeId
+          AND Kind=:kind
+        LIMIT 1
+      `;
             const hasConflictingScope = this.provenanceDb.withPreparedStatement(sql, (statement) => {
                 statement.bindId("elementId", aspectProps.element.id);
                 statement.bindId("scopeId", aspectProps.scope.id); // this scope.id can never be invalid, we create it above
@@ -256,39 +326,97 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 this._isFirstSynchronization = true; // couldn't tell this is the first time without provenance
             }
         }
-    }
-    queryExternalSourceAspectId(aspectProps) {
-        const sql = `SELECT ECInstanceId FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Element.Id=:elementId AND Scope.Id=:scopeId AND Kind=:kind AND Identifier=:identifier LIMIT 1`;
+        this._targetScopeProvenanceProps = aspectProps;
+    }
+    queryScopeExternalSource(aspectProps) {
+        const sql = `
+      SELECT ECInstanceId, Version
+      FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+      WHERE Element.Id=:elementId
+        AND Scope.Id=:scopeId
+        AND Kind=:kind
+        AND Identifier=:identifier
+      LIMIT 1
+    `;
         return this.provenanceDb.withPreparedStatement(sql, (statement) => {
             statement.bindId("elementId", aspectProps.element.id);
             if (aspectProps.scope === undefined)
-                return undefined; // return undefined instead of binding an invalid id
+                return [undefined, undefined]; // return undefined instead of binding an invalid id
             statement.bindId("scopeId", aspectProps.scope.id);
             statement.bindString("kind", aspectProps.kind);
             statement.bindString("identifier", aspectProps.identifier);
-            return (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) ? statement.getValue(0).getId() : undefined;
+            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== statement.step())
+                return [undefined, undefined];
+            const aspectId = statement.getValue(0).getId();
+            const version = statement.getValue(1).getString();
+            return [aspectId, version];
         });
     }
-    /** Iterate all matching ExternalSourceAspects in the provenance iModel (target unless reverse sync) and call a function for each one. */
+    /**
+     * Iterate all matching 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
+     */
     forEachTrackedElement(fn) {
         if (!this.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 sql = `SELECT Identifier,Element.Id FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Scope.Id=:scopeId AND Kind=:kind`;
-        this.provenanceDb.withPreparedStatement(sql, (statement) => {
-            statement.bindId("scopeId", this.targetScopeElementId);
-            statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
-            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const aspectIdentifier = statement.getValue(0).getString(); // ExternalSourceAspect.Identifier is of type string
-                const elementId = statement.getValue(1).getId();
-                if (this._options.isReverseSynchronization) {
-                    fn(elementId, aspectIdentifier); // provenance coming from the sourceDb
+        // query for provenanceDb
+        const provenanceContainerQuery = `
+      SELECT e.ECInstanceId, FederationGuid, esa.Identifier as AspectIdentifier
+      FROM bis.Element e
+      LEFT JOIN bis.ExternalSourceAspect esa ON e.ECInstanceId=esa.Element.Id
+      WHERE e.ECInstanceId NOT IN (0x1, 0xe, 0x10) -- special non-federated iModel-local elements
+        AND ((Scope.Id IS NULL AND KIND IS NULL) OR (Scope.Id=:scopeId AND Kind=:kind))
+      ORDER BY FederationGuid
+    `;
+        // query for nonProvenanceDb, the source to which the provenance is referring
+        const provenanceSourceQuery = `
+      SELECT e.ECInstanceId, FederationGuid
+      FROM bis.Element e
+      WHERE e.ECInstanceId NOT IN (0x1, 0xe, 0x10) -- special non-federated iModel-local 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
+        this.provenanceSourceDb.withStatement(provenanceSourceQuery, (sourceStmt) => this.provenanceDb.withStatement(provenanceContainerQuery, (containerStmt) => {
+            containerStmt.bindId("scopeId", this.targetScopeElementId);
+            containerStmt.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
+            if (sourceStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
+                return;
+            let sourceRow = sourceStmt.getRow();
+            if (containerStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
+                return;
+            let containerRow = containerStmt.getRow();
+            const runFnInProvDirection = (sourceId, targetId) => this._options.isReverseSynchronization ? fn(sourceId, targetId) : fn(targetId, sourceId);
+            while (true) {
+                const currSourceRow = sourceRow, currContainerRow = containerRow;
+                if (currSourceRow.federationGuid !== undefined
+                    && currContainerRow.federationGuid !== undefined
+                    && currSourceRow.federationGuid === currContainerRow.federationGuid) {
+                    fn(sourceRow.id, containerRow.id);
                 }
-                else {
-                    fn(aspectIdentifier, elementId); // provenance coming from the targetDb
+                if (currContainerRow.federationGuid === undefined
+                    || (currSourceRow.federationGuid !== undefined
+                        && currSourceRow.federationGuid >= currContainerRow.federationGuid)) {
+                    if (containerStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
+                        return;
+                    containerRow = containerStmt.getRow();
                 }
+                if (currSourceRow.federationGuid === undefined
+                    || (currContainerRow.federationGuid !== undefined
+                        && currSourceRow.federationGuid <= currContainerRow.federationGuid)) {
+                    if (sourceStmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
+                        return;
+                    sourceRow = sourceStmt.getRow();
+                }
+                // NOTE: needed test cases:
+                // - provenance container or provenance source has no fedguids
+                // - transforming split and join scenarios
+                if (!currContainerRow.federationGuid && currContainerRow.aspectIdentifier)
+                    runFnInProvDirection(currContainerRow.id, currContainerRow.aspectIdentifier);
             }
-        });
+        }));
     }
     /** Initialize the source to target Element mapping from ExternalSourceAspects in the target iModel.
      * @note This method is called from all `process*` functions and should never need to be called directly.
@@ -301,63 +429,62 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.context.remapElement(sourceElementId, targetElementId);
         });
         if (args)
-            return this.remapDeletedSourceElements(args);
+            return this.remapDeletedSourceElements();
     }
     /** When processing deleted elements in a reverse synchronization, the [[provenanceDb]] (usually a branch iModel) has already
      * deleted the [ExternalSourceAspect]($backend)s that tell us which elements in the reverse synchronization target (usually
      * a master iModel) should be deleted. We must use the changesets to get the values of those before they were deleted.
      */
-    async remapDeletedSourceElements(args) {
-        var _a;
+    async remapDeletedSourceElements() {
         // we need a connected iModel with changes to remap elements with deletions
-        if (this.sourceDb.iTwinId === undefined)
+        const notConnectedModel = this.sourceDb.iTwinId === undefined;
+        const noChanges = this._targetScopeVersion.index === this.sourceDb.changeset.index;
+        if (notConnectedModel || noChanges)
             return;
-        try {
-            const startChangesetId = (_a = args.startChangesetId) !== null && _a !== void 0 ? _a : this.sourceDb.changeset.id;
-            const endChangesetId = this.sourceDb.changeset.id;
-            const [firstChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetId, endChangesetId]
-                .map(async (id) => core_backend_1.IModelHost.hubAccess
-                .queryChangeset({
-                iModelId: this.sourceDb.iModelId,
-                changeset: { id },
-                accessToken: args.accessToken,
-            })
-                .then((changeset) => changeset.index)));
-            const changesetIds = await core_backend_1.ChangeSummaryManager.createChangeSummaries({
-                accessToken: args.accessToken,
-                iModelId: this.sourceDb.iModelId,
-                iTwinId: this.sourceDb.iTwinId,
-                range: { first: firstChangesetIndex, end: endChangesetIndex },
-            });
-            core_backend_1.ChangeSummaryManager.attachChangeCache(this.sourceDb);
-            for (const changesetId of changesetIds) {
-                this.sourceDb.withPreparedStatement(`
-          SELECT esac.Element.Id, esac.Identifier
-          FROM ecchange.change.InstanceChange ic
-          JOIN BisCore.ExternalSourceAspect.Changes(:changesetId, 'BeforeDelete') esac
-            ON ic.ChangedInstance.Id=esac.ECInstanceId
-          WHERE ic.OpCode=:opcode
-            AND ic.Summary.Id=:changesetId
-            AND esac.Scope.Id=:targetScopeElementId
-            -- not yet documented ecsql feature to check class id
-            AND ic.ChangedInstance.ClassId IS (ONLY BisCore.ExternalSourceAspect)
-          `, (stmt) => {
-                    stmt.bindInteger("opcode", core_common_1.ChangeOpCode.Delete);
-                    stmt.bindInteger("changesetId", changesetId);
-                    stmt.bindInteger("targetScopeElementId", this.targetScopeElementId);
-                    while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
-                        const targetId = stmt.getValue(0).getId();
-                        const sourceId = stmt.getValue(1).getString(); // BisCore.ExternalSourceAspect.Identifier stores a hex Id64String
-                        // TODO: maybe delete and don't just remap
-                        this.context.remapElement(targetId, sourceId);
-                    }
-                });
+        nodeAssert(this._changeSummaryIds, "change summaries should be initialized before we get here");
+        nodeAssert(this._changeSummaryIds.length > 0, "change summaries should have at least one");
+        const deletedElemSql = `
+      SELECT ic.ChangedInstance.Id, ${this._coalesceChangeSummaryJoinedValue((_, i) => `ec${i}.FederationGuid`)}
+      FROM ecchange.change.InstanceChange ic
+      -- ask affan about whether this is worth it...
+      ${this._changeSummaryIds.map((id, i) => `
+          LEFT JOIN bis.Element.Changes(${id}, 'BeforeDelete') ec${i}
+            ON ic.ChangedInstance.Id=ec${i}.ECInstanceId
+        `).join('')}
+      WHERE ic.OpCode=:opDelete
+        AND InVirtualSet(:changeSummaryIds, ic.Summary.Id)
+        -- not yet documented ecsql feature to check class id
+        AND ic.ChangedInstance.ClassId IS (BisCore.Element)
+    `;
+        // must also support old ESA provenance if no fedguids
+        this.sourceDb.withStatement(deletedElemSql, (stmt) => {
+            stmt.bindInteger("opDelete", core_common_1.ChangeOpCode.Delete);
+            stmt.bindIdSet("changeSummaryIds", this._changeSummaryIds);
+            // instead of targetScopeElementId, we only operate on elements
+            // that had colliding fed guids with the source...
+            // currently that is enforced by us checking that the deleted element fedguid is in both
+            // before remapping
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
+                const sourceId = stmt.getValue(0).getId();
+                // FIXME: if I could attach the second db, will probably be much faster to get target id
+                const sourceFedGuid = stmt.getValue(1).getGuid();
+                const targetId = this.queryElemIdByFedGuid(this.targetDb, sourceFedGuid);
+                const deletionNotInTarget = !targetId;
+                if (deletionNotInTarget)
+                    return;
+                // TODO: maybe delete and don't just remap
+                this.context.remapElement(sourceId, targetId);
             }
-        }
-        finally {
-            if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
-                core_backend_1.ChangeSummaryManager.detachChangeCache(this.sourceDb);
-        }
+        });
+    }
+    queryElemIdByFedGuid(db, fedGuid) {
+        return db.withPreparedStatement("SELECT ECInstanceId FROM Bis.Element WHERE FederationGuid=?", (stmt) => {
+            stmt.bindGuid(1, fedGuid);
+            if (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW)
+                return stmt.getValue(0).getId();
+            else
+                return undefined;
+        });
     }
     /** Returns `true` if *brute force* delete detections should be run.
      * @note Not relevant for processChanges when change history is known.
@@ -375,6 +502,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
     async detectElementDeletes() {
+        // FIXME: this is no longer possible to do without change data loading, but I don't think
+        // anyone uses this obscure feature, maybe we can remove it?
+        // NOTE: can implement this by checking for federation guids in the target that aren't
         if (this._options.isReverseSynchronization) {
             throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
         }
@@ -402,35 +532,95 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @note This can be called more than once for an element in arbitrary order, so it should not have side-effects.
      */
     onTransformElement(sourceElement) {
-        var _a, _b;
         core_bentley_1.Logger.logTrace(loggerCategory, `onTransformElement(${sourceElement.id}) "${sourceElement.getDisplayLabel()}"`);
         const targetElementProps = this.context.cloneElement(sourceElement, { binaryGeometry: this._options.cloneUsingBinaryGeometry });
         if (sourceElement instanceof core_backend_1.Subject) {
-            if ((_b = (_a = targetElementProps.jsonProperties) === null || _a === void 0 ? void 0 : _a.Subject) === null || _b === void 0 ? void 0 : _b.Job) {
+            if (targetElementProps.jsonProperties?.Subject?.Job) {
                 // don't propagate source channels into target (legacy bridge case)
                 targetElementProps.jsonProperties.Subject.Job = undefined;
             }
         }
         return targetElementProps;
     }
+    // handle sqlite coalesce requiring 2 arguments
+    _coalesceChangeSummaryJoinedValue(f) {
+        nodeAssert(this._changeSummaryIds?.length && this._changeSummaryIds.length > 0, "should have changeset data by now");
+        const valueList = this._changeSummaryIds.map(f).join(',');
+        return this._changeSummaryIds.length > 1 ? `coalesce(${valueList})` : valueList;
+    }
+    ;
+    // FIXME: this is a PoC, don't load this all into memory
+    _cacheSourceChanges() {
+        nodeAssert(this._changeSummaryIds && this._changeSummaryIds.length > 0, "should have changeset data by now");
+        this._hasElementChangedCache = new Set();
+        this._deletedSourceRelationshipData = new Map();
+        // somewhat complicated query because doing two things at once...
+        // (not to mention the multijoin coalescing hack)
+        // FIXME: perhaps the coalescing indicates that part should be done manually, not in the query?
+        const query = `
+      SELECT
+        ic.ChangedInstance.Id AS InstId,
+        -- NOTE: parse error even with () without iif
+        iif(ic.ChangedInstance.ClassId IS (BisCore.Element), TRUE, FALSE) AS IsElemNotDeletedRel,
+        coalesce(${
+        // HACK: adding "NONE" for empty result seems to prevent a bug where getValue(3) stops working after the NULL columns
+        this._changeSummaryIds.map((_, i) => `se${i}.FederationGuid, sec${i}.FederationGuid`).concat("'NONE'").join(',')}) AS SourceFedGuid,
+        coalesce(${this._changeSummaryIds.map((_, i) => `te${i}.FederationGuid, tec${i}.FederationGuid`).concat("'NONE'").join(',')}) AS TargetFedGuid,
+        ic.ChangedInstance.ClassId AS ClassId
+      FROM ecchange.change.InstanceChange ic
+      JOIN iModelChange.Changeset imc ON ic.Summary.Id=imc.Summary.Id
+      -- ask affan about whether this is worth it... maybe the ""
+      ${this._changeSummaryIds.map((id, i) => `
+          LEFT JOIN bis.ElementRefersToElements.Changes(${id}, 'BeforeDelete') ertec${i}
+            -- NOTE: see how the AND affects performance, it could be dropped
+            ON ic.ChangedInstance.Id=ertec${i}.ECInstanceId
+              AND NOT ic.ChangedInstance.ClassId IS (BisCore.Element)
+          -- FIXME: test a deletion of both an element and a relationship at the same time
+          LEFT JOIN bis.Element se${i}
+            ON se${i}.ECInstanceId=ertec${i}.SourceECInstanceId
+          LEFT JOIN bis.Element te${i}
+            ON te${i}.ECInstanceId=ertec${i}.TargetECInstanceId
+          LEFT JOIN bis.Element.Changes(${id}, 'BeforeDelete') sec${i}
+            ON sec${i}.ECInstanceId=ertec${i}.SourceECInstanceId
+          LEFT JOIN bis.Element.Changes(${id}, 'BeforeDelete') tec${i}
+            ON tec${i}.ECInstanceId=ertec${i}.TargetECInstanceId
+        `).join('')}
+      -- ignore deleted elems, we take care of those separately
+      WHERE ((ic.ChangedInstance.ClassId IS (BisCore.Element) AND ic.OpCode<>:opUpdate)
+          OR (ic.ChangedInstance.ClassId IS (BisCore.ElementRefersToElements) AND ic.OpCode=:opDelete))
+    `;
+        this.sourceDb.withPreparedStatement(query, (stmt) => {
+            stmt.bindInteger("opDelete", core_common_1.ChangeOpCode.Delete);
+            stmt.bindInteger("opUpdate", core_common_1.ChangeOpCode.Update);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
+                // REPORT: stmt.getValue(>3) seems to be bugged but the values survive .getRow so using that for now
+                const instId = stmt.getValue(0).getId();
+                const isElemNotDeletedRel = stmt.getValue(1).getBoolean();
+                if (isElemNotDeletedRel)
+                    this._hasElementChangedCache.add(instId);
+                else {
+                    const sourceFedGuid = stmt.getValue(2).getGuid();
+                    const targetFedGuid = stmt.getValue(3).getGuid();
+                    const classFullName = stmt.getValue(4).getClassNameForClassId();
+                    this._deletedSourceRelationshipData.set(instId, { classFullName, sourceFedGuid, targetFedGuid });
+                }
+            }
+        });
+    }
     /** Returns true if a change within sourceElement is detected.
      * @param sourceElement The Element from the source iModel
      * @param targetElementId The Element from the target iModel to compare against.
      * @note A subclass can override this method to provide custom change detection behavior.
      */
-    hasElementChanged(sourceElement, targetElementId) {
-        const sourceAspects = this.targetDb.elements.getAspects(targetElementId, core_backend_1.ExternalSourceAspect.classFullName);
-        for (const sourceAspect of sourceAspects) {
-            if (sourceAspect.scope === undefined) // if the scope was lost, we can't correlate so assume it changed
-                return true;
-            if (sourceAspect.identifier === sourceElement.id &&
-                sourceAspect.scope.id === this.targetScopeElementId &&
-                sourceAspect.kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
-                const lastModifiedTime = sourceElement.iModel.elements.queryLastModifiedTime(sourceElement.id);
-                return lastModifiedTime !== sourceAspect.version;
-            }
-        }
-        return true;
+    hasElementChanged(sourceElement, _targetElementId) {
+        if (this._changeDataState === "no-changes")
+            return false;
+        if (this._changeDataState === "unconnected")
+            return true;
+        nodeAssert(this._changeDataState === "has-changes", "change data should be initialized by now");
+        if (this._hasElementChangedCache === undefined)
+            this._cacheSourceChanges();
+        return this._hasElementChangedCache.has(sourceElement.id);
     }
     static transformCallbackFor(transformer, entity) {
         if (entity instanceof core_backend_1.Element)
@@ -587,7 +777,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * This override calls [[onTransformElement]] and then [IModelImporter.importElement]($transformer) to update the target iModel.
      */
     onExportElement(sourceElement) {
-        var _a;
         let targetElementId;
         let targetElementProps;
         if (this._options.preserveElementIdsForFiltering) {
@@ -606,7 +795,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         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 is trims
             // whitespace from the value, and there are iModels out there with untrimmed whitespace that we ought not to trim
-            targetElementProps.code.value = (_a = targetElementProps.code.value) !== null && _a !== void 0 ? _a : "";
+            targetElementProps.code.value = targetElementProps.code.value ?? "";
             targetElementId = this.targetDb.elements.queryElementIdByCode(targetElementProps.code);
             if (undefined !== targetElementId) {
                 const targetElement = this.targetDb.elements.getElement(targetElementId);
@@ -619,12 +808,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 }
             }
         }
-        if (undefined !== targetElementId && core_bentley_1.Id64.isValidId64(targetElementId)) {
-            // compare LastMod of sourceElement to ExternalSourceAspect of targetElement to see there are changes to import
-            if (!this.hasElementChanged(sourceElement, targetElementId)) {
-                return;
-            }
-        }
+        if (targetElementId !== undefined
+            && core_bentley_1.Id64.isValid(targetElementId)
+            && !this.hasElementChanged(sourceElement, targetElementId))
+            return;
         this.collectUnmappedReferences(sourceElement);
         // TODO: untangle targetElementId state...
         if (targetElementId === core_bentley_1.Id64.invalid)
@@ -636,17 +823,29 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.remapElement(sourceElement.id, targetElementProps.id); // targetElementProps.id assigned by importElement
         // now that we've mapped this elem we can fix unmapped references to it
         this.resolvePendingReferences(sourceElement);
+        // 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)
+        // when splitting/joining elements
+        // physical consolidation is an example of a 'joining' transform
+        // FIXME: document this externally!
+        // verify at finalization time that we don't lose provenance on new elements
+        // make public and improve `initElementProvenance` API for usage by consolidators
         if (!this._options.noProvenance) {
-            const aspectProps = this.initElementProvenance(sourceElement.id, targetElementProps.id);
-            let aspectId = this.queryExternalSourceAspectId(aspectProps);
-            if (aspectId === undefined) {
-                aspectId = this.provenanceDb.elements.insertAspect(aspectProps);
-            }
-            else {
-                this.provenanceDb.elements.updateAspect(aspectProps);
+            let provenance = sourceElement.federationGuid;
+            if (!provenance) {
+                const aspectProps = this.initElementProvenance(sourceElement.id, targetElementProps.id);
+                let [aspectId] = this.queryScopeExternalSource(aspectProps);
+                if (aspectId === undefined) {
+                    aspectId = this.provenanceDb.elements.insertAspect(aspectProps);
+                }
+                else {
+                    this.provenanceDb.elements.updateAspect(aspectProps);
+                }
+                aspectProps.id = aspectId;
+                provenance = aspectProps;
             }
-            aspectProps.id = aspectId;
-            this.markLastProvenance(aspectProps, { isRelationship: false });
+            this.markLastProvenance(provenance, { isRelationship: false });
         }
     }
     resolvePendingReferences(entity) {
@@ -760,7 +959,20 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @deprecated in 3.x. This method is no longer necessary since the transformer no longer needs to defer elements
      */
     async processDeferredElements(_numRetries = 3) { }
+    /** called at the end ([[finalizeTransformation]]) of a transformation,
+     * updates the target scope element to say that transformation up through the
+     * source's changeset has been performed.
+     */
+    _updateTargetScopeVersion() {
+        nodeAssert(this._targetScopeProvenanceProps);
+        if (this._changeDataState === "has-changes") {
+            this._targetScopeProvenanceProps.version = `${this.provenanceSourceDb.changeset.id};${this.provenanceSourceDb.changeset.index}`;
+            this.provenanceDb.elements.updateAspect(this._targetScopeProvenanceProps);
+        }
+    }
+    // FIXME: is this necessary when manually using lowlevel transform APIs?
     finalizeTransformation() {
+        this._updateTargetScopeVersion();
         if (this._partiallyCommittedEntities.size > 0) {
             core_bentley_1.Logger.logWarning(loggerCategory, [
                 "The following elements were never fully resolved:",
@@ -772,6 +984,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 partiallyCommittedElem.forceComplete();
             }
         }
+        // FIXME: make processAll have a try {} finally {} that cleans this up
+        if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
+            core_backend_1.ChangeSummaryManager.detachChangeCache(this.sourceDb);
     }
     /** Imports all relationships that subclass from the specified base class.
      * @param baseRelClassFullName The specified base relationship class.
@@ -789,40 +1004,84 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * This override calls [[onTransformRelationship]] and then [IModelImporter.importRelationship]($transformer) to update the target iModel.
      */
     onExportRelationship(sourceRelationship) {
+        const sourceFedGuid = queryElemFedGuid(this.sourceDb, sourceRelationship.sourceId);
+        const targetFedGuid = queryElemFedGuid(this.sourceDb, sourceRelationship.targetId);
         const targetRelationshipProps = this.onTransformRelationship(sourceRelationship);
         const targetRelationshipInstanceId = this.importer.importRelationship(targetRelationshipProps);
-        if (!this._options.noProvenance && core_bentley_1.Id64.isValidId64(targetRelationshipInstanceId)) {
-            const aspectProps = this.initRelationshipProvenance(sourceRelationship, targetRelationshipInstanceId);
-            if (undefined === aspectProps.id) {
-                aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
+        if (!this._options.noProvenance && core_bentley_1.Id64.isValid(targetRelationshipInstanceId)) {
+            let provenance = sourceFedGuid && targetFedGuid && `${sourceFedGuid}/${targetFedGuid}`;
+            if (!provenance) {
+                const aspectProps = this.initRelationshipProvenance(sourceRelationship, targetRelationshipInstanceId);
+                if (undefined === aspectProps.id) {
+                    aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
+                }
+                (0, core_bentley_1.assert)(aspectProps.id !== undefined);
+                provenance = aspectProps;
             }
-            (0, core_bentley_1.assert)(aspectProps.id !== undefined);
-            this.markLastProvenance(aspectProps, { isRelationship: true });
+            this.markLastProvenance(provenance, { isRelationship: true });
         }
     }
+    // FIXME: need to check if the element class was remapped and use that id instead
+    // is this really the best way to get class id? shouldn't we cache it somewhere?
+    // NOTE: maybe if we lower remapElementClass into here, we can use that
+    _getRelClassId(db, classFullName) {
+        // is it better to use un-cached `SELECT (ONLY ${classFullName})`?
+        return db.withPreparedStatement(`
+      SELECT c.ECInstanceId
+      FROM ECDbMeta.ECClassDef c
+      JOIN ECDbMeta.ECSchemaDef s ON c.Schema.Id=s.ECInstanceId
+      WHERE s.Name=? AND c.Name=?
+    `, (stmt) => {
+            const [schemaName, className] = classFullName.split(".");
+            stmt.bindString(1, schemaName);
+            stmt.bindString(2, className);
+            if (stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW)
+                return stmt.getValue(0).getId();
+            (0, core_bentley_1.assert)(false, "relationship was not found");
+        });
+    }
     /** 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) {
-        const sql = `SELECT ECInstanceId,JsonProperties FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect` +
-            ` WHERE aspect.Scope.Id=:scopeId AND aspect.Kind=:kind AND aspect.Identifier=:identifier LIMIT 1`;
+        nodeAssert(this._deletedSourceRelationshipData, "should be defined at initialization by now");
+        const deletedRelData = this._deletedSourceRelationshipData.get(sourceRelInstanceId);
+        if (!deletedRelData) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "tried to delete a relationship that wasn't in change data");
+            return;
+        }
+        const targetRelClassId = this._getRelClassId(this.targetDb, deletedRelData.classFullName);
+        // NOTE: if no remapping, could store the sourceRel class name earlier and reuse it instead of add to query
+        // TODO: name this query
+        const sql = `
+      SELECT SourceECInstanceId, TargetECInstanceId, erte.ECClassId
+      FROM BisCore.ElementRefersToElements erte
+      JOIN BisCore.Element se ON se.ECInstanceId=SourceECInstanceId
+      JOIN BisCore.Element te ON te.ECInstanceId=TargetECInstanceId
+      WHERE se.FederationGuid=:sourceFedGuid
+        AND te.FederationGuid=:targetFedGuid
+        AND erte.ECClassId=:relClassId
+    `;
         this.targetDb.withPreparedStatement(sql, (statement) => {
-            statement.bindId("scopeId", this.targetScopeElementId);
-            statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Relationship);
-            statement.bindString("identifier", sourceRelInstanceId);
+            statement.bindGuid("sourceFedGuid", deletedRelData.sourceFedGuid);
+            statement.bindGuid("targetFedGuid", deletedRelData.targetFedGuid);
+            statement.bindId("relClassId", targetRelClassId);
             if (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
-                const json = JSON.parse(statement.getValue(1).getString());
-                if (undefined !== json.targetRelInstanceId) {
-                    const targetRelationship = this.targetDb.relationships.tryGetInstance(core_backend_1.ElementRefersToElements.classFullName, json.targetRelInstanceId);
-                    if (targetRelationship) {
-                        this.importer.deleteRelationship(targetRelationship.toJSON());
-                    }
-                    this.targetDb.elements.deleteAspect(statement.getValue(0).getId());
+                const sourceId = statement.getValue(0).getId();
+                const targetId = statement.getValue(1).getId();
+                const targetRelClassFullName = statement.getValue(2).getClassNameForClassId();
+                // FIXME: make importer.deleteRelationship not need full props
+                const targetRelationship = this.targetDb.relationships.tryGetInstance(targetRelClassFullName, { sourceId, targetId });
+                if (targetRelationship) {
+                    this.importer.deleteRelationship(targetRelationship.toJSON());
                 }
+                // FIXME: restore in ESA compatible method
+                //this.targetDb.elements.deleteAspect(statement.getValue(0).getId());
             }
         });
     }
     /** Detect Relationship deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against relationships in the source iModel.
+     * @deprecated
      * @see processChanges
      * @note This method is called from [[processAll]] and is not needed by [[processChanges]], 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.
@@ -832,7 +1091,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
         }
         const aspectDeleteIds = [];
-        const sql = `SELECT ECInstanceId,Identifier,JsonProperties FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect WHERE aspect.Scope.Id=:scopeId AND aspect.Kind=:kind`;
+        const sql = `
+      SELECT ECInstanceId, Identifier, JsonProperties
+      FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect
+      WHERE aspect.Scope.Id=:scopeId
+        AND aspect.Kind=:kind
+    `;
         await this.targetDb.withPreparedStatement(sql, async (statement) => {
             statement.bindId("scopeId", this.targetScopeElementId);
             statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Relationship);
@@ -860,6 +1124,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetRelationshipProps = sourceRelationship.toJSON();
         targetRelationshipProps.sourceId = this.context.findTargetElementId(sourceRelationship.sourceId);
         targetRelationshipProps.targetId = this.context.findTargetElementId(sourceRelationship.targetId);
+        // TODO: move to cloneRelationship in IModelCloneContext
         sourceRelationship.forEachProperty((propertyName, propertyMetaData) => {
             if ((core_common_1.PrimitiveTypeCode.Long === propertyMetaData.primitiveType) && ("Id" === propertyMetaData.extendedType)) {
                 targetRelationshipProps[propertyName] = this.context.findTargetElementId(sourceRelationship.asAny[propertyName]);
@@ -889,8 +1154,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         sourceAspects.forEach((a) => this.collectUnmappedReferences(a));
         // const targetAspectsToImport = targetAspectPropsArray.filter((targetAspect, i) => hasEntityChanged(sourceAspects[i], targetAspect));
         const targetIds = this.importer.importElementMultiAspects(targetAspectPropsArray, (a) => {
-            var _a;
-            const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect && ((_a = a.scope) === null || _a === void 0 ? void 0 : _a.id) === this.targetScopeElementId;
+            const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect && a.scope?.id === this.targetScopeElementId;
             return !this._options.includeSourceProvenance || !isExternalSourceAspectFromTransformer;
         });
         for (let i = 0; i < targetIds.length; ++i) {
@@ -958,6 +1222,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * It is more efficient to process *data* changes after the schema changes have been saved.
      */
     async processSchemas() {
+        this.events.emit(TransformerEvent.beginProcessSchemas);
         // we do not need to initialize for this since no entities are exported
         try {
             core_backend_1.IModelJsFs.mkdirSync(this._schemaExportDir);
@@ -975,6 +1240,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         finally {
             core_backend_1.IModelJsFs.removeSync(this._schemaExportDir);
             this._longNamedSchemasMap.clear();
+            this.events.emit(TransformerEvent.endProcessSchemas);
         }
     }
     /** Cause all fonts to be exported from the source iModel and imported into the target iModel.
@@ -1031,17 +1297,53 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._initialized)
             return;
         await this.context.initialize();
+        await this._tryInitChangesetData(args);
         // eslint-disable-next-line deprecation/deprecation
         await this.initFromExternalSourceAspects(args);
         this._initialized = true;
     }
+    async _tryInitChangesetData(args) {
+        if (!args || this.sourceDb.iTwinId === undefined) {
+            this._changeDataState = "unconnected";
+            return;
+        }
+        const noChanges = this._targetScopeVersion.index === this.sourceDb.changeset.index;
+        if (noChanges) {
+            this._changeDataState = "no-changes";
+            this._changeSummaryIds = [];
+            return;
+        }
+        // NOTE: that we do NOT download the changesummary for the last transformed version, we want
+        // to ignore those already processed changes
+        const startChangesetIndexOrId = args?.startChangesetId ?? this._targetScopeVersion.index + 1;
+        const endChangesetId = this.sourceDb.changeset.id;
+        const [startChangesetIndex, endChangesetIndex] = await Promise.all(([startChangesetIndexOrId, endChangesetId])
+            .map(async (indexOrId) => typeof indexOrId === "number"
+            ? indexOrId
+            : core_backend_1.IModelHost.hubAccess
+                .queryChangeset({
+                iModelId: this.sourceDb.iModelId,
+                changeset: { id: indexOrId },
+                accessToken: args.accessToken,
+            })
+                .then((changeset) => changeset.index)));
+        // FIXME: do we need the startChangesetId?
+        this._changeSummaryIds = await core_backend_1.ChangeSummaryManager.createChangeSummaries({
+            accessToken: args.accessToken,
+            iModelId: this.sourceDb.iModelId,
+            iTwinId: this.sourceDb.iTwinId,
+            range: { first: startChangesetIndex, end: endChangesetIndex },
+        });
+        core_backend_1.ChangeSummaryManager.attachChangeCache(this.sourceDb);
+        this._changeDataState = "has-changes";
+    }
     /** Export everything from the source iModel and import the transformed entities into the target iModel.
    * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
    */
     async processAll() {
-        core_bentley_1.Logger.logTrace(loggerCategory, "processAll()");
+        this.events.emit(TransformerEvent.beginProcessAll);
         this.logSettings();
-        this.validateScopeProvenance();
+        this.initScopeProvenance();
         await this.initialize();
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
@@ -1059,15 +1361,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
         this.finalizeTransformation();
+        this.events.emit(TransformerEvent.endProcessAll);
     }
     markLastProvenance(sourceAspect, { isRelationship = false }) {
-        var _a;
-        this._lastProvenanceEntityInfo = {
-            entityId: sourceAspect.element.id,
-            aspectId: sourceAspect.id,
-            aspectVersion: (_a = sourceAspect.version) !== null && _a !== void 0 ? _a : "",
-            aspectKind: isRelationship ? core_backend_1.ExternalSourceAspect.Kind.Relationship : core_backend_1.ExternalSourceAspect.Kind.Element,
-        };
+        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,
+                };
     }
     /**
      * Load the state of the active transformation from an open SQLiteDb
@@ -1079,17 +1384,35 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const lastProvenanceEntityInfo = db.withSqliteStatement(`SELECT entityId, aspectId, aspectVersion, aspectKind FROM ${IModelTransformer.lastProvenanceEntityInfoTable}`, (stmt) => {
             if (core_bentley_1.DbResult.BE_SQLITE_ROW !== stmt.step())
                 throw Error("expected row when getting lastProvenanceEntityId from target state table");
-            return {
-                entityId: stmt.getValueString(0),
-                aspectId: stmt.getValueString(1),
-                aspectVersion: stmt.getValueString(2),
-                aspectKind: stmt.getValueString(3),
-            };
+            const entityId = stmt.getValueString(0);
+            const isGuidOrGuidPair = entityId.includes('-');
+            return isGuidOrGuidPair
+                ? entityId
+                : {
+                    entityId,
+                    aspectId: stmt.getValueString(1),
+                    aspectVersion: stmt.getValueString(2),
+                    aspectKind: stmt.getValueString(3),
+                };
         });
-        const targetHasCorrectLastProvenance = 
-        // ignore provenance check if it's null since we can't bind those ids
-        !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.aspectId) ||
+        /*
+        // TODO: maybe save transformer state resumption state based on target changset and require calls
+        // to saveChanges
+        if () {
+          const [sourceFedGuid, targetFedGuid, relClassFullName] = lastProvenanceEntityInfo.split("/");
+          const isRelProvenance = targetFedGuid !== undefined;
+          const instanceId = isRelProvenance
+            ? this.targetDb.elements.getElement({federationGuid: sourceFedGuid})
+            : "";
+          //const classId =
+          if (isRelProvenance) {
+          }
+        }
+        */
+        const targetHasCorrectLastProvenance = typeof lastProvenanceEntityInfo === "string" ||
+            // ignore provenance check if it's null since we can't bind those ids
             !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.entityId) ||
+            !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.aspectId) ||
             this.provenanceDb.withPreparedStatement(`
         SELECT Version FROM ${core_backend_1.ExternalSourceAspect.classFullName}
         WHERE Scope.Id=:scopeId
@@ -1186,8 +1509,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             throw Error("Failed to create the js state table in the state database");
         if (core_bentley_1.DbResult.BE_SQLITE_DONE !== db.executeSQL(`
       CREATE TABLE ${IModelTransformer.lastProvenanceEntityInfoTable} (
-        -- because we cannot bind the invalid id which we use for our null state, we actually store the id as a hex string
+        -- either the invalid id for null provenance state, federation guid (or pair for rels) of the entity, or a hex element id
         entityId TEXT,
+        -- the following are only valid if the above entityId is a hex id representation
         aspectId TEXT,
         aspectVersion TEXT,
         aspectKind TEXT
@@ -1201,10 +1525,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 throw Error("Failed to insert options into the state database");
         });
         db.withSqliteStatement(`INSERT INTO ${IModelTransformer.lastProvenanceEntityInfoTable} (entityId, aspectId, aspectVersion, aspectKind) VALUES (?,?,?,?)`, (stmt) => {
-            stmt.bindString(1, this._lastProvenanceEntityInfo.entityId);
-            stmt.bindString(2, this._lastProvenanceEntityInfo.aspectId);
-            stmt.bindString(3, this._lastProvenanceEntityInfo.aspectVersion);
-            stmt.bindString(4, this._lastProvenanceEntityInfo.aspectKind);
+            const lastProvenanceEntityInfo = this._lastProvenanceEntityInfo;
+            stmt.bindString(1, lastProvenanceEntityInfo?.entityId ?? this._lastProvenanceEntityInfo);
+            stmt.bindString(2, lastProvenanceEntityInfo?.aspectId ?? "");
+            stmt.bindString(3, lastProvenanceEntityInfo?.aspectVersion ?? "");
+            stmt.bindString(4, lastProvenanceEntityInfo?.aspectKind ?? "");
             if (core_bentley_1.DbResult.BE_SQLITE_DONE !== stmt.step())
                 throw Error("Failed to insert options into the state database");
         });
@@ -1233,16 +1558,16 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
     }
     /** 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).
-   * @param accessToken A valid access token string
-   * @param startChangesetId Include changes from this changeset up through and including the current changeset.
-   * If this parameter is not provided, then just the current changeset will be exported.
-   * @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.
-   */
+     * Inserts, updates, and deletes are determined by inspecting the changeset(s).
+     * @param accessToken A valid access token string
+     * @param startChangesetId Include changes from this changeset up through and including the current changeset.
+     * If this parameter is not provided, then just the current changeset will be exported.
+     * @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(accessToken, startChangesetId) {
-        core_bentley_1.Logger.logTrace(loggerCategory, "processChanges()");
+        this.events.emit(TransformerEvent.beginProcessChanges, startChangesetId);
         this.logSettings();
-        this.validateScopeProvenance();
+        this.initScopeProvenance();
         await this.initialize({ accessToken, startChangesetId });
         await this.exporter.exportChanges(accessToken, startChangesetId);
         await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
@@ -1250,13 +1575,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
         this.finalizeTransformation();
+        this.events.emit(TransformerEvent.endProcessChanges);
     }
 }
-exports.IModelTransformer = IModelTransformer;
 /** @internal the name of the table where javascript state of the transformer is serialized in transformer state dumps */
 IModelTransformer.jsStateTable = "TransformerJsState";
 /** @internal the name of the table where the target state heuristics is serialized in transformer state dumps */
 IModelTransformer.lastProvenanceEntityInfoTable = "LastProvenanceEntityInfo";
+exports.IModelTransformer = IModelTransformer;
 /** IModelTransformer that clones the contents of a template model.
  * @beta
  */
@@ -1354,4 +1680,17 @@ class TemplateModelCloner extends IModelTransformer {
     }
 }
 exports.TemplateModelCloner = TemplateModelCloner;
+function queryElemFedGuid(db, elemId) {
+    return db.withPreparedStatement(`
+    SELECT FederationGuid
+    FROM bis.Element
+    WHERE ECInstanceId=?
+  `, (stmt) => {
+        stmt.bindId(1, elemId);
+        (0, core_bentley_1.assert)(stmt.step() === core_bentley_1.DbResult.BE_SQLITE_ROW);
+        const result = stmt.getValue(0).getGuid();
+        (0, core_bentley_1.assert)(stmt.step() === core_bentley_1.DbResult.BE_SQLITE_DONE);
+        return result;
+    });
+}
 //# sourceMappingURL=IModelTransformer.js.map