@lossless.org/nosqldb 10.11.0 → 11.0.0

package/ts/ts_nosqldb/server/classes.nosqldbserver.ts

@@ -0,0 +1,874 @@
+import {
+  RustDbBridge,
+  NoSqlDbEngineExitError,
+  NoSqlDbManagementOperationTerminationError,
+  attachNoSqlDbEngineStderrTail,
+} from '../rust-db-bridge.js';
+import { validateNoSqlDbManagementOperationOptions } from '../offline-inspection.js';
+import type { INoSqlDbGetCommittedWritesInput, INoSqlDbCommittedWritesPage } from '../committed-writes.js';
+import { validateNoSqlDbStorageRehearsalStartup } from '../storage-rehearsal.js';
+import { assertNoLocalNoSqlDbStorageRootRelocationWorkspace } from '../storage-root-relocation.js';
+import {
+  type TNoSqlDbFileStorageStartup,
+} from '../file-storage-startup.js';
+import {
+  normalizeNoSqlDbFileStorageOptions,
+} from '../file-storage-options.js';
+import type {
+  IOpLogEntry,
+  IOpLogResult,
+  IOpLogStats,
+  IRevertResult,
+  ICollectionInfo,
+  IDocumentsResult,
+  INoSqlDbMetrics,
+  INoSqlDbQueryOptions,
+  INoSqlDbInboundOptions,
+} from '../rust-db-bridge.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,
+  TNoSqlDbCommitDatabasePublicationResult,
+} from '../service-types.js';
+
+/**
+ * Server configuration options
+ */
+export interface INoSqlDbServerOptions {
+  /** Exact engine executable. Invalid explicit paths reject without chmod or discovery fallback. Omit for normal discovery. */
+  binaryPath?: string;
+  /** Exact rehearsal operation ID. Requires authenticated current-format-only file storage and an explicit private Unix socket. Never promotes a rehearsal. */
+  storageRehearsalId?: string;
+  /** Default: current-format-only. existing-only also requires initialized storage and refuses fresh creation. */
+  fileStorageStartup?: TNoSqlDbFileStorageStartup;
+  /** Port to listen on (default: 27017, 0 requests an OS-assigned port) - ignored if socketPath is set */
+  port?: number;
+  /** Host to bind to (default: 127.0.0.1) - ignored if socketPath is set */
+  host?: string;
+  /** Unix socket path - if set, server listens on socket instead of TCP */
+  socketPath?: string;
+  /** Storage type: 'memory' or 'file' (default: 'memory') */
+  storage?: 'memory' | 'file';
+  /** Path for file storage (required if storage is 'file') */
+  storagePath?: string;
+  /** Authentication configuration. Disabled by default. */
+  auth?: INoSqlDbAuthOptions;
+  /** TLS transport configuration for TCP listeners. Disabled by default. */
+  tls?: INoSqlDbTlsOptions;
+  /** In-memory oplog: whether it is kept, and its retention limits (defaults: enabled, 10000 entries / 8 MiB). */
+  oplog?: INoSqlDbOplogOptions;
+  /** Memory, temporary storage, and concurrency admission for large sorts. */
+  query?: INoSqlDbQueryOptions;
+  /** Memory budgets for received requests (default: sized from the memory limit). */
+  inbound?: INoSqlDbInboundOptions;
+  /**
+   * The store's memory budget in bytes, which its node cache and write buffer
+   * share: 4 MiB to 1 TiB. The engine refuses a start with a value outside
+   * that range and never clamps it. Unset, the budget is computed from the
+   * memory the process may use.
+   */
+  storageBudgetBytes?: number;
+  /**
+   * Receives every line the engine writes to its standard error, in order and
+   * without its line break. Without it, nothing is written to the host
+   * process's standard error. Start failures and unexpected engine exits
+   * carry the engine's last lines either way, in `engineStderrTail`. Each
+   * call runs in its own microtask; an exception it throws is not caught and
+   * reaches the process as an uncaught exception.
+   */
+  engineLog?: (line: string) => void;
+  /**
+   * Called once for each unexpected engine exit: an exit with a non-zero
+   * status or by a signal while the server runs and no stop is in progress.
+   * An exit with status 0, which the engine makes after a graceful shutdown
+   * it was signalled to make, is not reported; the server counts as stopped
+   * either way. The call runs in a microtask after the server has recorded the
+   * exit. An exception it throws is not caught and reaches the process as an
+   * uncaught exception.
+   */
+  onEngineExit?: (error: NoSqlDbEngineExitError) => void;
+}
+
+export interface INoSqlDbOplogOptions {
+  /** Keep the oplog (default: true). When false, writes prepare no history, and getOpLog, getOpLogStats and revertToSeq reject with "oplog is disabled". */
+  enabled?: boolean;
+  /** Maximum number of retained oplog entries (default: 10000). */
+  maxEntries?: number;
+  /** Maximum approximate retained bytes, the entry table included (default: 8 MiB). Oldest entries are evicted first; reverts cannot reach past evicted entries. */
+  maxBytes?: number;
+}
+
+export interface INoSqlDbAuthOptions {
+  enabled?: boolean;
+  users?: INoSqlDbAuthUser[];
+  scramIterations?: number;
+}
+
+export interface INoSqlDbAuthUser {
+  username: string;
+  password: string;
+  database?: string;
+  roles?: string[];
+}
+
+export interface INoSqlDbTlsOptions {
+  enabled?: boolean;
+  certPath?: string;
+  keyPath?: string;
+  caPath?: string;
+  requireClientCert?: boolean;
+}
+
+/**
+ * How `stop()` ended the engine. A stop is clean exactly when a stop request
+ * was sent and acknowledged, the server neither signalled nor killed the
+ * engine, and the engine exited with code 0 and no signal; `clean` says so.
+ */
+export interface INoSqlDbServerStopResult {
+  /** Whether a stop request was sent to a running engine. */
+  stopRequestSent: boolean;
+  /** Whether the engine acknowledged that request. */
+  stopAcknowledged: boolean;
+  /**
+   * Whether the server had to signal or kill the engine to end it: the engine
+   * had not exited by itself within `noSqlDbServerStopGraceMs` of an
+   * acknowledged request, or no request was acknowledged while it ran.
+   */
+  forcedByServer: boolean;
+  /** The engine's exit code as its process exit reported it, or null. */
+  exitCode: number | null;
+  /** The signal that ended the engine as its process exit reported it, or null. */
+  exitSignal: string | null;
+  /** Whether the stop was clean, as defined above. */
+  clean: boolean;
+}
+
+/**
+ * How long `stop()` waits, after the engine has acknowledged the stop request
+ * and its management input is closed, for the engine to exit by itself before
+ * the server ends it.
+ */
+export const noSqlDbServerStopGraceMs = 10_000;
+
+/** One stop's result, frozen, as all of its callers share it. */
+const stopResult = (
+  stopRequestSent: boolean,
+  stopAcknowledged: boolean,
+  forcedByServer: boolean,
+  exit: { code: number | null; signal: string | null } | null,
+): INoSqlDbServerStopResult => {
+  const exitCode = exit?.code ?? null;
+  const exitSignal = exit?.signal ?? null;
+  return Object.freeze({
+    stopRequestSent,
+    stopAcknowledged,
+    forcedByServer,
+    exitCode,
+    exitSignal,
+    clean: stopRequestSent && stopAcknowledged && !forcedByServer && exitCode === 0 && exitSignal === null,
+  });
+};
+
+/** The result of a stop when no engine runs: no request was sent. */
+export const noStopRequestResult = stopResult(false, false, false, null);
+
+/**
+ * NoSqlDbServer - Wire protocol compatible database server backed by Rust
+ *
+ * This server implements the wire protocol to allow official drivers to
+ * connect and perform operations. The core engine runs as a Rust sidecar
+ * binary managed via @push.rocks/smartrust IPC.
+ *
+ * @example
+ * ```typescript
+ * import { NoSqlDbServer } from '@lossless.org/nosqldb';
+ * import { MongoClient } from 'mongodb';
+ *
+ * const server = new NoSqlDbServer({ port: 27017 });
+ * await server.start();
+ *
+ * const client = new MongoClient(server.getConnectionUri());
+ * await client.connect();
+ * ```
+ */
+export class NoSqlDbServer {
+  private options: INoSqlDbServerOptions;
+  private bridge: RustDbBridge;
+  private bridgeOwned = false;
+  private startInProgress = false;
+  private startCompletionPromise: Promise<void> | null = null;
+  private stopCompletionPromise: Promise<INoSqlDbServerStopResult> | null = null;
+  private isRunning = false;
+  private resolvedConnectionUri = '';
+  private resolvedPort: number | undefined;
+
+  constructor(options: INoSqlDbServerOptions = {}) {
+    validateNoSqlDbStorageRehearsalStartup(options);
+    const fileStorage = normalizeNoSqlDbFileStorageOptions(options);
+    this.options = {
+      binaryPath: options.binaryPath,
+      storageRehearsalId: options.storageRehearsalId,
+      ...fileStorage,
+      port: options.port ?? 27017,
+      host: options.host ?? '127.0.0.1',
+      socketPath: options.socketPath,
+      storage: options.storage ?? 'memory',
+      storagePath: options.storagePath ?? './data',
+      auth: options.auth,
+      tls: options.tls,
+      oplog: options.oplog,
+      query: options.query,
+      inbound: options.inbound,
+      storageBudgetBytes: options.storageBudgetBytes,
+      engineLog: options.engineLog,
+      onEngineExit: options.onEngineExit,
+    };
+    this.bridge = new RustDbBridge({ binaryPath: this.options.binaryPath, engineLog: this.options.engineLog });
+    this.bridge.on('exit', (code: number | null, signal: string | null) => {
+      // A stop keeps the running state until it has confirmed the bridge's
+      // termination, also when the engine exits by itself first.
+      if (this.stopCompletionPromise) return;
+      const exitedUnexpectedly = this.isRunning
+        && (code !== 0 || signal !== null);
+      this.isRunning = false;
+      this.resolvedConnectionUri = '';
+      this.resolvedPort = undefined;
+      if (exitedUnexpectedly) {
+        const onEngineExit = this.options.onEngineExit;
+        const exit = new NoSqlDbEngineExitError(code, signal, this.bridge.engineStderrTail);
+        // Outside the bridge's exit event, so a throwing callback cannot
+        // interrupt the bridge's own exit handling.
+        if (onEngineExit) queueMicrotask(() => onEngineExit(exit));
+      }
+    });
+  }
+
+  /**
+   * Start the server. A rejection carries `engineStderrTail`: the last
+   * standard-error lines of the engine this start spawned, or none.
+   */
+  async start(optionsArg?: INoSqlDbManagementOperationOptions): Promise<void> {
+    const attempt = { engineSpawned: false };
+    try {
+      await this.startAttempt(optionsArg, attempt);
+    } catch (error) {
+      // Read after the attempt's cleanup termination, once the engine's last
+      // lines have arrived.
+      attachNoSqlDbEngineStderrTail(error, attempt.engineSpawned ? this.bridge.engineStderrTail : []);
+      throw error;
+    }
+  }
+
+  private async startAttempt(
+    optionsArg: INoSqlDbManagementOperationOptions | undefined,
+    attempt: { engineSpawned: boolean },
+  ): Promise<void> {
+    validateNoSqlDbManagementOperationOptions(optionsArg);
+    optionsArg?.signal?.throwIfAborted();
+    if (this.isRunning || this.startInProgress || this.bridgeOwned || this.stopCompletionPromise) {
+      throw new Error('Server is already running or still owns a Rust bridge');
+    }
+
+    const startupStartedAt = Date.now();
+    const startupDeadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : startupStartedAt + optionsArg.timeoutMs;
+    const timeoutError = new DOMException(
+      optionsArg?.timeoutMs === undefined
+        ? 'NoSQLDB startup timed out'
+        : `NoSQLDB startup timed out after ${optionsArg.timeoutMs}ms`,
+      'TimeoutError',
+    );
+    const startupAbortController = new AbortController();
+    let startupTimeout: ReturnType<typeof setTimeout> | undefined;
+    let externalAbortHandler: (() => void) | undefined;
+    if (optionsArg?.signal) {
+      externalAbortHandler = () => {
+        startupAbortController.abort(optionsArg.signal!.reason);
+      };
+      optionsArg.signal.addEventListener('abort', externalAbortHandler, { once: true });
+    }
+    if (optionsArg?.timeoutMs !== undefined) {
+      startupTimeout = setTimeout(() => {
+        startupAbortController.abort(timeoutError);
+      }, optionsArg.timeoutMs);
+    }
+    const checkpoint = () => {
+      if (
+        startupDeadline !== undefined
+        && Date.now() >= startupDeadline
+        && !startupAbortController.signal.aborted
+      ) {
+        startupAbortController.abort(timeoutError);
+      }
+      startupAbortController.signal.throwIfAborted();
+    };
+    const getBridgeOperationOptions = (): INoSqlDbManagementOperationOptions | undefined => {
+      checkpoint();
+      const remainingTimeoutMs = startupDeadline === undefined
+        ? undefined
+        : startupDeadline - Date.now();
+      if (remainingTimeoutMs !== undefined && remainingTimeoutMs <= 0) {
+        startupAbortController.abort(timeoutError);
+        checkpoint();
+      }
+      if (!optionsArg?.signal && remainingTimeoutMs === undefined) return undefined;
+      return {
+        ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+        ...(remainingTimeoutMs === undefined ? {} : { timeoutMs: remainingTimeoutMs }),
+      };
+    };
+
+    this.startInProgress = true;
+    let resolveStartCompletion!: () => void;
+    const startCompletionPromise = new Promise<void>((resolveArg) => {
+      resolveStartCompletion = resolveArg;
+    });
+    this.startCompletionPromise = startCompletionPromise;
+    try {
+      checkpoint();
+      // Relocation workspace admission is read-only; the native owner alone
+      // classifies and initializes storage after acquiring its root lease.
+      if (this.options.storage === 'file' && this.options.storagePath) {
+        await assertNoLocalNoSqlDbStorageRootRelocationWorkspace(this.options.storagePath);
+        checkpoint();
+      }
+
+      // Ownership starts before spawn because a rejected spawn can still have
+      // created a child whose termination must be confirmed.
+      this.bridgeOwned = true;
+      const spawnOptions = getBridgeOperationOptions();
+      attempt.engineSpawned = true;
+      const spawned = await this.bridge.spawn(spawnOptions);
+      checkpoint();
+      if (!spawned) {
+        // The bridge states what it knows: that the engine at its binaryPath did not report ready, or, without one, both meanings.
+        throw new Error(this.bridge.spawnFailureMessage ?? 'the nosqldb engine did not start: spawn() returned false');
+      }
+
+      // Send config, get back connectionUri
+      const result = await this.bridge.startDb({
+        port: this.options.port,
+        host: this.options.host,
+        socketPath: this.options.socketPath,
+        storage: this.options.storage ?? 'memory',
+        storagePath: this.options.storagePath,
+        ...(this.options.fileStorageStartup === 'existing-only' ? { fileStorageStartup: 'existing-only' as const } : {}),
+        storageRehearsalId: this.options.storageRehearsalId,
+        auth: this.options.auth,
+        tls: this.options.tls,
+        oplog: this.options.oplog,
+        query: this.options.query,
+        inbound: this.options.inbound,
+        storageBudgetBytes: this.options.storageBudgetBytes,
+      }, getBridgeOperationOptions());
+      checkpoint();
+      if (!this.bridgeOwned || !this.bridge.running) {
+        throw new Error('nosqldb Rust process exited during startup');
+      }
+
+      if (!this.options.socketPath) {
+        const connectionUrl = new URL(result.connectionUri);
+        const resolvedPort = Number(connectionUrl.port);
+        if (
+          connectionUrl.protocol !== 'mongodb:'
+          || !connectionUrl.hostname
+          || !Number.isInteger(resolvedPort)
+          || resolvedPort < 1
+          || resolvedPort > 65_535
+        ) {
+          throw new Error(`nosqldb returned an invalid TCP connection URI: ${result.connectionUri}`);
+        }
+        this.resolvedPort = resolvedPort;
+      }
+      this.resolvedConnectionUri = result.connectionUri;
+      checkpoint();
+      this.isRunning = true;
+    } catch (error) {
+      const startupError = error instanceof NoSqlDbManagementOperationTerminationError
+        ? error
+        : optionsArg?.signal?.aborted
+          ? optionsArg.signal.reason
+          : startupAbortController.signal.aborted || (
+              startupDeadline !== undefined && Date.now() >= startupDeadline
+            )
+            ? timeoutError
+            : error;
+      this.isRunning = false;
+      this.resolvedConnectionUri = '';
+      this.resolvedPort = undefined;
+      if (this.bridgeOwned) {
+        try {
+          await this.bridge.terminate();
+          this.bridgeOwned = false;
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [startupError, cleanupError],
+            'NoSQLDB startup failed and Rust bridge cleanup was incomplete',
+            { cause: startupError },
+          );
+        }
+      }
+      throw startupError;
+    } finally {
+      if (startupTimeout) clearTimeout(startupTimeout);
+      if (externalAbortHandler && optionsArg?.signal) {
+        optionsArg.signal.removeEventListener('abort', externalAbortHandler);
+      }
+      this.startInProgress = false;
+      resolveStartCompletion();
+      if (this.startCompletionPromise === startCompletionPromise) {
+        this.startCompletionPromise = null;
+      }
+    }
+  }
+
+  /**
+   * Stop the server: wait for active startup work, send the engine a stop
+   * request, close its management input once it has acknowledged, give it
+   * `noSqlDbServerStopGraceMs` to exit by itself, and end it otherwise; then
+   * confirm the bridge's cleanup. Resolves with how the engine ended, which
+   * concurrent callers share; when no engine runs, the result says that no
+   * request was sent. Rejects, retaining ownership for a retry, only when the
+   * bridge's termination fails.
+   */
+  stop(): Promise<INoSqlDbServerStopResult> {
+    if (this.stopCompletionPromise) {
+      return this.stopCompletionPromise;
+    }
+
+    const stopCompletionPromise = this.stopInternal();
+    this.stopCompletionPromise = stopCompletionPromise;
+    const releaseStopCompletion = () => {
+      if (this.stopCompletionPromise === stopCompletionPromise) {
+        this.stopCompletionPromise = null;
+      }
+    };
+    void stopCompletionPromise.then(releaseStopCompletion, releaseStopCompletion);
+    return stopCompletionPromise;
+  }
+
+  private async stopInternal(): Promise<INoSqlDbServerStopResult> {
+    const startCompletionPromise = this.startCompletionPromise;
+    if (startCompletionPromise) {
+      await startCompletionPromise;
+    }
+
+    if (!this.isRunning && !this.bridgeOwned) {
+      return noStopRequestResult;
+    }
+
+    const requestGracefulStop = this.isRunning && this.bridge.running;
+    let stopAcknowledged = false;
+    if (requestGracefulStop) {
+      try {
+        await this.bridge.stopDb();
+        stopAcknowledged = true;
+      } catch {
+        // Confirmed bridge termination below still releases the owned process.
+      }
+    }
+    // An engine that acknowledged the stop exits by itself once its management
+    // input closes; it is ended only if it has not within the grace.
+    if (stopAcknowledged && this.bridge.engineProcessAlive) {
+      this.bridge.endManagementInput();
+      await this.bridge.waitForEngineExit(noSqlDbServerStopGraceMs);
+    }
+    const forcedByServer = this.bridge.engineProcessAlive;
+
+    try {
+      await this.bridge.terminate();
+    } catch (error) {
+      // An engine that has exited no longer runs, as the exit handler would
+      // have recorded outside a stop; ownership stays for a retry.
+      if (this.bridge.lastEngineExit !== null) {
+        this.isRunning = false;
+        this.resolvedConnectionUri = '';
+        this.resolvedPort = undefined;
+      }
+      throw error;
+    }
+    this.bridgeOwned = false;
+    this.isRunning = false;
+    this.resolvedConnectionUri = '';
+    this.resolvedPort = undefined;
+    // The process's exit event may follow the confirmed termination by a tick.
+    if (this.bridge.engineProcessAlive) await this.bridge.waitForEngineExit(1_000);
+    return stopResult(requestGracefulStop, stopAcknowledged, forcedByServer, this.bridge.lastEngineExit);
+  }
+
+  /**
+   * Get the connection URI for this server
+   */
+  getConnectionUri(): string {
+    if (this.resolvedConnectionUri) {
+      return this.resolvedConnectionUri;
+    }
+    // Fallback: compute from options
+    if (this.options.socketPath) {
+      const encodedPath = encodeURIComponent(this.options.socketPath);
+      return `mongodb://${encodedPath}`;
+    }
+    const baseUri = `mongodb://${this.options.host ?? '127.0.0.1'}:${this.options.port ?? 27017}`;
+    return this.options.tls?.enabled ? `${baseUri}/?tls=true` : baseUri;
+  }
+
+  /**
+   * Get the socket path (if using Unix socket mode)
+   */
+  get socketPath(): string | undefined {
+    return this.options.socketPath;
+  }
+
+  /**
+   * Check if the server is running
+   */
+  /** Process id of the spawned Rust engine, when it runs as a child process. */
+  get processId(): number | undefined {
+    return this.bridge.processId;
+  }
+
+  get running(): boolean {
+    return this.isRunning;
+  }
+
+  private async runDatabaseManagementOperation<TResult>(
+    operationArg: () => Promise<TResult>,
+  ): Promise<TResult> {
+    try {
+      return await operationArg();
+    } catch (error) {
+      if (
+        !this.bridge.running
+        || error instanceof NoSqlDbManagementOperationTerminationError
+      ) {
+        this.isRunning = false;
+        this.resolvedConnectionUri = '';
+        this.resolvedPort = undefined;
+        if (this.bridge.ownershipReleased) {
+          this.bridgeOwned = false;
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get the port the server is listening on
+   */
+  get port(): number {
+    return this.resolvedPort ?? this.options.port ?? 27017;
+  }
+
+  /**
+   * Get the host the server is bound to
+   */
+  get host(): string {
+    return this.options.host ?? '127.0.0.1';
+  }
+
+  /**
+   * Create an isolated database/user pair for an application tenant.
+   */
+  async createDatabaseTenant(
+    params: INoSqlDbDatabaseTenantInput,
+  ): Promise<INoSqlDbDatabaseTenantDescriptor> {
+    const descriptor = await this.bridge.createDatabaseTenant(params);
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
+  /** Authoritatively allocate an absent, fenced database tenant. */
+  async allocateDatabaseTenant(
+    params: INoSqlDbAllocateDatabaseTenantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbAllocateDatabaseTenantResult> {
+    const descriptor = await this.runDatabaseManagementOperation(
+      () => this.bridge.allocateDatabaseTenant(params, optionsArg),
+    );
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
+  /**
+   * Idempotently provision or rotate one exclusively owned database tenant.
+   */
+  async ensureDatabaseTenant(
+    params: INoSqlDbEnsureDatabaseTenantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbEnsureDatabaseTenantResult> {
+    const descriptor = await this.runDatabaseManagementOperation(
+      () => this.bridge.ensureDatabaseTenant(params, optionsArg),
+    );
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
+  /** Verify an exact tenant credential without changing provider state. */
+  async attestDatabaseTenant(
+    params: INoSqlDbAttestDatabaseTenantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbAttestDatabaseTenantResult> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.attestDatabaseTenant(params, optionsArg),
+    );
+  }
+
+  /**
+   * Delete a tenant database and its tenant user(s).
+   */
+  async deleteDatabaseTenant(
+    params: INoSqlDbDeleteDatabaseTenantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbDeleteDatabaseTenantResult> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.deleteDatabaseTenant(params, optionsArg),
+    );
+  }
+
+  /** Issue one fixed-expiry read grant bound to an exact active allocation. */
+  async issueDatabaseAllocationReadAccessGrant(
+    params: INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbIssueDatabaseAllocationReadAccessGrantResult> {
+    const descriptor = await this.runDatabaseManagementOperation(
+      () => this.bridge.issueDatabaseAllocationReadAccessGrant(params, optionsArg),
+    );
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
+  /** Idempotently revoke one allocation read grant without returning a secret. */
+  async revokeDatabaseAllocationReadAccessGrant(
+    params: INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.revokeDatabaseAllocationReadAccessGrant(params, optionsArg),
+    );
+  }
+
+  /**
+   * Rotate a tenant user's password without restarting the server.
+   */
+  async rotateDatabaseTenantPassword(
+    params: INoSqlDbRotateDatabaseTenantPasswordInput,
+  ): Promise<INoSqlDbDatabaseTenantDescriptor> {
+    const descriptor = await this.bridge.rotateDatabaseTenantPassword(params);
+    return this.withTenantMongoUri(descriptor, params.password);
+  }
+
+  /**
+   * List known database tenants.
+   */
+  async listDatabaseTenants(): Promise<INoSqlDbDatabaseTenantDescriptor[]> {
+    return this.bridge.listDatabaseTenants();
+  }
+
+  /**
+   * Get a tenant descriptor without exposing a password.
+   */
+  async getDatabaseTenantDescriptor(params: {
+    databaseName: string;
+    username: string;
+  }): Promise<INoSqlDbDatabaseTenantDescriptor> {
+    return this.bridge.getDatabaseTenantDescriptor(params);
+  }
+
+  /** Inspect the durable high-water mark without exposing mutation receipts. */
+  async getDatabaseResourceFenceState(
+    params: { databaseName: string },
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbDatabaseResourceFenceState | null> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.getDatabaseResourceFenceState(params, optionsArg),
+    );
+  }
+
+  /**
+   * Export one database as an Extended JSON snapshot.
+   */
+  async exportDatabase(
+    params: INoSqlDbExportDatabaseInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbDatabaseExport> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.exportDatabase(params, optionsArg),
+    );
+  }
+
+  /** Read an exact held publication without opening its serving data plane. */
+  async exportHeldDatabase(
+    params: INoSqlDbExportHeldDatabaseInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbDatabaseExport> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.exportHeldDatabase(params, optionsArg),
+    );
+  }
+
+  /** Compute a bounded, database-name-independent digest of logical database content. */
+  async getDatabaseContentDigest(
+    params: INoSqlDbGetDatabaseContentDigestInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbDatabaseContentDigest> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.getDatabaseContentDigest(params, optionsArg),
+    );
+  }
+
+  /**
+   * Replace one database with a previously exported snapshot.
+   */
+  async importDatabase(
+    params: INoSqlDbImportDatabaseInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbImportDatabaseResult> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.importDatabase(params, optionsArg),
+    );
+  }
+
+  /** Release an exact held database publication after downstream fsync. */
+  async commitDatabasePublication(
+    params: INoSqlDbCommitDatabasePublicationInput,
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<TNoSqlDbCommitDatabasePublicationResult> {
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.commitDatabasePublication(params, optionsArg),
+    );
+  }
+
+  /**
+   * Get readiness/health details for long-running service use.
+   */
+  async getHealth(
+    optionsArg?: INoSqlDbManagementOperationOptions,
+  ): Promise<INoSqlDbHealth> {
+    if (!this.isRunning) {
+      return {
+        running: false,
+        storage: this.options.storage,
+        storagePath: this.options.storage === 'file' ? this.options.storagePath : undefined,
+        resourceFencingVersion: this.options.storage === 'file' ? 1 : undefined,
+        resourceFencingSupported: this.options.storage === 'file' ? false : undefined,
+        resourceFencingRequiresDrain: this.options.storage === 'file' ? true : undefined,
+        allocationFencingVersion: this.options.storage === 'file' ? 1 : undefined,
+        allocationFencingSupported: this.options.storage === 'file' ? false : undefined,
+        allocationFencingRequiresDrain: this.options.storage === 'file' ? true : undefined,
+        publicationHoldVersion: 1,
+        publicationHoldSupported: false,
+        publicationHoldRequiresExternalDrain: false,
+        authEnabled: Boolean(this.options.auth?.enabled),
+        authUsers: this.options.auth?.users?.length ?? 0,
+        usersPathConfigured: false,
+        databaseCount: 0,
+        collectionCount: 0,
+      };
+    }
+    return this.runDatabaseManagementOperation(
+      () => this.bridge.getHealth(optionsArg),
+    );
+  }
+
+  // --- OpLog / Debug API ---
+
+  async getCommittedWrites(params: INoSqlDbGetCommittedWritesInput): Promise<INoSqlDbCommittedWritesPage> {
+    return this.runDatabaseManagementOperation(() => this.bridge.getCommittedWrites(params));
+  }
+
+  /**
+   * Get oplog entries, optionally filtered.
+   */
+  async getOpLog(params: {
+    sinceSeq?: number;
+    limit?: number;
+    db?: string;
+    collection?: string;
+  } = {}): Promise<IOpLogResult> {
+    return this.bridge.getOpLog(params);
+  }
+
+  /**
+   * Get aggregate oplog statistics.
+   */
+  async getOpLogStats(): Promise<IOpLogStats> {
+    return this.bridge.getOpLogStats();
+  }
+
+  /**
+   * Revert database state to a specific oplog sequence number.
+   * Use dryRun=true to preview which entries would be reverted.
+   */
+  async revertToSeq(seq: number, dryRun = false): Promise<IRevertResult> {
+    return this.bridge.revertToSeq(seq, dryRun);
+  }
+
+  /**
+   * List all collections across all databases, with document counts.
+   */
+  async getCollections(db?: string): Promise<ICollectionInfo[]> {
+    return this.bridge.getCollections(db);
+  }
+
+  /**
+   * Get documents from a collection with pagination.
+   */
+  async getDocuments(
+    db: string,
+    collection: string,
+    limit = 50,
+    skip = 0,
+  ): Promise<IDocumentsResult> {
+    return this.bridge.getDocuments(db, collection, limit, skip);
+  }
+
+  /**
+   * Get server metrics including database/collection counts and oplog info.
+   */
+  async getMetrics(): Promise<INoSqlDbMetrics> {
+    return this.bridge.getMetrics();
+  }
+
+  private withTenantMongoUri<TDescriptor extends INoSqlDbDatabaseTenantDescriptor>(
+    descriptor: TDescriptor,
+    password: string,
+  ): TDescriptor & { mongodbUri: string } {
+    return {
+      ...descriptor,
+      mongodbUri: this.buildTenantMongoUri(descriptor.databaseName, descriptor.username, password),
+    };
+  }
+
+  private buildTenantMongoUri(databaseName: string, username: string, password: string): string {
+    const host = this.options.socketPath
+      ? encodeURIComponent(this.options.socketPath)
+      : `${this.options.host ?? '127.0.0.1'}:${this.port}`;
+    const auth = `${encodeURIComponent(username)}:${encodeURIComponent(password)}@`;
+    const query = new URLSearchParams({ authSource: databaseName });
+    if (this.options.tls?.enabled) {
+      query.set('tls', 'true');
+    }
+    return `mongodb://${auth}${host}/${encodeURIComponent(databaseName)}?${query.toString()}`;
+  }
+}