@itwin/imodel-transformer 2.0.0-dev.8 → 2.0.0-experimental.0

package/lib/cjs/ProvenanceManager.js

@@ -0,0 +1,771 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvenanceManager = void 0;
+exports.queryTargetScopeElementIds = queryTargetScopeElementIds;
+exports.isTransformerProvenanceAspect = isTransformerProvenanceAspect;
+exports.sourceProvenanceMatchFilter = sourceProvenanceMatchFilter;
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_backend_1 = require("@itwin/core-backend");
+const core_common_1 = require("@itwin/core-common");
+const ElementAspectCleanup_1 = require("./ElementAspectCleanup");
+const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
+const IModelTransformerError_1 = require("./IModelTransformerError");
+const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelTransformer;
+/**
+ * Manages provenance scope aspects and synchronization versioning.
+ * Encapsulates all ESA scope management, sync version tracking, and
+ * provenance DB direction logic extracted from IModelTransformer.
+ * @internal
+ */
+class ProvenanceManager {
+    _context;
+    _targetScopeElementId;
+    _transformerOptions;
+    _syncTypeResolver;
+    _startingChangesetIndices;
+    /** NOTE: the json properties must be converted to string before insertion */
+    _targetScopeProvenanceProps = undefined;
+    _cachedSynchronizationVersion = undefined;
+    _targetClassNameToClassIdCache = new Map();
+    _targetEditTxn;
+    _sourceEditTxn;
+    constructor(targetScopeElementId, transformerOptions, context, syncTypeResolver, targetEditTxn, sourceEditTxn) {
+        this._targetScopeElementId = targetScopeElementId;
+        this._transformerOptions = transformerOptions;
+        this._context = context;
+        this._syncTypeResolver = syncTypeResolver;
+        this._targetEditTxn = targetEditTxn;
+        this._sourceEditTxn = sourceEditTxn;
+        const sourceDb = this._context.sourceDb;
+        const targetDb = this._context.targetDb;
+        if (sourceDb.isBriefcase && targetDb.isBriefcase) {
+            if (sourceDb.changeset.index === undefined ||
+                targetDb.changeset.index === undefined)
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ChangesetIndexUnavailable,
+                    },
+                    message: "database has no changeset index",
+                });
+            this._startingChangesetIndices = {
+                target: targetDb.changeset.index,
+                source: sourceDb.changeset.index,
+            };
+        }
+    }
+    async _isReverseSynchronization() {
+        return (await this._syncTypeResolver.getSyncType()) === "reverse";
+    }
+    async _queryTargetRelId(sourceRelInfo) {
+        const targetRelInfo = {
+            sourceId: this._context.findTargetElementId(sourceRelInfo.sourceId),
+            targetId: this._context.findTargetElementId(sourceRelInfo.targetId),
+        };
+        if (targetRelInfo.sourceId === undefined ||
+            targetRelInfo.targetId === undefined)
+            return undefined;
+        const sql = `
+      select ecinstanceid
+      from bis.elementreferstoelements
+      where sourceecinstanceid=?
+        and targetecinstanceid=?
+        and ecclassid=?
+    `;
+        const params = new core_common_1.QueryBinder();
+        params.bindId(1, targetRelInfo.sourceId);
+        params.bindId(2, targetRelInfo.targetId);
+        params.bindId(3, await this._targetClassNameToClassId(sourceRelInfo.classFullName));
+        const result = this._context.targetDb.createQueryReader(sql, params, {
+            usePrimaryConn: true,
+        });
+        if (await result.step())
+            return result.current.id;
+        else
+            return undefined;
+    }
+    async _targetClassNameToClassId(classFullName) {
+        let classId = this._targetClassNameToClassIdCache.get(classFullName);
+        if (classId === undefined) {
+            classId = await this._getRelClassId(this._context.targetDb, classFullName);
+            this._targetClassNameToClassIdCache.set(classFullName, classId);
+        }
+        return classId;
+    }
+    async _getRelClassId(db, classFullName) {
+        const sql = `
+      SELECT c.ECInstanceId
+      FROM ECDbMeta.ECClassDef c
+      JOIN ECDbMeta.ECSchemaDef s ON c.Schema.Id=s.ECInstanceId
+      WHERE s.Name=? AND c.Name=?
+    `;
+        const [schemaName, className] = classFullName.indexOf(".") !== -1
+            ? classFullName.split(".")
+            : classFullName.split(":");
+        const params = new core_common_1.QueryBinder();
+        params.bindString(1, schemaName);
+        params.bindString(2, className);
+        const result = db.createQueryReader(sql, params, { usePrimaryConn: true });
+        if (await result.step())
+            return result.current.id;
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.RelationshipClassNotFound,
+            },
+            message: `Could not find class ${classFullName} in the db`,
+        });
+    }
+    // ── Static provenance metadata ──────────────────────────────────────────
+    /** 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];
+    }
+    // ── Static provenance queries ──────────────────────────────────────────
+    /**
+     * 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 async forEachTrackedElement(args) {
+        if (args.provenanceDb === args.provenanceSourceDb)
+            return;
+        if (!args.provenanceDb.containsClass(core_backend_1.ExternalSourceAspect.classFullName)) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ProvenanceSchemaUnsupported,
+                },
+                message: "The BisCore schema version of the target database is too old",
+            });
+        }
+        const sourceDb = args.isReverseSynchronization
+            ? args.provenanceDb
+            : args.provenanceSourceDb;
+        const targetDb = args.isReverseSynchronization
+            ? args.provenanceSourceDb
+            : args.provenanceDb;
+        // query for provenanceDb
+        const elementIdByFedGuidQuery = `
+      SELECT e.ECInstanceId, FederationGuid
+      FROM bis.Element e
+      ${args.skipPropagateChangesToRootElements
+            ? "WHERE e.ECInstanceId NOT IN (0x1, 0xe, 0x10) -- special static elements"
+            : ""}
+      ORDER BY FederationGuid
+    `;
+        // iterate through sorted list of fed guids from both dbs to get the intersection
+        // NOTE: if we exposed the native attach database support,
+        // we could get the intersection of fed guids in one query, not sure if it would be faster
+        // OR we could do a raw sqlite query...
+        const sourceReader = sourceDb.createQueryReader(elementIdByFedGuidQuery, undefined, { usePrimaryConn: true });
+        const targetReader = targetDb.createQueryReader(elementIdByFedGuidQuery, undefined, { usePrimaryConn: true });
+        let hasSourceRow = await sourceReader.step();
+        let hasTargetRow = await targetReader.step();
+        while (hasSourceRow && hasTargetRow) {
+            const sourceFedGuid = sourceReader.current.federationGuid;
+            const targetFedGuid = targetReader.current.federationGuid;
+            if (sourceFedGuid !== undefined &&
+                targetFedGuid !== undefined &&
+                sourceFedGuid === targetFedGuid) {
+                // data flow direction is always sourceDb -> targetDb and it does not depend on where the explicit element provenance is stored
+                args.fn(sourceReader.current.id, targetReader.current.id);
+            }
+            if (targetFedGuid === undefined ||
+                (sourceFedGuid !== undefined && sourceFedGuid >= targetFedGuid)) {
+                hasTargetRow = await targetReader.step();
+            }
+            if (sourceFedGuid === undefined ||
+                (targetFedGuid !== undefined && sourceFedGuid <= targetFedGuid)) {
+                hasSourceRow = await sourceReader.step();
+            }
+        }
+        // query for provenanceDb
+        const provenanceAspectsQuery = `
+      SELECT esa.Identifier, Element.Id
+      FROM bis.ExternalSourceAspect esa
+      WHERE Scope.Id=:scopeId
+        AND Kind=:kind
+      ORDER BY esa.Identifier, esa.ECInstanceId DESC
+    `;
+        // Technically this will a second time call the function (as documented) on
+        // victims of the old provenance method that have both fedguids and an inserted aspect.
+        // But this is a private function with one known caller where that doesn't matter
+        const runFnInDataFlowDirection = (sourceId, targetId) => args.isReverseSynchronization
+            ? args.fn(sourceId, targetId)
+            : args.fn(targetId, sourceId);
+        const params = new core_common_1.QueryBinder();
+        params.bindId("scopeId", args.targetScopeElementId);
+        params.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
+        const provenanceReader = args.provenanceDb.createQueryReader(provenanceAspectsQuery, params, { usePrimaryConn: true });
+        for await (const row of provenanceReader) {
+            // ExternalSourceAspect.Identifier is of type string
+            const aspectIdentifier = row[0];
+            const elementId = row.id;
+            runFnInDataFlowDirection(elementId, aspectIdentifier);
+        }
+    }
+    /**
+     * Queries for an ESA which matches the props in the provided aspectProps.
+     * @param dbToQuery db to run the query on
+     * @param aspectProps aspectProps to search for
+     */
+    static async queryScopeExternalSourceAspect(dbToQuery, aspectProps) {
+        const sql = `
+      SELECT ECInstanceId, Version, JsonProperties
+      FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+      WHERE Element.Id=:elementId
+        AND Scope.Id=:scopeId
+        AND Kind=:kind
+        AND Identifier=:identifier
+      LIMIT 1
+    `;
+        if (aspectProps.scope === undefined)
+            return undefined;
+        const params = new core_common_1.QueryBinder()
+            .bindId("elementId", aspectProps.element.id)
+            .bindId("scopeId", aspectProps.scope.id)
+            .bindString("kind", aspectProps.kind)
+            .bindString("identifier", aspectProps.identifier);
+        return dbToQuery.withQueryReader(sql, (reader) => {
+            if (!reader.step())
+                return undefined;
+            const aspectId = reader.current[0];
+            const version = reader.current[1];
+            const jsonProperties = reader.current[2];
+            return { aspectId, version, jsonProperties };
+        }, params);
+    }
+    // ── Provenance DB direction ────────────────────────────────────────────
+    /** Return the IModelDb where provenance is stored (for reads/queries).
+     * This will be targetDb except when it is a reverse synchronization, in which case it will be sourceDb.
+     */
+    async getProvenanceDb() {
+        return (await this._isReverseSynchronization())
+            ? this._context.sourceDb
+            : this._context.targetDb;
+    }
+    /** Return the EditTxn for writing provenance.
+     * This will be targetEditTxn except when it is a reverse synchronization, in which case it will be sourceEditTxn.
+     */
+    async getProvenanceEditTxn() {
+        if (await this._isReverseSynchronization()) {
+            if (!this._sourceEditTxn) {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.SourceEditTxnRequired,
+                    },
+                    message: "A reverse synchronization requires a sourceEditTxn to write provenance back to the source iModel. " +
+                        "Pass sourceEditTxn in IModelTransformOptions.",
+                });
+            }
+            return this._sourceEditTxn;
+        }
+        return this._targetEditTxn;
+    }
+    /** Return the IModelDb where entities referred to by stored provenance live.
+     * This will be sourceDb except when it is a reverse synchronization, in which case it will be targetDb.
+     */
+    async getProvenanceSourceDb() {
+        return (await this._isReverseSynchronization())
+            ? this._context.targetDb
+            : this._context.sourceDb;
+    }
+    // ── Scope aspect management ────────────────────────────────────────────
+    /**
+     * @returns provenance scope aspect if it exists in the provenanceDb.
+     * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
+     */
+    async tryGetProvenanceScopeAspect() {
+        const scopeProvenanceAspectProps = await ProvenanceManager.queryScopeExternalSourceAspect(await this.getProvenanceDb(), {
+            id: undefined,
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            scope: { id: core_common_1.IModel.rootSubjectId },
+            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
+            element: {
+                id: this._targetScopeElementId ?? core_common_1.IModel.rootSubjectId,
+            },
+            identifier: (await this.getProvenanceSourceDb()).iModelId,
+        });
+        return scopeProvenanceAspectProps !== undefined
+            ? (await this.getProvenanceDb()).elements.getAspect(scopeProvenanceAspectProps.aspectId)
+            : undefined;
+    }
+    /**
+     * 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 (this must be a first synchronization).
+     */
+    async initScopeProvenance() {
+        const provenanceDb = await this.getProvenanceDb();
+        const provenanceEditTxn = await this.getProvenanceEditTxn();
+        const sourceProvenanceDb = await this.getProvenanceSourceDb();
+        const aspectProps = {
+            id: undefined,
+            version: undefined,
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: {
+                id: this._targetScopeElementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
+            scope: { id: core_common_1.IModel.rootSubjectId },
+            identifier: sourceProvenanceDb.iModelId,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
+            jsonProperties: undefined,
+        };
+        const foundEsaProps = await ProvenanceManager.queryScopeExternalSourceAspect(provenanceDb, aspectProps);
+        if (foundEsaProps === undefined) {
+            aspectProps.version = "";
+            aspectProps.jsonProperties = {
+                pendingReverseSyncChangesetIndices: [],
+                pendingSyncChangesetIndices: [],
+                reverseSyncVersion: "",
+            };
+            // query without "identifier" to find possible conflicts
+            const sql = `
+        SELECT ECInstanceId
+        FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+        WHERE Element.Id=:elementId
+          AND Scope.Id=:scopeId
+          AND Kind=:kind
+        LIMIT 1
+      `;
+            const params = new core_common_1.QueryBinder();
+            params.bindId("elementId", aspectProps.element.id);
+            params.bindId("scopeId", aspectProps.scope.id);
+            params.bindString("kind", aspectProps.kind);
+            const reader = provenanceDb.createQueryReader(sql, params, {
+                usePrimaryConn: true,
+            });
+            const hasConflictingScope = await reader.step();
+            if (hasConflictingScope) {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ProvenanceScopeConflict,
+                    },
+                    message: "Provenance scope conflict",
+                });
+            }
+            if (!this._transformerOptions.noProvenance) {
+                const id = provenanceEditTxn.insertAspect({
+                    ...aspectProps,
+                    jsonProperties: JSON.stringify(aspectProps.jsonProperties),
+                });
+                aspectProps.id = id;
+                this.clearCachedSynchronizationVersion();
+            }
+        }
+        else {
+            aspectProps.id = foundEsaProps.aspectId;
+            aspectProps.version = foundEsaProps.version;
+            aspectProps.jsonProperties = foundEsaProps.jsonProperties
+                ? JSON.parse(foundEsaProps.jsonProperties)
+                : undefined;
+            const oldProps = JSON.parse(JSON.stringify(aspectProps));
+            if (this.handleUnsafeMigrate(aspectProps)) {
+                core_bentley_1.Logger.logInfo(loggerCategory, "Unsafe migrate made a change to the target scope's external source aspect. Updating aspect in database.", { oldProps, newProps: aspectProps });
+                provenanceEditTxn.updateAspect({
+                    ...aspectProps,
+                    jsonProperties: JSON.stringify(aspectProps.jsonProperties),
+                });
+                this.clearCachedSynchronizationVersion();
+            }
+        }
+        this._targetScopeProvenanceProps =
+            aspectProps;
+    }
+    /** Returns true if a change was made to the aspectProps. */
+    handleUnsafeMigrate(aspectProps) {
+        let madeChange = false;
+        if (this._transformerOptions.branchRelationshipDataBehavior !==
+            "unsafe-migrate")
+            return madeChange;
+        const fallbackSyncVersionToUse = this._transformerOptions.argsForProcessChanges
+            ?.unsafeFallbackSyncVersion ?? "";
+        const fallbackReverseSyncVersionToUse = this._transformerOptions.argsForProcessChanges
+            ?.unsafeFallbackReverseSyncVersion ?? "";
+        if (aspectProps.version === undefined ||
+            (aspectProps.version === "" &&
+                aspectProps.version !== fallbackSyncVersionToUse)) {
+            aspectProps.version = fallbackSyncVersionToUse;
+            madeChange = true;
+        }
+        if (aspectProps.jsonProperties === undefined) {
+            aspectProps.jsonProperties = {
+                pendingReverseSyncChangesetIndices: [],
+                pendingSyncChangesetIndices: [],
+                reverseSyncVersion: fallbackReverseSyncVersionToUse,
+            };
+            madeChange = true;
+        }
+        else if (aspectProps.jsonProperties.reverseSyncVersion === undefined ||
+            (aspectProps.jsonProperties.reverseSyncVersion === "" &&
+                aspectProps.jsonProperties.reverseSyncVersion !==
+                    fallbackReverseSyncVersionToUse)) {
+            aspectProps.jsonProperties.reverseSyncVersion =
+                fallbackReverseSyncVersionToUse;
+            madeChange = true;
+        }
+        if (aspectProps.jsonProperties.pendingReverseSyncChangesetIndices ===
+            undefined) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingReverseSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
+            aspectProps.jsonProperties.pendingReverseSyncChangesetIndices = [];
+            madeChange = true;
+        }
+        if (aspectProps.jsonProperties.pendingSyncChangesetIndices === undefined) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "Property pendingSyncChangesetIndices missing on the jsonProperties of the scoping ESA. Setting to [].");
+            aspectProps.jsonProperties.pendingSyncChangesetIndices = [];
+            madeChange = true;
+        }
+        return madeChange;
+    }
+    // ── Synchronization version ────────────────────────────────────────────
+    /**
+     * We cache the synchronization version to avoid querying the target scoping ESA multiple times.
+     * Clears the cached value so the next call to getSynchronizationVersion re-queries.
+     */
+    clearCachedSynchronizationVersion() {
+        this._cachedSynchronizationVersion = undefined;
+    }
+    /** The changeset version in the scoping element's source version found for this transformation.
+     * @note the version depends on whether this is a reverse synchronization or not.
+     * @note empty string and -1 for changeset and index if it has never been transformed.
+     */
+    async getSynchronizationVersion() {
+        if (this._cachedSynchronizationVersion === undefined) {
+            const provenanceScopeAspect = await this.tryGetProvenanceScopeAspect();
+            if (!provenanceScopeAspect) {
+                return { index: -1, id: "" };
+            }
+            const version = (await this._isReverseSynchronization())
+                ? JSON.parse(provenanceScopeAspect.jsonProperties ?? "{}").reverseSyncVersion
+                : provenanceScopeAspect.version;
+            if (!version &&
+                this._transformerOptions.branchRelationshipDataBehavior ===
+                    "unsafe-migrate") {
+                return { index: -1, id: "" };
+            }
+            if (version === undefined) {
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.SynchronizationVersionMissing,
+                    },
+                    message: `Could not find synchronization version in scope aspect. This may be due to the last successful run of the transformer being done with an older version.
+         Consider running the transformer with branchRelationshipDataBehavior set to 'unsafe-migrate'`,
+                });
+            }
+            const [id, index] = version === "" ? ["", -1] : version.split(";");
+            if (Number.isNaN(Number(index)))
+                throw new Error("Could not parse version data from scope aspect");
+            this._cachedSynchronizationVersion = { index: Number(index), id };
+        }
+        return this._cachedSynchronizationVersion;
+    }
+    /**
+     * Returns the pending changeset indices to skip for the current synchronization direction.
+     * Used by changeset initialization to determine which changesets have already been processed.
+     */
+    async getChangesetsToSkip() {
+        if (this._targetScopeProvenanceProps === undefined)
+            throw new Error("_targetScopeProvenanceProps should be set by now");
+        const props = this._targetScopeProvenanceProps;
+        return (await this._isReverseSynchronization())
+            ? props.jsonProperties.pendingReverseSyncChangesetIndices
+            : props.jsonProperties.pendingSyncChangesetIndices;
+    }
+    /**
+     * Updates the synchronization version on the scope ESA.
+     *
+     * Called at the end of a transformation, updates the target scope element to record
+     * 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
+     *
+     * @param initializeReverseSyncVersion When true, 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 this 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.
+     *
+     * @param sourceChangeDataState The current state of change data — used to skip updates
+     * when there are no changes.
+     */
+    async updateSynchronizationVersion({ initializeReverseSyncVersion = false, sourceChangeDataState, }) {
+        const shouldSkipSyncVersionUpdate = !initializeReverseSyncVersion && sourceChangeDataState !== "has-changes";
+        if (shouldSkipSyncVersionUpdate)
+            return;
+        // If noProvenance is set, there's no scope ESA to update
+        if (this._transformerOptions.noProvenance)
+            return;
+        if (this._targetScopeProvenanceProps === undefined)
+            throw new Error("_targetScopeProvenanceProps should be set by now");
+        const scopeProps = this._targetScopeProvenanceProps;
+        const sourceVersion = `${this._context.sourceDb.changeset.id};${this._context.sourceDb.changeset.index}`;
+        const targetVersion = `${this._context.targetDb.changeset.id};${this._context.targetDb.changeset.index}`;
+        if (await this._isReverseSynchronization()) {
+            const oldVersion = scopeProps.jsonProperties.reverseSyncVersion;
+            core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse version from ${oldVersion} to ${sourceVersion}`);
+            scopeProps.jsonProperties.reverseSyncVersion = sourceVersion;
+        }
+        else {
+            core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${scopeProps.version} to ${sourceVersion}`);
+            scopeProps.version = sourceVersion;
+            if (initializeReverseSyncVersion) {
+                core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse sync version from ${scopeProps.jsonProperties.reverseSyncVersion} to ${targetVersion}`);
+                scopeProps.jsonProperties.reverseSyncVersion = targetVersion;
+            }
+        }
+        const startingChangesetIndices = this._startingChangesetIndices;
+        if (!!this._transformerOptions.argsForProcessChanges ||
+            (startingChangesetIndices && initializeReverseSyncVersion)) {
+            if (this._context.targetDb.changeset.index === undefined ||
+                startingChangesetIndices === undefined)
+                throw new Error("updateSynchronizationVersion was called without change history");
+            const jsonProps = scopeProps.jsonProperties;
+            core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingReverseSyncChanges: ${String(jsonProps.pendingReverseSyncChangesetIndices)}`);
+            core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingSyncChanges: ${String(jsonProps.pendingSyncChangesetIndices)}`);
+            const pendingSyncChangesetIndicesKey = "pendingSyncChangesetIndices";
+            const pendingReverseSyncChangesetIndicesKey = "pendingReverseSyncChangesetIndices";
+            let syncChangesetsToClearKey;
+            let syncChangesetsToUpdateKey;
+            if (await this._isReverseSynchronization()) {
+                syncChangesetsToClearKey = pendingReverseSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingSyncChangesetIndicesKey;
+            }
+            else {
+                syncChangesetsToClearKey = pendingSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingReverseSyncChangesetIndicesKey;
+            }
+            for (let i = startingChangesetIndices.target + 1; i <= this._context.targetDb.changeset.index + 1; i++)
+                jsonProps[syncChangesetsToUpdateKey].push(i);
+            jsonProps[syncChangesetsToClearKey] = jsonProps[syncChangesetsToClearKey].filter((csIndex) => {
+                return csIndex > startingChangesetIndices.source;
+            });
+            if (await this._isReverseSynchronization()) {
+                if (this._context.sourceDb.changeset.index === undefined)
+                    throw new Error("changeset didn't exist");
+                for (let i = startingChangesetIndices.source + 1; i <= this._context.sourceDb.changeset.index + 1; i++)
+                    jsonProps.pendingReverseSyncChangesetIndices.push(i);
+            }
+            core_bentley_1.Logger.logTrace(loggerCategory, `new pendingReverseSyncChanges: ${String(jsonProps.pendingReverseSyncChangesetIndices)}`);
+            core_bentley_1.Logger.logTrace(loggerCategory, `new pendingSyncChanges: ${String(jsonProps.pendingSyncChangesetIndices)}`);
+        }
+        (await this.getProvenanceEditTxn()).updateAspect({
+            ...scopeProps,
+            jsonProperties: JSON.stringify(scopeProps.jsonProperties),
+        });
+        this.clearCachedSynchronizationVersion();
+    }
+    // ── Element/Relationship provenance creation ───────────────────────────
+    /** Create ExternalSourceAspectProps for an element in an iModel → iModel transformation. */
+    static initElementProvenanceOptions(sourceElementId, targetElementId, args) {
+        const elementId = args.isReverseSynchronization
+            ? sourceElementId
+            : targetElementId;
+        const version = args.isReverseSynchronization
+            ? args.targetDb.elements.queryLastModifiedTime(targetElementId)
+            : args.sourceDb.elements.queryLastModifiedTime(sourceElementId);
+        const aspectIdentifier = args.isReverseSynchronization
+            ? targetElementId
+            : sourceElementId;
+        const aspectProps = {
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: {
+                id: elementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
+            scope: { id: args.targetScopeElementId },
+            identifier: aspectIdentifier,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Element,
+            version,
+        };
+        return aspectProps;
+    }
+    /** Create ExternalSourceAspectProps for a relationship in an iModel → iModel transformation. */
+    static async initRelationshipProvenanceOptions(sourceRelInstanceId, targetRelInstanceId, args) {
+        const provenanceDb = args.isReverseSynchronization
+            ? args.sourceDb
+            : args.targetDb;
+        const aspectIdentifier = args.isReverseSynchronization
+            ? targetRelInstanceId
+            : sourceRelInstanceId;
+        const provenanceRelInstanceId = args.isReverseSynchronization
+            ? sourceRelInstanceId
+            : targetRelInstanceId;
+        // the provenance relationship lives in the provenanceDb, so its known source-endpoint id is
+        // the source rel's on reverse synchronization and the target rel's otherwise
+        let elementId = args.isReverseSynchronization
+            ? args.knownEndpoints?.sourceRelSourceElementId
+            : args.knownEndpoints?.targetRelSourceElementId;
+        if (undefined === elementId) {
+            const sql = "SELECT SourceECInstanceId FROM bis.ElementRefersToElements WHERE ECInstanceId=?";
+            const params = new core_common_1.QueryBinder().bindId(1, provenanceRelInstanceId);
+            const reader = provenanceDb.createQueryReader(sql, params, {
+                usePrimaryConn: true,
+            });
+            if (!(await reader.step()))
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.RelationshipProvenanceNotFound,
+                    },
+                    message: "relationship provenance query returned no rows",
+                });
+            elementId = reader.current[0];
+        }
+        const jsonProperties = args.forceOldRelationshipProvenanceMethod
+            ? { targetRelInstanceId }
+            : { provenanceRelInstanceId };
+        const aspectProps = {
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: {
+                id: elementId,
+                relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName,
+            },
+            scope: { id: args.targetScopeElementId },
+            identifier: aspectIdentifier,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Relationship,
+            jsonProperties: JSON.stringify(jsonProperties),
+        };
+        return aspectProps;
+    }
+    /** Create an ExternalSourceAspectProps for an element using this manager's context. */
+    async initElementProvenance(sourceElementId, targetElementId) {
+        return ProvenanceManager.initElementProvenanceOptions(sourceElementId, targetElementId, {
+            isReverseSynchronization: await this._isReverseSynchronization(),
+            targetScopeElementId: this._targetScopeElementId,
+            sourceDb: this._context.sourceDb,
+            targetDb: this._context.targetDb,
+        });
+    }
+    /** Create an ExternalSourceAspectProps for a relationship using this manager's context. */
+    async initRelationshipProvenance(sourceRelInstanceId, targetRelInstanceId, forceOldRelationshipProvenanceMethod, knownEndpoints) {
+        return ProvenanceManager.initRelationshipProvenanceOptions(sourceRelInstanceId, targetRelInstanceId, {
+            sourceDb: this._context.sourceDb,
+            targetDb: this._context.targetDb,
+            isReverseSynchronization: await this._isReverseSynchronization(),
+            targetScopeElementId: this._targetScopeElementId,
+            forceOldRelationshipProvenanceMethod,
+            knownEndpoints,
+        });
+    }
+    // ── Provenance queries ─────────────────────────────────────────────────
+    /**
+     * Queries the provenanceDb for an ESA whose identifier matches the provided relationship ID.
+     * @param entityInProvenanceSourceId ID of the relationship in the provenanceSourceDb
+     * @param sourceRelInfo Source relationship class and endpoint info (for legacy fallback)
+     */
+    async queryProvenanceForRelationship(entityInProvenanceSourceId, sourceRelInfo) {
+        const sql = `
+      SELECT
+        ECInstanceId,
+        JSON_EXTRACT(JsonProperties, '$.provenanceRelInstanceId') AS provenanceRelInstId
+      FROM Bis.ExternalSourceAspect
+      WHERE Kind=?
+        AND Scope.Id=?
+        AND Identifier=?
+    `;
+        const params = new core_common_1.QueryBinder();
+        params.bindString(1, core_backend_1.ExternalSourceAspect.Kind.Relationship);
+        params.bindId(2, this._targetScopeElementId);
+        params.bindString(3, entityInProvenanceSourceId);
+        const result = (await this.getProvenanceDb()).createQueryReader(sql, params, {
+            usePrimaryConn: true,
+        });
+        if (await result.step()) {
+            const aspectId = result.current.id;
+            const provenanceRelInstId = result.current.provenanceRelInstId;
+            const provenanceRelInstanceId = provenanceRelInstId !== undefined
+                ? provenanceRelInstId
+                : await this._queryTargetRelId(sourceRelInfo);
+            return {
+                aspectId,
+                relationshipId: provenanceRelInstanceId,
+            };
+        }
+        else
+            return undefined;
+    }
+    /** Instance convenience that calls the static forEachTrackedElement with this manager's context. */
+    async forEachTrackedElement(fn) {
+        return ProvenanceManager.forEachTrackedElement({
+            provenanceSourceDb: await this.getProvenanceSourceDb(),
+            provenanceDb: await this.getProvenanceDb(),
+            targetScopeElementId: this._targetScopeElementId,
+            isReverseSynchronization: await this._isReverseSynchronization(),
+            fn,
+            skipPropagateChangesToRootElements: this._transformerOptions.skipPropagateChangesToRootElements ?? true,
+        });
+    }
+}
+exports.ProvenanceManager = ProvenanceManager;
+/** Returns the target scope elements: those that own a Scope ExternalSourceAspect.
+ * A transformation creates its target scope's Scope aspect before it exports any aspect, so the result includes the current target scope.
+ * @internal
+ */
+async function queryTargetScopeElementIds(db) {
+    const ids = new Set();
+    for await (const row of db.createQueryReader(`SELECT Element.Id id FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Kind = :scopeKind`, new core_common_1.QueryBinder().bindString("scopeKind", core_backend_1.ExternalSourceAspect.Kind.Scope), { usePrimaryConn: true }))
+        ids.add(row.id);
+    return ids;
+}
+/** Whether an aspect is transformer provenance: a Scope ExternalSourceAspect, or an Element or Relationship ExternalSourceAspect scoped to one of `targetScopeElementIds`.
+ * Every target scope counts, not just the current one: an element shared by several target scopes, such as one source imported in parts, carries each scope's provenance.
+ * Cleanup never deletes transformer provenance.
+ * @internal
+ */
+function isTransformerProvenanceAspect(aspect, targetScopeElementIds) {
+    if (!(aspect instanceof core_backend_1.ExternalSourceAspect))
+        return false;
+    if (aspect.kind === core_backend_1.ExternalSourceAspect.Kind.Scope)
+        return true;
+    return ((aspect.kind === core_backend_1.ExternalSourceAspect.Kind.Element ||
+        aspect.kind === core_backend_1.ExternalSourceAspect.Kind.Relationship) &&
+        aspect.scope !== undefined &&
+        targetScopeElementIds.has(aspect.scope.id));
+}
+/** Returns the `importElementMultiAspects` filter for a transformation that includes source provenance.
+ * Source provenance cloned from another transformation looks exactly like another target scope's provenance, so a transformer provenance aspect is only eligible for reuse when an incoming ExternalSourceAspect has the same kind, scope, and identifier.
+ * The current scope's own provenance is never eligible: the transformer maintains it separately.
+ * @internal
+ */
+function sourceProvenanceMatchFilter(incoming, targetScopeElementIds, currentScopeElementId) {
+    const incomingKeys = new Set(incoming
+        .filter((props) => (0, ElementAspectCleanup_1.isSameClass)(props, core_backend_1.ExternalSourceAspect.classFullName))
+        .map((props) => externalSourceAspectKey(props)));
+    return (aspect) => {
+        if (!isTransformerProvenanceAspect(aspect, targetScopeElementIds))
+            return true;
+        const scopeElementId = aspect.kind === core_backend_1.ExternalSourceAspect.Kind.Scope
+            ? aspect.element.id
+            : aspect.scope?.id;
+        return (scopeElementId !== currentScopeElementId &&
+            incomingKeys.has(externalSourceAspectKey(aspect)));
+    };
+}
+/** The natural key of an ExternalSourceAspect on its owner. Kinds and IDs never contain `|`, and the identifier comes last, so distinct keys can't collide. */
+function externalSourceAspectKey(aspect) {
+    return `${aspect.kind}|${aspect.scope?.id}|${aspect.identifier}`;
+}
+//# sourceMappingURL=ProvenanceManager.js.map