@itwin/imodel-transformer 2.0.0-dev.5 → 2.0.0-dev.51

package/lib/cjs/IModelTransformerError.d.ts

@@ -0,0 +1,84 @@
+/** Scope shared by errors originating from `@itwin/imodel-transformer`.
+ * @beta
+ */
+export declare const IModelTransformerErrorScope = "@itwin/imodel-transformer";
+/** Errors originating from `@itwin/imodel-transformer`.
+ * @beta
+ */
+export declare enum IModelTransformerError {
+    /** An ElementAspect change requires its owning element identifier. */
+    AspectOwnerRequired = "aspect-owner-required",
+    /** Required changed-instance metadata is missing. */
+    ChangedInstanceMetadataMissing = "changed-instance-metadata-missing",
+    /** A required changeset index is unavailable. */
+    ChangesetIndexUnavailable = "changeset-index-unavailable",
+    /** A source entity contains a dangling reference rejected by transformer policy. */
+    DanglingReference = "dangling-reference",
+    /** A required dependency has no target mapping. */
+    DependencyMappingMissing = "dependency-mapping-missing",
+    /** The installed iTwin.js dependency version is incompatible. */
+    DependencyVersionMismatch = "dependency-version-mismatch",
+    /** A required edit transaction is not active. */
+    EditTxnNotActive = "edit-txn-not-active",
+    /** Native bulk deletion failed for one or more requested element trees. */
+    ElementBulkDeleteFailed = "element-bulk-delete-failed",
+    /** An element identifier cannot be preserved in the target. */
+    ElementIdNotPreservable = "element-id-not-preservable",
+    /** A required element identifier was not provided. */
+    ElementIdRequired = "element-id-required",
+    /** Exporting changes requires a briefcase iModel. */
+    ExportChangesRequiresBriefcase = "export-changes-requires-briefcase",
+    /** No export handler has been registered. */
+    ExportHandlerNotRegistered = "export-handler-not-registered",
+    /** A required geographic coordinate system is unavailable. */
+    GeographicCoordinateSystemUnavailable = "geographic-coordinate-system-unavailable",
+    /** Source and target geographic coordinate systems are incompatible. */
+    GeographicCoordinateSystemMismatch = "geographic-coordinate-system-mismatch",
+    /** Required geolocation data or an invertible geolocation transform is unavailable. */
+    GeolocationUnavailable = "geolocation-unavailable",
+    /** A custom importer option conflicts with the transformer option. */
+    ImporterOptionMismatch = "importer-option-mismatch",
+    /** A code is invalid or incomplete. */
+    InvalidCode = "invalid-code",
+    /** An entity reference has an unsupported representation. */
+    InvalidEntityReference = "invalid-entity-reference",
+    /** A relationship query returned malformed instance data. */
+    InvalidRelationshipData = "invalid-relationship-data",
+    /** A model identifier is invalid or missing. */
+    InvalidModelId = "invalid-model-id",
+    /** A subcategory is invalid or incomplete. */
+    InvalidSubCategory = "invalid-subcategory",
+    /** The source iModel has no changesets or custom changes. */
+    NoChangesets = "no-changesets",
+    /** A required parent model was not provided. */
+    ParentModelRequired = "parent-model-required",
+    /** A provenance scope conflicts with existing provenance. */
+    ProvenanceScopeConflict = "provenance-scope-conflict",
+    /** The BisCore schema does not support required provenance data. */
+    ProvenanceSchemaUnsupported = "provenance-schema-unsupported",
+    /** A required relationship class is absent. */
+    RelationshipClassNotFound = "relationship-class-not-found",
+    /** A required relationship identifier was not provided. */
+    RelationshipIdRequired = "relationship-id-required",
+    /** Expected relationship provenance is absent. */
+    RelationshipProvenanceNotFound = "relationship-provenance-not-found",
+    /** The root subject cannot be processed directly. */
+    RootSubjectNotProcessable = "root-subject-not-processable",
+    /** A schema conflict or incompatible schema version prevented processing. */
+    SchemaConflict = "schema-conflict",
+    /** The source schema dependency graph contains a cycle. */
+    SchemaDependencyCycle = "schema-dependency-cycle",
+    /** A required schema could not be loaded. */
+    SchemaLoadFailed = "schema-load-failed",
+    /** Reverse synchronization requires a source edit transaction. */
+    SourceEditTxnRequired = "source-edit-txn-required",
+    /** The requested synchronization range is invalid. */
+    SynchronizationRangeInvalid = "synchronization-range-invalid",
+    /** The synchronization direction cannot be determined. */
+    SynchronizationTypeNotDetermined = "synchronization-type-not-determined",
+    /** The previous synchronization version is missing. */
+    SynchronizationVersionMissing = "synchronization-version-missing",
+    /** A required class is absent from the target iModel. */
+    TargetClassNotFound = "target-class-not-found"
+}
+//# sourceMappingURL=IModelTransformerError.d.ts.map

package/lib/cjs/IModelTransformerError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModelTransformerError.d.ts","sourceRoot":"","sources":["../../src/IModelTransformerError.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,eAAO,MAAM,2BAA2B,8BAA8B,CAAC;AAEvE;;GAEG;AACH,oBAAY,sBAAsB;IAChC,sEAAsE;IACtE,mBAAmB,0BAA0B;IAC7C,qDAAqD;IACrD,8BAA8B,sCAAsC;IACpE,iDAAiD;IACjD,yBAAyB,gCAAgC;IACzD,oFAAoF;IACpF,iBAAiB,uBAAuB;IACxC,mDAAmD;IACnD,wBAAwB,+BAA+B;IACvD,iEAAiE;IACjE,yBAAyB,gCAAgC;IACzD,iDAAiD;IACjD,gBAAgB,wBAAwB;IACxC,2EAA2E;IAC3E,uBAAuB,+BAA+B;IACtD,+DAA+D;IAC/D,uBAAuB,+BAA+B;IACtD,sDAAsD;IACtD,iBAAiB,wBAAwB;IACzC,qDAAqD;IACrD,8BAA8B,sCAAsC;IACpE,6CAA6C;IAC7C,0BAA0B,kCAAkC;IAC5D,8DAA8D;IAC9D,qCAAqC,6CAA6C;IAClF,wEAAwE;IACxE,kCAAkC,0CAA0C;IAC5E,uFAAuF;IACvF,sBAAsB,4BAA4B;IAClD,sEAAsE;IACtE,sBAAsB,6BAA6B;IACnD,uCAAuC;IACvC,WAAW,iBAAiB;IAC5B,6DAA6D;IAC7D,sBAAsB,6BAA6B;IACnD,6DAA6D;IAC7D,uBAAuB,8BAA8B;IACrD,gDAAgD;IAChD,cAAc,qBAAqB;IACnC,8CAA8C;IAC9C,kBAAkB,wBAAwB;IAC1C,6DAA6D;IAC7D,YAAY,kBAAkB;IAC9B,gDAAgD;IAChD,mBAAmB,0BAA0B;IAC7C,6DAA6D;IAC7D,uBAAuB,8BAA8B;IACrD,oEAAoE;IACpE,2BAA2B,kCAAkC;IAC7D,+CAA+C;IAC/C,yBAAyB,iCAAiC;IAC1D,2DAA2D;IAC3D,sBAAsB,6BAA6B;IACnD,kDAAkD;IAClD,8BAA8B,sCAAsC;IACpE,qDAAqD;IACrD,yBAAyB,iCAAiC;IAC1D,6EAA6E;IAC7E,cAAc,oBAAoB;IAClC,2DAA2D;IAC3D,qBAAqB,4BAA4B;IACjD,6CAA6C;IAC7C,gBAAgB,uBAAuB;IACvC,kEAAkE;IAClE,qBAAqB,6BAA6B;IAClD,sDAAsD;IACtD,2BAA2B,kCAAkC;IAC7D,0DAA0D;IAC1D,gCAAgC,wCAAwC;IACxE,uDAAuD;IACvD,6BAA6B,oCAAoC;IACjE,yDAAyD;IACzD,mBAAmB,2BAA2B;CAC/C"}

package/lib/cjs/IModelTransformerError.js

@@ -0,0 +1,93 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IModelTransformerError = exports.IModelTransformerErrorScope = void 0;
+/** Scope shared by errors originating from `@itwin/imodel-transformer`.
+ * @beta
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+exports.IModelTransformerErrorScope = "@itwin/imodel-transformer";
+/** Errors originating from `@itwin/imodel-transformer`.
+ * @beta
+ */
+var IModelTransformerError;
+(function (IModelTransformerError) {
+    /** An ElementAspect change requires its owning element identifier. */
+    IModelTransformerError["AspectOwnerRequired"] = "aspect-owner-required";
+    /** Required changed-instance metadata is missing. */
+    IModelTransformerError["ChangedInstanceMetadataMissing"] = "changed-instance-metadata-missing";
+    /** A required changeset index is unavailable. */
+    IModelTransformerError["ChangesetIndexUnavailable"] = "changeset-index-unavailable";
+    /** A source entity contains a dangling reference rejected by transformer policy. */
+    IModelTransformerError["DanglingReference"] = "dangling-reference";
+    /** A required dependency has no target mapping. */
+    IModelTransformerError["DependencyMappingMissing"] = "dependency-mapping-missing";
+    /** The installed iTwin.js dependency version is incompatible. */
+    IModelTransformerError["DependencyVersionMismatch"] = "dependency-version-mismatch";
+    /** A required edit transaction is not active. */
+    IModelTransformerError["EditTxnNotActive"] = "edit-txn-not-active";
+    /** Native bulk deletion failed for one or more requested element trees. */
+    IModelTransformerError["ElementBulkDeleteFailed"] = "element-bulk-delete-failed";
+    /** An element identifier cannot be preserved in the target. */
+    IModelTransformerError["ElementIdNotPreservable"] = "element-id-not-preservable";
+    /** A required element identifier was not provided. */
+    IModelTransformerError["ElementIdRequired"] = "element-id-required";
+    /** Exporting changes requires a briefcase iModel. */
+    IModelTransformerError["ExportChangesRequiresBriefcase"] = "export-changes-requires-briefcase";
+    /** No export handler has been registered. */
+    IModelTransformerError["ExportHandlerNotRegistered"] = "export-handler-not-registered";
+    /** A required geographic coordinate system is unavailable. */
+    IModelTransformerError["GeographicCoordinateSystemUnavailable"] = "geographic-coordinate-system-unavailable";
+    /** Source and target geographic coordinate systems are incompatible. */
+    IModelTransformerError["GeographicCoordinateSystemMismatch"] = "geographic-coordinate-system-mismatch";
+    /** Required geolocation data or an invertible geolocation transform is unavailable. */
+    IModelTransformerError["GeolocationUnavailable"] = "geolocation-unavailable";
+    /** A custom importer option conflicts with the transformer option. */
+    IModelTransformerError["ImporterOptionMismatch"] = "importer-option-mismatch";
+    /** A code is invalid or incomplete. */
+    IModelTransformerError["InvalidCode"] = "invalid-code";
+    /** An entity reference has an unsupported representation. */
+    IModelTransformerError["InvalidEntityReference"] = "invalid-entity-reference";
+    /** A relationship query returned malformed instance data. */
+    IModelTransformerError["InvalidRelationshipData"] = "invalid-relationship-data";
+    /** A model identifier is invalid or missing. */
+    IModelTransformerError["InvalidModelId"] = "invalid-model-id";
+    /** A subcategory is invalid or incomplete. */
+    IModelTransformerError["InvalidSubCategory"] = "invalid-subcategory";
+    /** The source iModel has no changesets or custom changes. */
+    IModelTransformerError["NoChangesets"] = "no-changesets";
+    /** A required parent model was not provided. */
+    IModelTransformerError["ParentModelRequired"] = "parent-model-required";
+    /** A provenance scope conflicts with existing provenance. */
+    IModelTransformerError["ProvenanceScopeConflict"] = "provenance-scope-conflict";
+    /** The BisCore schema does not support required provenance data. */
+    IModelTransformerError["ProvenanceSchemaUnsupported"] = "provenance-schema-unsupported";
+    /** A required relationship class is absent. */
+    IModelTransformerError["RelationshipClassNotFound"] = "relationship-class-not-found";
+    /** A required relationship identifier was not provided. */
+    IModelTransformerError["RelationshipIdRequired"] = "relationship-id-required";
+    /** Expected relationship provenance is absent. */
+    IModelTransformerError["RelationshipProvenanceNotFound"] = "relationship-provenance-not-found";
+    /** The root subject cannot be processed directly. */
+    IModelTransformerError["RootSubjectNotProcessable"] = "root-subject-not-processable";
+    /** A schema conflict or incompatible schema version prevented processing. */
+    IModelTransformerError["SchemaConflict"] = "schema-conflict";
+    /** The source schema dependency graph contains a cycle. */
+    IModelTransformerError["SchemaDependencyCycle"] = "schema-dependency-cycle";
+    /** A required schema could not be loaded. */
+    IModelTransformerError["SchemaLoadFailed"] = "schema-load-failed";
+    /** Reverse synchronization requires a source edit transaction. */
+    IModelTransformerError["SourceEditTxnRequired"] = "source-edit-txn-required";
+    /** The requested synchronization range is invalid. */
+    IModelTransformerError["SynchronizationRangeInvalid"] = "synchronization-range-invalid";
+    /** The synchronization direction cannot be determined. */
+    IModelTransformerError["SynchronizationTypeNotDetermined"] = "synchronization-type-not-determined";
+    /** The previous synchronization version is missing. */
+    IModelTransformerError["SynchronizationVersionMissing"] = "synchronization-version-missing";
+    /** A required class is absent from the target iModel. */
+    IModelTransformerError["TargetClassNotFound"] = "target-class-not-found";
+})(IModelTransformerError || (exports.IModelTransformerError = IModelTransformerError = {}));
+//# sourceMappingURL=IModelTransformerError.js.map

package/lib/cjs/IModelTransformerError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModelTransformerError.js","sourceRoot":"","sources":["../../src/IModelTransformerError.ts"],"names":[],"mappings":";AAAA;;;gGAGgG;;;AAEhG;;GAEG;AACH,gEAAgE;AACnD,QAAA,2BAA2B,GAAG,2BAA2B,CAAC;AAEvE;;GAEG;AACH,IAAY,sBA2EX;AA3ED,WAAY,sBAAsB;IAChC,sEAAsE;IACtE,uEAA6C,CAAA;IAC7C,qDAAqD;IACrD,8FAAoE,CAAA;IACpE,iDAAiD;IACjD,mFAAyD,CAAA;IACzD,oFAAoF;IACpF,kEAAwC,CAAA;IACxC,mDAAmD;IACnD,iFAAuD,CAAA;IACvD,iEAAiE;IACjE,mFAAyD,CAAA;IACzD,iDAAiD;IACjD,kEAAwC,CAAA;IACxC,2EAA2E;IAC3E,gFAAsD,CAAA;IACtD,+DAA+D;IAC/D,gFAAsD,CAAA;IACtD,sDAAsD;IACtD,mEAAyC,CAAA;IACzC,qDAAqD;IACrD,8FAAoE,CAAA;IACpE,6CAA6C;IAC7C,sFAA4D,CAAA;IAC5D,8DAA8D;IAC9D,4GAAkF,CAAA;IAClF,wEAAwE;IACxE,sGAA4E,CAAA;IAC5E,uFAAuF;IACvF,4EAAkD,CAAA;IAClD,sEAAsE;IACtE,6EAAmD,CAAA;IACnD,uCAAuC;IACvC,sDAA4B,CAAA;IAC5B,6DAA6D;IAC7D,6EAAmD,CAAA;IACnD,6DAA6D;IAC7D,+EAAqD,CAAA;IACrD,gDAAgD;IAChD,6DAAmC,CAAA;IACnC,8CAA8C;IAC9C,oEAA0C,CAAA;IAC1C,6DAA6D;IAC7D,wDAA8B,CAAA;IAC9B,gDAAgD;IAChD,uEAA6C,CAAA;IAC7C,6DAA6D;IAC7D,+EAAqD,CAAA;IACrD,oEAAoE;IACpE,uFAA6D,CAAA;IAC7D,+CAA+C;IAC/C,oFAA0D,CAAA;IAC1D,2DAA2D;IAC3D,6EAAmD,CAAA;IACnD,kDAAkD;IAClD,8FAAoE,CAAA;IACpE,qDAAqD;IACrD,oFAA0D,CAAA;IAC1D,6EAA6E;IAC7E,4DAAkC,CAAA;IAClC,2DAA2D;IAC3D,2EAAiD,CAAA;IACjD,6CAA6C;IAC7C,iEAAuC,CAAA;IACvC,kEAAkE;IAClE,4EAAkD,CAAA;IAClD,sDAAsD;IACtD,uFAA6D,CAAA;IAC7D,0DAA0D;IAC1D,kGAAwE,CAAA;IACxE,uDAAuD;IACvD,2FAAiE,CAAA;IACjE,yDAAyD;IACzD,wEAA8C,CAAA;AAChD,CAAC,EA3EW,sBAAsB,aAAtB,sBAAsB,GAAtB,sBAAsB,QA2EjC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\n/** Scope shared by errors originating from `@itwin/imodel-transformer`.\n * @beta\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const IModelTransformerErrorScope = \"@itwin/imodel-transformer\";\n\n/** Errors originating from `@itwin/imodel-transformer`.\n * @beta\n */\nexport enum IModelTransformerError {\n  /** An ElementAspect change requires its owning element identifier. */\n  AspectOwnerRequired = \"aspect-owner-required\",\n  /** Required changed-instance metadata is missing. */\n  ChangedInstanceMetadataMissing = \"changed-instance-metadata-missing\",\n  /** A required changeset index is unavailable. */\n  ChangesetIndexUnavailable = \"changeset-index-unavailable\",\n  /** A source entity contains a dangling reference rejected by transformer policy. */\n  DanglingReference = \"dangling-reference\",\n  /** A required dependency has no target mapping. */\n  DependencyMappingMissing = \"dependency-mapping-missing\",\n  /** The installed iTwin.js dependency version is incompatible. */\n  DependencyVersionMismatch = \"dependency-version-mismatch\",\n  /** A required edit transaction is not active. */\n  EditTxnNotActive = \"edit-txn-not-active\",\n  /** Native bulk deletion failed for one or more requested element trees. */\n  ElementBulkDeleteFailed = \"element-bulk-delete-failed\",\n  /** An element identifier cannot be preserved in the target. */\n  ElementIdNotPreservable = \"element-id-not-preservable\",\n  /** A required element identifier was not provided. */\n  ElementIdRequired = \"element-id-required\",\n  /** Exporting changes requires a briefcase iModel. */\n  ExportChangesRequiresBriefcase = \"export-changes-requires-briefcase\",\n  /** No export handler has been registered. */\n  ExportHandlerNotRegistered = \"export-handler-not-registered\",\n  /** A required geographic coordinate system is unavailable. */\n  GeographicCoordinateSystemUnavailable = \"geographic-coordinate-system-unavailable\",\n  /** Source and target geographic coordinate systems are incompatible. */\n  GeographicCoordinateSystemMismatch = \"geographic-coordinate-system-mismatch\",\n  /** Required geolocation data or an invertible geolocation transform is unavailable. */\n  GeolocationUnavailable = \"geolocation-unavailable\",\n  /** A custom importer option conflicts with the transformer option. */\n  ImporterOptionMismatch = \"importer-option-mismatch\",\n  /** A code is invalid or incomplete. */\n  InvalidCode = \"invalid-code\",\n  /** An entity reference has an unsupported representation. */\n  InvalidEntityReference = \"invalid-entity-reference\",\n  /** A relationship query returned malformed instance data. */\n  InvalidRelationshipData = \"invalid-relationship-data\",\n  /** A model identifier is invalid or missing. */\n  InvalidModelId = \"invalid-model-id\",\n  /** A subcategory is invalid or incomplete. */\n  InvalidSubCategory = \"invalid-subcategory\",\n  /** The source iModel has no changesets or custom changes. */\n  NoChangesets = \"no-changesets\",\n  /** A required parent model was not provided. */\n  ParentModelRequired = \"parent-model-required\",\n  /** A provenance scope conflicts with existing provenance. */\n  ProvenanceScopeConflict = \"provenance-scope-conflict\",\n  /** The BisCore schema does not support required provenance data. */\n  ProvenanceSchemaUnsupported = \"provenance-schema-unsupported\",\n  /** A required relationship class is absent. */\n  RelationshipClassNotFound = \"relationship-class-not-found\",\n  /** A required relationship identifier was not provided. */\n  RelationshipIdRequired = \"relationship-id-required\",\n  /** Expected relationship provenance is absent. */\n  RelationshipProvenanceNotFound = \"relationship-provenance-not-found\",\n  /** The root subject cannot be processed directly. */\n  RootSubjectNotProcessable = \"root-subject-not-processable\",\n  /** A schema conflict or incompatible schema version prevented processing. */\n  SchemaConflict = \"schema-conflict\",\n  /** The source schema dependency graph contains a cycle. */\n  SchemaDependencyCycle = \"schema-dependency-cycle\",\n  /** A required schema could not be loaded. */\n  SchemaLoadFailed = \"schema-load-failed\",\n  /** Reverse synchronization requires a source edit transaction. */\n  SourceEditTxnRequired = \"source-edit-txn-required\",\n  /** The requested synchronization range is invalid. */\n  SynchronizationRangeInvalid = \"synchronization-range-invalid\",\n  /** The synchronization direction cannot be determined. */\n  SynchronizationTypeNotDetermined = \"synchronization-type-not-determined\",\n  /** The previous synchronization version is missing. */\n  SynchronizationVersionMissing = \"synchronization-version-missing\",\n  /** A required class is absent from the target iModel. */\n  TargetClassNotFound = \"target-class-not-found\",\n}\n"]}

package/lib/cjs/ProvenanceManager.d.ts

@@ -0,0 +1,182 @@
+import { Id64String } from "@itwin/core-bentley";
+import { EditTxn, type Entity, ExternalSourceAspect, IModelDb } from "@itwin/core-backend";
+import { ChangesetIndexAndId, ExternalSourceAspectProps } from "@itwin/core-common";
+import type { IModelTransformOptions } from "./IModelTransformer";
+import type { SyncTypeResolver } from "./SyncTypeResolver";
+import type { IModelTransformContext } from "./IModelTransformContext";
+type ProvenanceContext = Pick<IModelTransformContext, "findTargetElementId"> & {
+    readonly sourceDb: IModelDb;
+    readonly targetDb: IModelDb;
+};
+/**
+ * Manages provenance scope aspects and synchronization versioning.
+ * Encapsulates all ESA scope management, sync version tracking, and
+ * provenance DB direction logic extracted from IModelTransformer.
+ * @internal
+ */
+export declare class ProvenanceManager {
+    private readonly _context;
+    private readonly _targetScopeElementId;
+    private readonly _transformerOptions;
+    private readonly _syncTypeResolver;
+    private readonly _startingChangesetIndices?;
+    /** NOTE: the json properties must be converted to string before insertion */
+    private _targetScopeProvenanceProps;
+    private _cachedSynchronizationVersion;
+    private _targetClassNameToClassIdCache;
+    private readonly _targetEditTxn;
+    private readonly _sourceEditTxn?;
+    constructor(targetScopeElementId: Id64String, transformerOptions: IModelTransformOptions, context: ProvenanceContext, syncTypeResolver: SyncTypeResolver, targetEditTxn: EditTxn, sourceEditTxn?: EditTxn);
+    private _isReverseSynchronization;
+    private _queryTargetRelId;
+    private _targetClassNameToClassId;
+    private _getRelClassId;
+    /** The element classes that are considered to define provenance in the iModel */
+    static get provenanceElementClasses(): (typeof Entity)[];
+    /** The element aspect classes that are considered to define provenance in the iModel */
+    static get provenanceElementAspectClasses(): (typeof Entity)[];
+    /**
+     * Iterate all matching federation guids and ExternalSourceAspects in the provenance iModel (target unless reverse sync)
+     * and call a function for each one.
+     * @note provenance is done by federation guids where possible
+     * @note this may execute on each element more than once! Only use in cases where that is handled
+     */
+    static forEachTrackedElement(args: {
+        provenanceSourceDb: IModelDb;
+        provenanceDb: IModelDb;
+        targetScopeElementId: Id64String;
+        isReverseSynchronization: boolean;
+        fn: (sourceElementId: Id64String, targetElementId: Id64String) => void;
+        skipPropagateChangesToRootElements: boolean;
+    }): Promise<void>;
+    /**
+     * 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 queryScopeExternalSourceAspect(dbToQuery: IModelDb, aspectProps: ExternalSourceAspectProps): Promise<{
+        aspectId: Id64String;
+        version?: string;
+        /** stringified json */
+        jsonProperties?: string;
+    } | undefined>;
+    /** 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.
+     */
+    private getProvenanceDb;
+    /** Return the EditTxn for writing provenance.
+     * This will be targetEditTxn except when it is a reverse synchronization, in which case it will be sourceEditTxn.
+     */
+    getProvenanceEditTxn(): Promise<EditTxn>;
+    /** 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.
+     */
+    getProvenanceSourceDb(): Promise<IModelDb>;
+    /**
+     * @returns provenance scope aspect if it exists in the provenanceDb.
+     * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
+     */
+    tryGetProvenanceScopeAspect(): Promise<ExternalSourceAspect | 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).
+     */
+    initScopeProvenance(): Promise<void>;
+    /** Returns true if a change was made to the aspectProps. */
+    private handleUnsafeMigrate;
+    /**
+     * 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(): void;
+    /** 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.
+     */
+    getSynchronizationVersion(): Promise<ChangesetIndexAndId>;
+    /**
+     * Returns the pending changeset indices to skip for the current synchronization direction.
+     * Used by changeset initialization to determine which changesets have already been processed.
+     */
+    getChangesetsToSkip(): Promise<number[]>;
+    /**
+     * 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.
+     */
+    updateSynchronizationVersion({ initializeReverseSyncVersion, sourceChangeDataState, }: {
+        initializeReverseSyncVersion?: boolean;
+        sourceChangeDataState: "uninited" | "has-changes" | "no-changes" | "unconnected";
+    }): Promise<void>;
+    /** Create ExternalSourceAspectProps for an element in an iModel → iModel transformation. */
+    static initElementProvenanceOptions(sourceElementId: Id64String, targetElementId: Id64String, args: {
+        sourceDb: IModelDb;
+        targetDb: IModelDb;
+        isReverseSynchronization: boolean;
+        targetScopeElementId: Id64String;
+    }): ExternalSourceAspectProps;
+    /** Create ExternalSourceAspectProps for a relationship in an iModel → iModel transformation. */
+    static initRelationshipProvenanceOptions(sourceRelInstanceId: Id64String, targetRelInstanceId: Id64String, args: {
+        sourceDb: IModelDb;
+        targetDb: IModelDb;
+        isReverseSynchronization: boolean;
+        targetScopeElementId: Id64String;
+        forceOldRelationshipProvenanceMethod: boolean;
+        /** Already-known source-endpoint element ids of the relationships, used to skip the
+         * per-relationship endpoint query when the caller knows the needed id.
+         */
+        knownEndpoints?: {
+            /** `SourceECInstanceId` of the relationship identified by `sourceRelInstanceId` in `sourceDb`. */
+            sourceRelSourceElementId?: Id64String;
+            /** `SourceECInstanceId` of the relationship identified by `targetRelInstanceId` in `targetDb`. */
+            targetRelSourceElementId?: Id64String;
+        };
+    }): Promise<ExternalSourceAspectProps>;
+    /** Create an ExternalSourceAspectProps for an element using this manager's context. */
+    initElementProvenance(sourceElementId: Id64String, targetElementId: Id64String): Promise<ExternalSourceAspectProps>;
+    /** Create an ExternalSourceAspectProps for a relationship using this manager's context. */
+    initRelationshipProvenance(sourceRelInstanceId: Id64String, targetRelInstanceId: Id64String, forceOldRelationshipProvenanceMethod: boolean, knownEndpoints?: {
+        sourceRelSourceElementId?: Id64String;
+        targetRelSourceElementId?: Id64String;
+    }): Promise<ExternalSourceAspectProps>;
+    /**
+     * Queries the provenanceDb for an ESA whose identifier matches the provided element ID.
+     * @param entityInProvenanceSourceId ID of the element in the provenanceSourceDb
+     */
+    queryProvenanceForElement(entityInProvenanceSourceId: Id64String): Promise<Id64String | undefined>;
+    /**
+     * 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)
+     */
+    queryProvenanceForRelationship(entityInProvenanceSourceId: Id64String, sourceRelInfo: {
+        classFullName: string;
+        sourceId: Id64String;
+        targetId: Id64String;
+    }): Promise<{
+        aspectId: Id64String;
+        /** if undefined, the relationship could not be found, perhaps it was deleted */
+        relationshipId: Id64String | undefined;
+    } | undefined>;
+    /** Instance convenience that calls the static forEachTrackedElement with this manager's context. */
+    forEachTrackedElement(fn: (sourceElementId: Id64String, targetElementId: Id64String) => void): Promise<void>;
+}
+export {};
+//# sourceMappingURL=ProvenanceManager.d.ts.map

package/lib/cjs/ProvenanceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProvenanceManager.d.ts","sourceRoot":"","sources":["../../src/ProvenanceManager.ts"],"names":[],"mappings":"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"}