@lossless.org/nosqldb 10.10.0 → 10.11.0

package/ts/ts_nosqldb/rust-db-bridge.ts

@@ -1,1066 +0,0 @@
-import { normalizeStoppedStorageRootAlignmentInput, type ILocalNoSqlDbStoppedStorageRootAlignmentInput, type TLocalNoSqlDbStoppedStorageRootAlignmentResult, type ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult } from './storage-root-alignment.js';
-import { normalizeStoppedStorageRootInspectionInput, normalizeStoppedOperationUnknownMethod, type ILocalNoSqlDbStoppedStorageRootInspectionInput, type TLocalNoSqlDbStoppedStorageRootInspection } from './stopped-storage.js';
-import * as plugins from './plugins.js';
-import type { INoSqlDbGetCommittedWritesInput, INoSqlDbCommittedWritesPage } from './committed-writes.js';
-import { normalizeNoSqlDbFileStorageOptions } from './file-storage-options.js';
-import type { TNoSqlDbFileStorageStartup } from './file-storage-startup.js';
-import * as path from 'node:path';
-import * as url from 'node:url';
-import { EventEmitter } from 'node:events';
-import {
-  normalizeNoSqlDbStorageRehearsalInput,
-  type INoSqlDbStorageRehearsalInput,
-  type INoSqlDbStorageRehearsalReceipt,
-  type TNormalizedNoSqlDbStorageRehearsalInput,
-} from './storage-rehearsal.js';
-import {
-  normalizeNoSqlDbAllocationReadAccessGrantError,
-  normalizeNoSqlDbResourceFenceError,
-} from './service-types.js';
-import {
-  normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput,
-  normalizeLocalNoSqlDbOfflineInspectionInput,
-  validateNoSqlDbManagementOperationOptions,
-} from './offline-inspection.js';
-import {
-  normalizeLocalNoSqlDbStoppedStorageRootRelocationInput,
-  type ILocalNoSqlDbStoppedStorageRootRelocationInput,
-  type ILocalNoSqlDbStoppedStorageRootRelocationReceipt,
-} from './storage-root-relocation.js';
-import type {
-  INoSqlDbHealth,
-  INoSqlDbDatabaseTenantInput,
-  INoSqlDbAttestDatabaseTenantInput,
-  INoSqlDbAttestDatabaseTenantResult,
-  INoSqlDbEnsureDatabaseTenantInput,
-  INoSqlDbEnsureDatabaseTenantResult,
-  INoSqlDbAllocateDatabaseTenantInput,
-  INoSqlDbAllocateDatabaseTenantResult,
-  INoSqlDbDeleteDatabaseTenantInput,
-  INoSqlDbRotateDatabaseTenantPasswordInput,
-  INoSqlDbDatabaseTenantDescriptor,
-  INoSqlDbDeleteDatabaseTenantResult,
-  INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
-  INoSqlDbIssueDatabaseAllocationReadAccessGrantResult,
-  INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
-  INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult,
-  INoSqlDbDatabaseExport,
-  INoSqlDbExportDatabaseInput,
-  INoSqlDbExportHeldDatabaseInput,
-  INoSqlDbDatabaseContentDigest,
-  INoSqlDbGetDatabaseContentDigestInput,
-  INoSqlDbImportDatabaseInput,
-  INoSqlDbImportDatabaseResult,
-  INoSqlDbCommitDatabasePublicationInput,
-  INoSqlDbManagementOperationOptions,
-  INoSqlDbDatabaseResourceFenceState,
-  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
-  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
-  ILocalNoSqlDbOfflineStringValueInspection,
-  TLocalNoSqlDbOfflineStringValueInspectionResult,
-  TNoSqlDbCommitDatabasePublicationResult,
-} from './service-types.js';
-
-export type {
-  INoSqlDbHealth,
-  INoSqlDbDatabaseTenantInput,
-  INoSqlDbAttestDatabaseTenantInput,
-  INoSqlDbAttestDatabaseTenantResult,
-  INoSqlDbEnsureDatabaseTenantInput,
-  INoSqlDbEnsureDatabaseTenantResult,
-  INoSqlDbAllocateDatabaseTenantInput,
-  INoSqlDbAllocateDatabaseTenantResult,
-  INoSqlDbDeleteDatabaseTenantInput,
-  INoSqlDbRotateDatabaseTenantPasswordInput,
-  INoSqlDbDatabaseTenantDescriptor,
-  INoSqlDbDeleteDatabaseTenantResult,
-  INoSqlDbDatabaseAllocationReadAccessGrantIdentity,
-  INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
-  INoSqlDbIssueDatabaseAllocationReadAccessGrantResult,
-  INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
-  INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult,
-  INoSqlDbDatabaseExportCollection,
-  INoSqlDbDatabaseExport,
-  INoSqlDbImportDatabaseInput,
-  INoSqlDbImportDatabaseResult,
-  INoSqlDbHeldPublicationReceipt,
-  INoSqlDbCommitDatabasePublicationInput,
-  INoSqlDbManagementOperationOptions,
-  INoSqlDbDatabaseResourceFenceState,
-  ILocalNoSqlDbOfflineInspectionLimits,
-  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits,
-  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
-  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
-  ILocalNoSqlDbOfflineStringValueInspection,
-  TLocalNoSqlDbOfflineStringValueInspectionResult,
-  TNoSqlDbCommitDatabasePublicationResult,
-} from './service-types.js';
-
-/**
- * A single oplog entry returned from the Rust engine.
- */
-export interface IOpLogEntry {
-  seq: number;
-  timestampMs: number;
-  op: 'insert' | 'update' | 'delete';
-  db: string;
-  collection: string;
-  documentId: string;
-  document: Record<string, any> | null;
-  previousDocument: Record<string, any> | null;
-}
-
-/**
- * Aggregate oplog statistics.
- */
-export interface IOpLogStats {
-  currentSeq: number;
-  totalEntries: number;
-  oldestSeq: number;
-  /** Approximate retained bytes: the in-memory oplog entries and the table holding them. */
-  approxBytes: number;
-  entriesByOp: {
-    insert: number;
-    update: number;
-    delete: number;
-  };
-}
-
-/**
- * Result of a getOpLog query.
- */
-export interface IOpLogResult {
-  entries: IOpLogEntry[];
-  currentSeq: number;
-  totalEntries: number;
-}
-
-/**
- * Result of a revertToSeq command.
- */
-export interface IRevertResult {
-  dryRun: boolean;
-  reverted: number;
-  targetSeq?: number;
-  entries?: IOpLogEntry[];
-  errors?: string[];
-}
-
-/**
- * A collection info entry.
- */
-export interface ICollectionInfo {
-  db: string;
-  name: string;
-  count: number;
-}
-
-/**
- * Result of a getDocuments query.
- */
-export interface IDocumentsResult {
-  documents: Record<string, any>[];
-  total: number;
-}
-
-export class NoSqlDbManagementOperationTerminationError extends AggregateError {
-  constructor(operationErrorArg: unknown, terminationErrorArg: unknown) {
-    super(
-      [operationErrorArg, terminationErrorArg],
-      'NoSQLDB management operation failed and Rust engine termination was incomplete',
-      { cause: operationErrorArg },
-    );
-    this.name = 'NoSqlDbManagementOperationTerminationError';
-  }
-}
-
-/**
- * Server metrics.
- */
-export interface INoSqlDbMetrics {
-  databases: number;
-  collections: number;
-  oplogEnabled: boolean;
-  /** Null when the oplog is disabled. */
-  oplogEntries: number | null;
-  /** Null when the oplog is disabled. */
-  oplogCurrentSeq: number | null;
-  sessions: number;
-  activeTransactions: number;
-  authEnabled: boolean;
-  authUsers: number;
-  uptimeSeconds: number;
-}
-
-/**
- * Type-safe command definitions for the RustDb IPC protocol.
- */
-type TOfflinePhysicalNamespaceInspectionCommandParams = {
-  folderPath: string;
-  timeoutMs?: number;
-} & ILocalNoSqlDbOfflinePhysicalNamespaceInspection['limits'];
-
-export const rustDbBridgeStorageRootAlignment = Symbol('storageRootAlignment');
-export const rustDbBridgeStorageRootAlignmentAbort = Symbol('storageRootAlignmentAbort');
-
-type TNoSqlDbCommands = {
-  alignStoppedStorageRoot: { params: ILocalNoSqlDbStoppedStorageRootAlignmentInput & { timeoutMs?: number }; result: TLocalNoSqlDbStoppedStorageRootAlignmentResult };
-  abortStoppedStorageRootAlignment: { params: ILocalNoSqlDbStoppedStorageRootAlignmentInput & { timeoutMs?: number }; result: ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult };
-  inspectStoppedStorageRoot: {
-    params: ILocalNoSqlDbStoppedStorageRootInspectionInput & { timeoutMs?: number };
-    result: TLocalNoSqlDbStoppedStorageRootInspection;
-  };
-  createStoppedStorageRehearsal: {
-    params: { request: TNormalizedNoSqlDbStorageRehearsalInput; timeoutMs: number };
-    result: INoSqlDbStorageRehearsalReceipt;
-  };
-  relocateStoppedStorageRoot: {
-    params: ILocalNoSqlDbStoppedStorageRootRelocationInput & { timeoutMs?: number };
-    result: ILocalNoSqlDbStoppedStorageRootRelocationReceipt;
-  };
-  inspectOfflinePhysicalNamespaces: {
-    params: TOfflinePhysicalNamespaceInspectionCommandParams;
-    result: ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult;
-  };
-  inspectOfflineStringValue: {
-    params: ILocalNoSqlDbOfflineStringValueInspection & { timeoutMs?: number };
-    result: TLocalNoSqlDbOfflineStringValueInspectionResult;
-  };
-  start: { params: { config: INoSqlDbRustConfig; timeoutMs?: number }; result: { connectionUri: string } };
-  stop: { params: Record<string, never>; result: void };
-  getStatus: { params: Record<string, never>; result: { running: boolean } };
-  getHealth: { params: Record<string, never>; result: INoSqlDbHealth };
-  getMetrics: { params: Record<string, never>; result: INoSqlDbMetrics };
-  createDatabaseTenant: {
-    params: INoSqlDbDatabaseTenantInput;
-    result: INoSqlDbDatabaseTenantDescriptor;
-  };
-  allocateDatabaseTenant: {
-    params: INoSqlDbAllocateDatabaseTenantInput;
-    result: INoSqlDbAllocateDatabaseTenantResult;
-  };
-  ensureDatabaseTenant: {
-    params: INoSqlDbEnsureDatabaseTenantInput;
-    result: INoSqlDbEnsureDatabaseTenantResult;
-  };
-  attestDatabaseTenant: {
-    params: INoSqlDbAttestDatabaseTenantInput;
-    result: INoSqlDbAttestDatabaseTenantResult;
-  };
-  deleteDatabaseTenant: {
-    params: INoSqlDbDeleteDatabaseTenantInput;
-    result: INoSqlDbDeleteDatabaseTenantResult;
-  };
-  issueDatabaseAllocationReadAccessGrant: {
-    params: INoSqlDbIssueDatabaseAllocationReadAccessGrantInput;
-    result: INoSqlDbIssueDatabaseAllocationReadAccessGrantResult;
-  };
-  revokeDatabaseAllocationReadAccessGrant: {
-    params: INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput;
-    result: INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult;
-  };
-  rotateDatabaseTenantPassword: {
-    params: INoSqlDbRotateDatabaseTenantPasswordInput;
-    result: INoSqlDbDatabaseTenantDescriptor;
-  };
-  listDatabaseTenants: {
-    params: Record<string, never>;
-    result: { tenants: INoSqlDbDatabaseTenantDescriptor[] };
-  };
-  getDatabaseTenantDescriptor: {
-    params: { databaseName: string; username: string };
-    result: INoSqlDbDatabaseTenantDescriptor;
-  };
-  getDatabaseResourceFenceState: {
-    params: { databaseName: string };
-    result: INoSqlDbDatabaseResourceFenceState | null;
-  };
-  exportDatabase: {
-    params: INoSqlDbExportDatabaseInput;
-    result: INoSqlDbDatabaseExport;
-  };
-  exportHeldDatabase: {
-    params: INoSqlDbExportHeldDatabaseInput;
-    result: INoSqlDbDatabaseExport;
-  };
-  getDatabaseContentDigest: {
-    params: INoSqlDbGetDatabaseContentDigestInput;
-    result: INoSqlDbDatabaseContentDigest;
-  };
-  importDatabase: {
-    params: INoSqlDbImportDatabaseInput & { timeoutMs?: number };
-    result: INoSqlDbImportDatabaseResult;
-  };
-  commitDatabasePublication: {
-    params: INoSqlDbCommitDatabasePublicationInput;
-    result: TNoSqlDbCommitDatabasePublicationResult;
-  };
-  getOpLog: {
-    params: { sinceSeq?: number; limit?: number; db?: string; collection?: string };
-    result: IOpLogResult;
-  };
-  getCommittedWrites: {
-    params: INoSqlDbGetCommittedWritesInput;
-    result: INoSqlDbCommittedWritesPage;
-  };
-  getOpLogStats: { params: Record<string, never>; result: IOpLogStats };
-  revertToSeq: {
-    params: { seq: number; dryRun?: boolean };
-    result: IRevertResult;
-  };
-  getCollections: {
-    params: { db?: string };
-    result: { collections: ICollectionInfo[] };
-  };
-  getDocuments: {
-    params: { db: string; collection: string; limit?: number; skip?: number };
-    result: IDocumentsResult;
-  };
-};
-
-export const rustDbBridgeStorageRootRelocation = Symbol(
-  'nosqldb.internal.storage-root-relocation',
-);
-export const rustDbBridgeStorageRehearsal = Symbol('nosqldb.internal.storage-rehearsal');
-
-/**
- * Configuration sent to the Rust binary on start.
- */
-export interface INoSqlDbQueryOptions {
-  /** Target encoded bytes per in-memory sort run (default: 4 MiB). */
-  sortBufferBytes?: number;
-  /** Shared temporary sort-file budget, including merge output (default: 4 GiB). */
-  maxSortSpillBytes?: number;
-  /** Concurrent sort builders (default: 4). */
-  maxConcurrentSorts?: number;
-}
-
-/**
- * Memory budgets the server's connections share for received requests, and
- * the rate a frame larger than the 8 KiB receive buffer must arrive at while
- * others need the encoded budget. An unset budget is sized from the process's
- * cgroup memory limit, or physical memory. Each set budget must be 64 MiB to
- * 1 TiB.
- */
-export interface INoSqlDbInboundOptions {
-  /** Encoded bytes of received frames until they are decoded (default: a sixteenth of the memory limit, 64–256 MiB). */
-  encodedBytes?: number;
-  /** Memory of decoded requests; a request that needs more is refused (default: a quarter of the memory limit, 64 MiB–1 GiB). */
-  decodedBytes?: number;
-  /** Milliseconds a large frame has, once its encoded budget is held, before its rate counts (default: 10000; 1 to 300000). */
-  frameGraceMs?: number;
-  /** Slowest average rate a large frame may arrive at after its grace while another connection waits for the encoded budget or more than seven eighths of it are held; the slowest frame below it then closes its connection (default: 1048576; at least 1). */
-  minFrameBytesPerSecond?: number;
-}
-
-interface INoSqlDbRustConfig {
-  fileStorageStartup?: TNoSqlDbFileStorageStartup;
-  storageRehearsalId?: string;
-  port?: number;
-  host?: string;
-  socketPath?: string;
-  storage: 'memory' | 'file';
-  storagePath?: string;
-  query?: INoSqlDbQueryOptions;
-  inbound?: INoSqlDbInboundOptions;
-  auth?: {
-    enabled?: boolean;
-    users?: Array<{
-      username: string;
-      password: string;
-      database?: string;
-      roles?: string[];
-    }>;
-    scramIterations?: number;
-  };
-  tls?: {
-    enabled?: boolean;
-    certPath?: string;
-    keyPath?: string;
-    caPath?: string;
-    requireClientCert?: boolean;
-  };
-  oplog?: {
-    enabled?: boolean;
-    maxEntries?: number;
-    maxBytes?: number;
-  };
-}
-
-/**
- * Get the package root directory using import.meta.url.
- * This file is at ts/ts_nosqldb/, so package root is 2 levels up.
- */
-function getPackageRoot(): string {
-  const thisDir = path.dirname(url.fileURLToPath(import.meta.url));
-  return path.resolve(thisDir, '..', '..');
-}
-
-/**
- * Map Node.js process.platform/process.arch to tsrust's friendly name suffix.
- * tsrust names cross-compiled binaries as: rustdb_linux_amd64, rustdb_linux_arm64, etc.
- */
-function getTsrustPlatformSuffix(): string | null {
-  const archMap: Record<string, string> = { x64: 'amd64', arm64: 'arm64' };
-  const osMap: Record<string, string> = { linux: 'linux', darwin: 'macos' };
-  const os = osMap[process.platform];
-  const arch = archMap[process.arch];
-  if (os && arch) {
-    // Static musl runs on both Alpine and glibc hosts without probing host libc.
-    return `${os}_${arch}${os === 'linux' ? '_musl' : ''}`;
-  }
-  return null;
-}
-
-/**
- * Build local search paths for the Rust binary, including dist_rust/ candidates
- * (built by tsrust) and local development build paths.
- */
-function buildLocalPaths(): string[] {
-  const packageRoot = getPackageRoot();
-  const suffix = getTsrustPlatformSuffix();
-  const paths: string[] = [];
-
-  // dist_rust/ candidates (tsrust cross-compiled output)
-  if (suffix) {
-    paths.push(path.join(packageRoot, 'dist_rust', `rustdb_${suffix}`));
-  }
-  paths.push(path.join(packageRoot, 'dist_rust', 'rustdb'));
-
-  // Local dev build paths
-  paths.push(path.resolve(process.cwd(), 'rust', 'target', 'release', 'rustdb'));
-  paths.push(path.resolve(process.cwd(), 'rust', 'target', 'debug', 'rustdb'));
-
-  return paths;
-}
-export function getRustDbAllocatorEnv(
-  environment: NodeJS.ProcessEnv = process.env,
-): Record<string, string> {
-  return {
-    MIMALLOC_ARENA_EAGER_COMMIT: environment.MIMALLOC_ARENA_EAGER_COMMIT ?? '0',
-    MIMALLOC_ALLOW_LARGE_OS_PAGES: environment.MIMALLOC_ALLOW_LARGE_OS_PAGES ?? '0',
-  };
-}
-
-export interface IRustDbBridgeOptions {
-  /** Exact engine executable, validated by Smartrust without discovery fallback or permission changes. */
-  binaryPath?: string;
-}
-
-/**
- * Bridge between TypeScript NoSqlDbServer and the Rust binary.
- * Wraps @push.rocks/smartrust's RustBridge with type-safe command definitions.
- */
-export class RustDbBridge extends EventEmitter {
-  private bridge: plugins.smartrust.RustBridge<TNoSqlDbCommands>;
-
-  /**
-   * Operating-system process id of the spawned Rust engine while it runs as a
-   * child process of this Node.js process. Undefined before spawn, after
-   * termination, or when the bridge is connected to an external process.
-   */
-  public get processId(): number | undefined {
-    const transport = (this.bridge as unknown as {
-      transport?: { childProcess?: { pid?: number } | null };
-    }).transport;
-    return transport?.childProcess?.pid;
-  }
-  private terminationConfirmed = true;
-  private terminationPromise: Promise<void> | undefined;
-  private terminationFailure: unknown;
-
-  constructor(options: IRustDbBridgeOptions = {}) {
-    super();
-
-    this.bridge = new plugins.smartrust.RustBridge<TNoSqlDbCommands>({
-      binaryName: 'rustdb',
-      binaryPath: options.binaryPath,
-      envVarName: 'NOSQLDB_RUST_BINARY',
-      platformPackagePrefix: '@lossless.org/nosqldb',
-      localPaths: buildLocalPaths(),
-      maxPayloadSize: 100 * 1024 * 1024, // database exports/imports can be larger than command replies
-      env: getRustDbAllocatorEnv(),
-    });
-
-    // Forward events from the inner bridge
-    this.bridge.on('exit', (code: number | null, signal: string | null) => {
-      this.terminationConfirmed = true;
-      this.emit('exit', code, signal);
-    });
-  }
-
-  /**
-   * Spawn the Rust binary in management mode.
-   * Returns true if the binary was found and spawned successfully.
-   */
-  public async spawn(optionsArg?: INoSqlDbManagementOperationOptions): Promise<boolean> {
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    if (optionsArg?.signal?.aborted) {
-      throw new plugins.smartrust.RustBridgeRequestError(
-        'NoSQLDB Rust sidecar spawn was aborted before it started',
-        {
-          code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
-          method: 'spawn',
-          cause: optionsArg.signal.reason,
-        },
-      );
-    }
-
-    this.terminationConfirmed = false;
-    this.terminationFailure = undefined;
-    const spawnPromise = this.bridge.spawn();
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-    let abortHandler: (() => void) | undefined;
-    const cancellationPromise = new Promise<never>((_resolveArg, rejectArg) => {
-      if (optionsArg?.timeoutMs !== undefined) {
-        timeout = setTimeout(() => {
-          rejectArg(new plugins.smartrust.RustBridgeRequestError(
-            `NoSQLDB Rust sidecar spawn timed out after ${optionsArg.timeoutMs}ms`,
-            {
-              code: 'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
-              method: 'spawn',
-            },
-          ));
-        }, optionsArg.timeoutMs);
-      }
-      if (optionsArg?.signal) {
-        abortHandler = () => {
-          rejectArg(new plugins.smartrust.RustBridgeRequestError(
-            'NoSQLDB Rust sidecar spawn was aborted',
-            {
-              code: 'ERR_RUST_BRIDGE_REQUEST_ABORTED',
-              method: 'spawn',
-              cause: optionsArg.signal!.reason,
-            },
-          ));
-        };
-        optionsArg.signal.addEventListener('abort', abortHandler, { once: true });
-      }
-    });
-
-    try {
-      const spawned = await Promise.race([spawnPromise, cancellationPromise]);
-      if (!spawned) {
-        await this.terminate({ gracePeriodMs: 0 });
-      }
-      return spawned;
-    } catch (error) {
-      try {
-        await this.terminate({ gracePeriodMs: 0 });
-      } catch (terminationError) {
-        throw new NoSqlDbManagementOperationTerminationError(error, terminationError);
-      }
-      throw error;
-    } finally {
-      if (timeout) clearTimeout(timeout);
-      if (abortHandler && optionsArg?.signal) {
-        optionsArg.signal.removeEventListener('abort', abortHandler);
-      }
-    }
-  }
-
-  /**
-   * Kill the Rust process and clean up.
-   */
-  public kill(): void {
-    this.bridge.kill();
-  }
-
-  /**
-   * Confirm that the Rust process has exited and all bridge resources are released.
-   */
-  public terminate(
-    optionsArg?: plugins.smartrust.IRustBridgeTerminateOptions,
-  ): Promise<void> {
-    if (this.terminationPromise) {
-      return this.terminationPromise;
-    }
-
-    const terminationPromise = this.bridge.terminate(optionsArg).then(
-      () => {
-        this.terminationConfirmed = true;
-        this.terminationFailure = undefined;
-      },
-      (errorArg: unknown) => {
-        this.terminationFailure = errorArg;
-        throw errorArg;
-      },
-    );
-    this.terminationPromise = terminationPromise;
-    void terminationPromise.then(
-      () => {
-        if (this.terminationPromise === terminationPromise) {
-          this.terminationPromise = undefined;
-        }
-      },
-      () => {
-        if (this.terminationPromise === terminationPromise) {
-          this.terminationPromise = undefined;
-        }
-      },
-    );
-    return terminationPromise;
-  }
-
-  /**
-   * Whether the bridge is currently running.
-   */
-  public get running(): boolean {
-    return this.bridge.running;
-  }
-
-  public get ownershipReleased(): boolean {
-    return this.terminationConfirmed;
-  }
-
-  private async awaitManagementOperationTermination(errorArg: unknown) {
-    const cancellationRequiresTermination =
-      errorArg instanceof plugins.smartrust.RustBridgeRequestError
-      && [
-        'ERR_RUST_BRIDGE_REQUEST_ABORTED',
-        'ERR_RUST_BRIDGE_REQUEST_TIMEOUT',
-      ].includes(errorArg.code);
-    let terminationPromise = this.terminationPromise;
-    if (cancellationRequiresTermination && !terminationPromise) {
-      terminationPromise = this.terminate({ gracePeriodMs: 0 });
-    }
-
-    if (!terminationPromise) {
-      if (!this.terminationConfirmed && this.terminationFailure !== undefined) {
-        throw new NoSqlDbManagementOperationTerminationError(
-          errorArg,
-          this.terminationFailure,
-        );
-      }
-      return;
-    }
-
-    try {
-      await terminationPromise;
-    } catch (terminationError) {
-      throw new NoSqlDbManagementOperationTerminationError(
-        errorArg,
-        terminationError,
-      );
-    }
-  }
-
-  // --- Convenience methods for each management command ---
-
-  public async [rustDbBridgeStorageRehearsal](inputArg: INoSqlDbStorageRehearsalInput,
-    optionsArg: INoSqlDbManagementOperationOptions & { timeoutMs: number }): Promise<INoSqlDbStorageRehearsalReceipt> {
-    const request = normalizeNoSqlDbStorageRehearsalInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand('createStoppedStorageRehearsal',
-        { request, timeoutMs: optionsArg.timeoutMs }, optionsArg) as INoSqlDbStorageRehearsalReceipt;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, 'createStoppedStorageRehearsal');
-    }
-  }
-
-  public async [rustDbBridgeStorageRootRelocation](
-    inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<ILocalNoSqlDbStoppedStorageRootRelocationReceipt> {
-    const input = normalizeLocalNoSqlDbStoppedStorageRootRelocationInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand(
-        'relocateStoppedStorageRoot',
-        { ...input, timeoutMs: optionsArg?.timeoutMs },
-        optionsArg,
-      ) as ILocalNoSqlDbStoppedStorageRootRelocationReceipt;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, 'relocateStoppedStorageRoot');
-    }
-  }
-
-  public async [rustDbBridgeStorageRootAlignment](inputArg: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
-    optionsArg?: INoSqlDbManagementOperationOptions): Promise<TLocalNoSqlDbStoppedStorageRootAlignmentResult> {
-    return this.stoppedAlignmentCommand('alignStoppedStorageRoot', inputArg, optionsArg) as Promise<TLocalNoSqlDbStoppedStorageRootAlignmentResult>;
-  }
-  public async [rustDbBridgeStorageRootAlignmentAbort](inputArg: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
-    optionsArg?: INoSqlDbManagementOperationOptions): Promise<ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult> {
-    return this.stoppedAlignmentCommand('abortStoppedStorageRootAlignment', inputArg, optionsArg) as Promise<ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult>;
-  }
-  private async stoppedAlignmentCommand(method: 'alignStoppedStorageRoot' | 'abortStoppedStorageRootAlignment',
-    inputArg: ILocalNoSqlDbStoppedStorageRootAlignmentInput, optionsArg?: INoSqlDbManagementOperationOptions) {
-    const input = normalizeStoppedStorageRootAlignmentInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand(method, { ...input, timeoutMs: optionsArg?.timeoutMs }, optionsArg);
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, method);
-    }
-  }
-
-  public async inspectStoppedStorageRoot(
-    inputArg: ILocalNoSqlDbStoppedStorageRootInspectionInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<TLocalNoSqlDbStoppedStorageRootInspection> {
-    const input = normalizeStoppedStorageRootInspectionInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand('inspectStoppedStorageRoot',
-        { ...input, timeoutMs: optionsArg?.timeoutMs }, optionsArg) as TLocalNoSqlDbStoppedStorageRootInspection;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, 'inspectStoppedStorageRoot');
-    }
-  }
-
-  public async inspectOfflinePhysicalNamespaces(
-    inputArg: ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult> {
-    const input = normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    const params: TOfflinePhysicalNamespaceInspectionCommandParams = {
-      folderPath: input.folderPath,
-      ...input.limits,
-      timeoutMs: optionsArg?.timeoutMs,
-    };
-    try {
-      return await this.bridge.sendCommand(
-        'inspectOfflinePhysicalNamespaces',
-        params,
-        optionsArg,
-      ) as ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, 'inspectOfflinePhysicalNamespaces');
-    }
-  }
-
-  public async inspectOfflineStringValue(
-    inputArg: ILocalNoSqlDbOfflineStringValueInspection,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<TLocalNoSqlDbOfflineStringValueInspectionResult> {
-    const input = normalizeLocalNoSqlDbOfflineInspectionInput(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand(
-        'inspectOfflineStringValue',
-        { ...input, timeoutMs: optionsArg?.timeoutMs },
-        optionsArg,
-      ) as TLocalNoSqlDbOfflineStringValueInspectionResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeStoppedOperationUnknownMethod(error, 'inspectOfflineStringValue');
-    }
-  }
-
-  public async startDb(
-    config: INoSqlDbRustConfig,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<{ connectionUri: string }> {
-    normalizeNoSqlDbFileStorageOptions(config);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
-    try {
-      return await this.bridge.sendCommand(
-        'start',
-        { config, timeoutMs: optionsArg?.timeoutMs },
-        optionsArg,
-      ) as { connectionUri: string };
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw error;
-    }
-  }
-
-  public async stopDb(): Promise<void> {
-    await this.bridge.sendCommand('stop', {} as Record<string, never>);
-  }
-
-  public async getStatus(): Promise<{ running: boolean }> {
-    return await this.bridge.sendCommand('getStatus', {} as Record<string, never>) as { running: boolean };
-  }
-
-  public async getMetrics(): Promise<INoSqlDbMetrics> {
-    return this.bridge.sendCommand('getMetrics', {} as Record<string, never>) as Promise<INoSqlDbMetrics>;
-  }
-
-  public async getHealth(
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbHealth> {
-    try {
-      return await this.bridge.sendCommand(
-        'getHealth',
-        {} as Record<string, never>,
-        optionsArg,
-      ) as INoSqlDbHealth;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw error;
-    }
-  }
-
-  public async createDatabaseTenant(
-    params: INoSqlDbDatabaseTenantInput,
-  ): Promise<INoSqlDbDatabaseTenantDescriptor> {
-    try {
-      return await this.bridge.sendCommand('createDatabaseTenant', params) as INoSqlDbDatabaseTenantDescriptor;
-    } catch (error) {
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async ensureDatabaseTenant(
-    params: INoSqlDbEnsureDatabaseTenantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbEnsureDatabaseTenantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'ensureDatabaseTenant',
-        params,
-        optionsArg,
-      ) as INoSqlDbEnsureDatabaseTenantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async attestDatabaseTenant(
-    params: INoSqlDbAttestDatabaseTenantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbAttestDatabaseTenantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'attestDatabaseTenant',
-        params,
-        optionsArg,
-      ) as INoSqlDbAttestDatabaseTenantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async allocateDatabaseTenant(
-    params: INoSqlDbAllocateDatabaseTenantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbAllocateDatabaseTenantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'allocateDatabaseTenant',
-        params,
-        optionsArg,
-      ) as INoSqlDbAllocateDatabaseTenantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async deleteDatabaseTenant(
-    params: INoSqlDbDeleteDatabaseTenantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbDeleteDatabaseTenantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'deleteDatabaseTenant',
-        params,
-        optionsArg,
-      ) as INoSqlDbDeleteDatabaseTenantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async issueDatabaseAllocationReadAccessGrant(
-    params: INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbIssueDatabaseAllocationReadAccessGrantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'issueDatabaseAllocationReadAccessGrant',
-        params,
-        optionsArg,
-      ) as INoSqlDbIssueDatabaseAllocationReadAccessGrantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbAllocationReadAccessGrantError(
-        normalizeNoSqlDbResourceFenceError(error),
-        error instanceof plugins.smartrust.RustBridgeRequestError
-          ? error.responseErrorCode
-          : undefined,
-      );
-    }
-  }
-
-  public async revokeDatabaseAllocationReadAccessGrant(
-    params: INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'revokeDatabaseAllocationReadAccessGrant',
-        params,
-        optionsArg,
-      ) as INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbAllocationReadAccessGrantError(
-        normalizeNoSqlDbResourceFenceError(error),
-        error instanceof plugins.smartrust.RustBridgeRequestError
-          ? error.responseErrorCode
-          : undefined,
-      );
-    }
-  }
-
-  public async rotateDatabaseTenantPassword(
-    params: INoSqlDbRotateDatabaseTenantPasswordInput,
-  ): Promise<INoSqlDbDatabaseTenantDescriptor> {
-    return this.bridge.sendCommand('rotateDatabaseTenantPassword', params) as Promise<INoSqlDbDatabaseTenantDescriptor>;
-  }
-
-  public async listDatabaseTenants(): Promise<INoSqlDbDatabaseTenantDescriptor[]> {
-    const result = await this.bridge.sendCommand('listDatabaseTenants', {} as Record<string, never>) as { tenants: INoSqlDbDatabaseTenantDescriptor[] };
-    return result.tenants;
-  }
-
-  public async getDatabaseTenantDescriptor(params: {
-    databaseName: string;
-    username: string;
-  }): Promise<INoSqlDbDatabaseTenantDescriptor> {
-    return this.bridge.sendCommand('getDatabaseTenantDescriptor', params) as Promise<INoSqlDbDatabaseTenantDescriptor>;
-  }
-
-  public async getDatabaseResourceFenceState(
-    params: { databaseName: string },
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbDatabaseResourceFenceState | null> {
-    try {
-      return await this.bridge.sendCommand(
-        'getDatabaseResourceFenceState',
-        params,
-        optionsArg,
-      ) as INoSqlDbDatabaseResourceFenceState | null;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async exportDatabase(
-    params: INoSqlDbExportDatabaseInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbDatabaseExport> {
-    try {
-      return await this.bridge.sendCommand(
-        'exportDatabase',
-        params,
-        optionsArg,
-      ) as INoSqlDbDatabaseExport;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw error;
-    }
-  }
-
-  public async exportHeldDatabase(
-    params: INoSqlDbExportHeldDatabaseInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbDatabaseExport> {
-    try {
-      return await this.bridge.sendCommand(
-        'exportHeldDatabase',
-        params,
-        optionsArg,
-      ) as INoSqlDbDatabaseExport;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async getDatabaseContentDigest(
-    params: INoSqlDbGetDatabaseContentDigestInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbDatabaseContentDigest> {
-    try {
-      return await this.bridge.sendCommand(
-        'getDatabaseContentDigest',
-        params,
-        optionsArg,
-      ) as INoSqlDbDatabaseContentDigest;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw error;
-    }
-  }
-
-  public async importDatabase(
-    params: INoSqlDbImportDatabaseInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<INoSqlDbImportDatabaseResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'importDatabase',
-        { ...params, timeoutMs: optionsArg?.timeoutMs },
-        optionsArg,
-      ) as INoSqlDbImportDatabaseResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async commitDatabasePublication(
-    params: INoSqlDbCommitDatabasePublicationInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
-  ): Promise<TNoSqlDbCommitDatabasePublicationResult> {
-    try {
-      return await this.bridge.sendCommand(
-        'commitDatabasePublication',
-        params,
-        optionsArg,
-      ) as TNoSqlDbCommitDatabasePublicationResult;
-    } catch (error) {
-      await this.awaitManagementOperationTermination(error);
-      throw normalizeNoSqlDbResourceFenceError(error);
-    }
-  }
-
-  public async getOpLog(params: {
-    sinceSeq?: number;
-    limit?: number;
-    db?: string;
-    collection?: string;
-  } = {}): Promise<IOpLogResult> {
-    return this.bridge.sendCommand('getOpLog', params) as Promise<IOpLogResult>;
-  }
-
-  public async getCommittedWrites(params: INoSqlDbGetCommittedWritesInput): Promise<INoSqlDbCommittedWritesPage> {
-    return this.bridge.sendCommand('getCommittedWrites', params);
-  }
-
-  public async getOpLogStats(): Promise<IOpLogStats> {
-    return this.bridge.sendCommand('getOpLogStats', {} as Record<string, never>) as Promise<IOpLogStats>;
-  }
-
-  public async revertToSeq(seq: number, dryRun = false): Promise<IRevertResult> {
-    return this.bridge.sendCommand('revertToSeq', { seq, dryRun }) as Promise<IRevertResult>;
-  }
-
-  public async getCollections(db?: string): Promise<ICollectionInfo[]> {
-    const result = await this.bridge.sendCommand('getCollections', db ? { db } : {}) as { collections: ICollectionInfo[] };
-    return result.collections;
-  }
-
-  public async getDocuments(
-    db: string,
-    collection: string,
-    limit = 50,
-    skip = 0,
-  ): Promise<IDocumentsResult> {
-    return this.bridge.sendCommand('getDocuments', { db, collection, limit, skip }) as Promise<IDocumentsResult>;
-  }
-}