Add the ability to release the locks associated with reversed Txns

common/api/core-backend.api.md

@@ -221,6 +221,7 @@ import { Range2dProps } from '@itwin/core-geometry';
 import { Range3d } from '@itwin/core-geometry';
 import { Range3dProps } from '@itwin/core-geometry';
 import { Rank } from '@itwin/core-common';
+import { ReinstateTxnArgs } from '@itwin/core-common';
 import { RelatedElement } from '@itwin/core-common';
 import { RelatedElementProps } from '@itwin/core-common';
 import { RelationshipClass } from '@itwin/ecschema-metadata';
@@ -231,6 +232,7 @@ import { RenderSchedule } from '@itwin/core-common';
 import { RenderTimelineProps } from '@itwin/core-common';
 import { RepositoryLinkProps } from '@itwin/core-common';
 import { RequestNewBriefcaseProps } from '@itwin/core-common';
+import { ReverseTxnArgs } from '@itwin/core-common';
 import { RgbFactorProps } from '@itwin/core-common';
 import { RpcActivity } from '@itwin/core-common';
 import { RpcInterfaceEndpoints } from '@itwin/core-common';
@@ -442,6 +444,10 @@ export interface AzureBlobStorageCredentials {
 
 // @public
 export interface BackendHubAccess {
+    // @beta
+    abandonAllLocks?: (arg: BriefcaseIdArg) => Promise<void>;
+    // @beta
+    abandonLocks?: (arg: BriefcaseIdArg, locks: LockMap) => Promise<void>;
     acquireLocks: (arg: BriefcaseDbArg, locks: LockMap) => Promise<void>;
     acquireNewBriefcaseId: (arg: AcquireNewBriefcaseIdArg) => Promise<BriefcaseId>;
     createNewIModel: (arg: CreateNewIModelProps) => Promise<GuidString>;
@@ -5062,13 +5068,25 @@ export interface LockControl {
     readonly [_implementationProhibited]: unknown;
     // @internal
     [_releaseAllLocks]: () => Promise<void>;
+    // @beta
+    abandonAllLocks(): Promise<void>;
+    // @beta
+    abandonLocksForCurrentUnsavedTxn(): Promise<boolean>;
+    // @beta
+    abandonLocksForReversedTxn(txnId: Id64String): Promise<boolean>;
     acquireLocks(arg: {
         shared?: Id64Arg;
         exclusive?: Id64Arg;
     }): Promise<void>;
+    // @beta
+    acquireLocksForReinstatingTxn(txnId: Id64String): Promise<boolean>;
     checkExclusiveLock(id: Id64String, type: string, operation: string): void;
     checkSharedLock(id: Id64String, type: string, operation: string): void;
+    // @beta
+    clearTxnLockRecords(txnId: Id64String): void;
     holdsExclusiveLock(id: Id64String): boolean;
+    // @beta
+    holdsNecessaryLocksForReinstatingTxn(txnId: Id64String): boolean;
     holdsSharedLock(id: Id64String): boolean;
     readonly isServerBased: boolean;
     releaseAllLocks(): Promise<void>;
@@ -7359,6 +7377,8 @@ export class TxnManager {
     appCustomConflictHandler?: (args: DbRebaseChangesetConflictArgs) => DbConflictResolution | undefined;
     beginMultiTxnOperation(): DbResult;
     cancelTo(txnId: TxnIdString): IModelStatus;
+    // @beta
+    cancelToTxnAsync(txnId: TxnIdString, args?: ReverseTxnArgs): Promise<void>;
     deleteAllTxns(): void;
     endMultiTxnOperation(): DbResult;
     getChangeTrackingMemoryUsed(): number;
@@ -7447,12 +7467,22 @@ export class TxnManager {
     // @internal (undocumented)
     readonly rebaser: RebaseManager;
     reinstateTxn(): IModelStatus;
+    // @beta
+    reinstateTxnAsync(args?: ReinstateTxnArgs): Promise<void>;
     reportError(error: ValidationError): void;
     restartSession(): void;
     reverseAll(): IModelStatus;
+    // @beta
+    reverseAllTxnsAsync(args?: ReverseTxnArgs): Promise<void>;
     reverseSingleTxn(): IModelStatus;
+    // @beta
+    reverseSingleTxnAsync(args?: ReverseTxnArgs): Promise<void>;
     reverseTo(txnId: TxnIdString): IModelStatus;
+    // @beta
+    reverseToTxnAsync(txnId: TxnIdString, args?: ReverseTxnArgs): Promise<void>;
     reverseTxns(numOperations: number): IModelStatus;
+    // @beta
+    reverseTxnsAsync(numOperations: number, args?: ReverseTxnArgs): Promise<void>;
     // @internal
     touchWatchFile(): void;
     readonly validationErrors: ValidationError[];

common/api/core-common.api.md

@@ -5611,11 +5611,17 @@ export interface IpcAppFunctions {
     // (undocumented)
     reinstateTxn: (key: string) => Promise<IModelStatus>;
     // (undocumented)
+    reinstateTxnAsync: (key: string, args?: ReinstateTxnArgs) => Promise<void>;
+    // (undocumented)
     restartTxnSession: (key: string) => Promise<void>;
     // (undocumented)
     reverseAllTxn: (key: string) => Promise<IModelStatus>;
     // (undocumented)
+    reverseAllTxnsAsync: (key: string, args?: ReverseTxnArgs) => Promise<void>;
+    // (undocumented)
     reverseTxns: (key: string, numOperations: number) => Promise<IModelStatus>;
+    // (undocumented)
+    reverseTxnsAsync: (key: string, numOperations: number, args?: ReverseTxnArgs) => Promise<void>;
     // @deprecated (undocumented)
     saveChanges: (key: string, description?: string) => Promise<void>;
     // (undocumented)
@@ -8042,6 +8048,11 @@ export class RealityModelDisplaySettings {
 // @internal (undocumented)
 export const REGISTRY: unique symbol;
 
+// @beta
+export interface ReinstateTxnArgs {
+    readonly retainLocks?: boolean;
+}
+
 // @public @preview
 export class RelatedElement implements RelatedElementProps {
     constructor(props: RelatedElementProps);
@@ -8641,6 +8652,11 @@ export class ResponseLike implements Response {
     get url(): string;
 }
 
+// @beta
+export interface ReverseTxnArgs {
+    readonly retainLocks?: boolean;
+}
+
 // @public
 export class RgbColor {
     constructor(r: number, g: number, b: number);
@@ -9536,6 +9552,22 @@ export interface SerializedRpcRequest extends SerializedRpcActivity {
     protocolVersion?: number;
 }
 
+// @beta
+export namespace ServerBasedLocksError {
+    const scope = "itwin-ServerBasedLocks";
+    export function isError(error: unknown, key?: Key): error is ITwinError;
+    export type Key =
+    /** The briefcase contains unsaved changes */
+    "has-unsaved-changes" |
+    /** A SQLite error occurred while reading or writing the "locks" database */
+    "lock-database-problem" |
+    /** The specified Txn ID is not known to the TxnManager */
+    "txn-id-not-found" |
+    /** Attempted to abandon locks for a Txn that has not yet been reversed */
+    "txn-not-reversed";
+    export function throwError(key: Key, message: string): never;
+}
+
 // @public (undocumented)
 export class ServerError extends IModelError {
     constructor(errorNumber: number, message: string);

common/api/core-frontend.api.md

@@ -262,6 +262,7 @@ import { RealityDataProvider } from '@itwin/core-common';
 import { RealityDataSourceKey } from '@itwin/core-common';
 import { RealityDataStatus } from '@itwin/core-bentley';
 import { RealityModelDisplaySettings } from '@itwin/core-common';
+import { ReinstateTxnArgs } from '@itwin/core-common';
 import { RelatedElement } from '@itwin/core-common';
 import { RelativePosition } from '@itwin/appui-abstract';
 import { RemoveFunction } from '@itwin/core-common';
@@ -274,6 +275,7 @@ import { RenderTexture } from '@itwin/core-common';
 import { RenderTextureParams } from '@itwin/core-common';
 import { RenderTimelineProps } from '@itwin/core-common';
 import { RenderType } from '@itwin/webgl-compatibility';
+import { ReverseTxnArgs } from '@itwin/core-common';
 import { RgbColor } from '@itwin/core-common';
 import { RgbColorProps } from '@itwin/core-common';
 import { RootSubjectProps } from '@itwin/core-common';
@@ -1892,10 +1894,18 @@ export class BriefcaseTxns extends BriefcaseNotificationHandler implements TxnNo
     // @alpha
     readonly onReverseLocalChangesEnd: BeEvent<(txns: TxnProps[]) => void>;
     reinstateTxn(): Promise<IModelStatus>;
+    // @beta
+    reinstateTxnAsync(args?: ReinstateTxnArgs): Promise<void>;
     restartTxnSession(): Promise<void>;
     reverseAll(): Promise<IModelStatus>;
+    // @beta
+    reverseAllTxnsAsync(args?: ReverseTxnArgs): Promise<void>;
     reverseSingleTxn(): Promise<IModelStatus>;
+    // @beta
+    reverseSingleTxnAsync(args?: ReverseTxnArgs): Promise<void>;
     reverseTxns(numOperations: number): Promise<IModelStatus>;
+    // @beta
+    reverseTxnsAsync(numOperations: number, args?: ReverseTxnArgs): Promise<void>;
 }
 
 // @internal (undocumented)

common/api/summary/core-common.exports.csv

@@ -746,6 +746,7 @@ beta;interface;RealityDataSourceProps
 beta;interface;RealityModelDisplayProps
 beta;class;RealityModelDisplaySettings
 internal;const;REGISTRY
+beta;interface;ReinstateTxnArgs
 public;class;RelatedElement
 preview;class;RelatedElement
 public;interface;RelatedElementProps
@@ -775,6 +776,7 @@ public;interface;RepositoryLinkProps
 preview;interface;RepositoryLinkProps
 public;interface;RequestNewBriefcaseProps
 internal;class;ResponseLike
+beta;interface;ReverseTxnArgs
 public;class;RgbColor
 public;interface;RgbColorProps
 public;type;RgbFactorProps
@@ -863,6 +865,7 @@ preview;enum;SectionType
 public;interface;SerializedRpcActivity
 internal;interface;SerializedRpcOperation
 internal;interface;SerializedRpcRequest
+beta;namespace;ServerBasedLocksError
 public;class;ServerError
 public;class;ServerTimeoutError
 public;interface;SessionProps

common/changes/@itwin/core-backend/kring-release-txn-locks_2026-03-02-06-31.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-backend",
+      "comment": "Added the ability to release locks associated with reversed Txns.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-backend"
+}

common/changes/@itwin/core-common/kring-release-txn-locks_2026-03-16-13-12.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-common",
+      "comment": "Added async versions of Txn reverse and reinstate operations, and added support for abandoning locks when reversing Txns.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-common"
+}

common/changes/@itwin/core-frontend/kring-release-txn-locks_2026-04-09-23-59.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "Added async versions of Txn reverse and reinstate operations, and added support for abandoning locks when reversing Txns.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

core/backend/package.json

@@ -128,4 +128,4 @@
   "nyc": {
     "extends": "./node_modules/@itwin/build-tools/.nycrc"
   }
-}
+}

core/backend/src/BackendHubAccess.ts

@@ -224,12 +224,52 @@ export interface BackendHubAccess {
    */
   acquireLocks: (arg: BriefcaseDbArg, locks: LockMap) => Promise<void>;
 
+  /**
+   * Abandons the specified locks when none of the associated elements have
+   * been or will be modified. Depending on the {@link LockState} specified for the lock,
+   * it may be returned to the {@link LockState.Shared} state or released entirely. It is only
+   * valid to call this method when none of the elements protected by the locks have been edited, or if all edits
+   * have been reversed or abandoned without pushing them.
+   *
+   * The locks are released on the IModelHub, but the changeset associated with the locks is not updated.
+   *
+   * It is an error to specify {@link LockState.Exclusive} for any element, to specify {@link LockState.Shared}
+   * for an element where the Exclusive lock is not currently held, or to include any element for which no lock
+   * is currently held.
+   *
+   * This method is optional, so not all IModelHubs will implement it. If this method is not implemented
+   * explicitly by an IModelHub, it will be implemented implicitly by calling
+   * {@link BackendHubAccess.acquireLocks} with the same locks and passing `changeset.id=""` and
+   * `changeset.index=0` in the first argument to indicate that the lock state should change without updating
+   * the changeset associated with the locks.
+   *
+   * @beta
+   */
+  abandonLocks?: (arg: BriefcaseIdArg, locks: LockMap) => Promise<void>;
+
   /** Get the list of all held locks for a briefcase. This can be very expensive and is currently used only for tests. */
   queryAllLocks: (arg: BriefcaseDbArg) => Promise<LockProps[]>;
 
   /** Release all currently held locks */
   releaseAllLocks: (arg: BriefcaseDbArg) => Promise<void>;
 
+  /**
+   * Abandons all currently held locks when none of the associated elements have been or will be modified.
+   * It is only valid to call this method when none of the elements protected by the locks have been edited,
+   * or if all edits have been reversed or abandoned without pushing them.
+   *
+   * The locks are released on the IModelHub, but the changeset associated with the locks is not updated.
+   *
+   * This method is optional, so not all IModelHubs will implement it. If this method is not implemented
+   * explicitly by an IModelHub, it will be implemented implicitly by calling
+   * {@link BackendHubAccess.releaseAllLocks}, passing `changeset.id=""` and `changeset.index=0` in the
+   * first argument to indicate that the lock state should change without updating the changeset associated
+   * with the locks.
+   *
+   * @beta
+   */
+  abandonAllLocks?: (arg: BriefcaseIdArg) => Promise<void>;
+
   /** Get the iModelId of an iModel by name. Undefined if no iModel with that name exists.  */
   queryIModelByName: (arg: IModelNameArg) => Promise<GuidString | undefined>;
 

core/backend/src/IModelDb.ts

@@ -3521,7 +3521,7 @@ export class BriefcaseDb extends IModelDb {
 
     // attempt to release locks must happen after changes are undone successfully
     Logger.logInfo(loggerCategory, "Releasing locks after discarding changes");
-    await this.locks.releaseAllLocks();
+    await this.locks.abandonAllLocks();
   }
 
   /**

core/backend/src/IpcHost.ts

@@ -12,7 +12,8 @@ import {
   BriefcaseConnectionProps,
   ChangesetIndex, ChangesetIndexAndId, EditingScopeNotifications, getPullChangesIpcChannel, IModelConnectionProps, IModelError, IModelNotFoundResponse, IModelRpcProps,
   ipcAppChannels, IpcAppFunctions, IpcAppNotifications, IpcInvokeReturn, IpcListener, IpcSocketBackend, iTwinChannel,
-  OpenBriefcaseProps, OpenCheckpointArgs, PullChangesOptions, RemoveFunction, SnapshotOpenOptions, StandaloneOpenOptions, TileTreeContentIds, TxnNotifications,
+  OpenBriefcaseProps, OpenCheckpointArgs, PullChangesOptions, ReinstateTxnArgs, RemoveFunction, ReverseTxnArgs, SnapshotOpenOptions,
+  StandaloneOpenOptions, TileTreeContentIds, TxnNotifications,
 } from "@itwin/core-common";
 import { ProgressFunction, ProgressStatus } from "./CheckpointManager";
 import { BriefcaseDb, IModelDb, SnapshotDb, StandaloneDb } from "./IModelDb";
@@ -342,16 +343,31 @@ class IpcAppHandler extends IpcHandler implements IpcAppFunctions {
   }
 
   public async reverseTxns(key: string, numOperations: number): Promise<IModelStatus> {
-    return IModelDb.findByKey(key)[_nativeDb].reverseTxns(numOperations);
+    return BriefcaseDb.findByKey(key).txns.reverseTxns(numOperations);
   }
+
+  public async reverseTxnsAsync(key: string, numOperations: number, args?: ReverseTxnArgs): Promise<void> {
+    return BriefcaseDb.findByKey(key).txns.reverseTxnsAsync(numOperations, args);
+  }
+
   public async reverseAllTxn(key: string): Promise<IModelStatus> {
-    return IModelDb.findByKey(key)[_nativeDb].reverseAll();
+    return BriefcaseDb.findByKey(key).txns.reverseAll();
+  }
+
+  public async reverseAllTxnsAsync(key: string, args?: ReverseTxnArgs): Promise<void> {
+    return BriefcaseDb.findByKey(key).txns.reverseAllTxnsAsync(args);
   }
+
   public async reinstateTxn(key: string): Promise<IModelStatus> {
-    return IModelDb.findByKey(key)[_nativeDb].reinstateTxn();
+    return BriefcaseDb.findByKey(key).txns.reinstateTxn();
+  }
+
+  public async reinstateTxnAsync(key: string, args?: ReinstateTxnArgs): Promise<void> {
+    return BriefcaseDb.findByKey(key).txns.reinstateTxnAsync(args);
   }
+
   public async restartTxnSession(key: string): Promise<void> {
-    return IModelDb.findByKey(key)[_nativeDb].restartTxnSession();
+    return IModelDb.findByKey(key).restartTxnSession();
   }
 
   public async queryConcurrency(pool: "io" | "cpu"): Promise<number> {