@lossless.org/nosqldb 10.0.0 → 10.2.0

package/ts/ts_local/classes.localnosqldb.ts

@@ -1,3 +1,18 @@
+import {
+  normalizeStoppedStorageRootAlignmentInput, normalizeStoppedStorageRootAlignmentResult,
+  normalizeStoppedStorageRootAlignmentAbortResult,
+  type ILocalNoSqlDbStoppedStorageRootAlignmentInput, type TLocalNoSqlDbStoppedStorageRootAlignmentResult,
+  type ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult,
+} from '../ts_nosqldb/storage-root-alignment.js';
+import {
+  NoSqlDbStoppedOperationError,
+  normalizeStoppedStorageRootInspectionInput,
+  validateNoSqlDbStoppedOperationOptions,
+  isStoppedOperationUnknownMethod,
+  type INoSqlDbStoppedOperationOptions,
+  type ILocalNoSqlDbStoppedStorageRootInspectionInput,
+  type TLocalNoSqlDbStoppedStorageRootInspection,
+} from '../ts_nosqldb/stopped-storage.js';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import * as net from 'node:net';
@@ -17,6 +32,8 @@ import {
 import {
   RustDbBridge,
   rustDbBridgeStorageRootRelocation,
+  rustDbBridgeStorageRootAlignment,
+  rustDbBridgeStorageRootAlignmentAbort,
 } from '../ts_nosqldb/rust-db-bridge.js';
 import { validateNoSqlDbStorageRehearsalStartup } from '../ts_nosqldb/storage-rehearsal.js';
 import {
@@ -55,7 +72,7 @@ export interface ILocalNoSqlDbOptions {
   storageRehearsalId?: string;
   /** Exact engine executable. Invalid explicit paths reject without chmod or discovery fallback. Omit for normal discovery. */
   binaryPath?: string;
-  /** Default: current-format-only. Native ownership precedes all file-root initialization. */
+  /** Default: current-format-only. existing-only refuses missing, empty or uninitialized storage. */
   fileStorageStartup?: TNoSqlDbFileStorageStartup;
   /** Required: where to store data */
   folderPath: string;
@@ -106,12 +123,12 @@ export class LocalNoSqlDb {
     };
   }
 
-  private static createOfflineInspectionBridge(): RustDbBridge {
-    return new RustDbBridge();
+  private static createOfflineInspectionBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
   }
 
-  private static createStorageRootRelocationBridge(): RustDbBridge {
-    return new RustDbBridge();
+  private static createStorageRootRelocationBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
   }
 
   private static async withStorageRootRelocationGate<TResult>(
@@ -148,12 +165,12 @@ export class LocalNoSqlDb {
    */
   public static async relocateStoppedStorageRoot(
     inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
-    optionsArg?: INoSqlDbManagementOperationOptions,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
   ): Promise<ILocalNoSqlDbStoppedStorageRootRelocationReceipt> {
     let input: ILocalNoSqlDbStoppedStorageRootRelocationInput;
     try {
       input = normalizeLocalNoSqlDbStoppedStorageRootRelocationInput(inputArg);
-      validateNoSqlDbManagementOperationOptions(optionsArg);
+      validateNoSqlDbStoppedOperationOptions(optionsArg);
     } catch (error) {
       if (error instanceof LocalNoSqlDbStorageRootRelocationError) throw error;
       throw new LocalNoSqlDbStorageRootRelocationError('INVALID_REQUEST');
@@ -188,7 +205,7 @@ export class LocalNoSqlDb {
       let receipt: ILocalNoSqlDbStoppedStorageRootRelocationReceipt | undefined;
       let operationError: LocalNoSqlDbStorageRootRelocationError | undefined;
       try {
-        bridge = LocalNoSqlDb.createStorageRootRelocationBridge();
+        bridge = LocalNoSqlDb.createStorageRootRelocationBridge(optionsArg?.binaryPath);
         LocalNoSqlDb.storageRootRelocationBridge = bridge;
         const spawnTimeout = LocalNoSqlDb.remainingManagementTimeout(deadline);
         const spawned = await bridge.spawn({
@@ -205,7 +222,9 @@ export class LocalNoSqlDb {
         });
         receipt = normalizeLocalNoSqlDbStoppedStorageRootRelocationReceipt(result, input);
       } catch (error) {
-        if (error instanceof LocalNoSqlDbStorageRootRelocationError) {
+        if (error instanceof NoSqlDbStoppedOperationError || isStoppedOperationUnknownMethod(error, 'relocateStoppedStorageRoot')) {
+          operationError = new LocalNoSqlDbStorageRootRelocationError(error instanceof NoSqlDbStoppedOperationError ? error.code : 'UNSUPPORTED');
+        } else if (error instanceof LocalNoSqlDbStorageRootRelocationError) {
           operationError = error;
         } else {
           const requestWasDispatched = error instanceof Error
@@ -247,21 +266,110 @@ export class LocalNoSqlDb {
     });
   }
 
+  private static createStorageRootAlignmentBridge(binaryPath?: string): RustDbBridge {
+    return new RustDbBridge({ binaryPath });
+  }
+
+  /** Adopt an authority-free stopped copy as an independent provider. Retain its external receipt. */
+  public static alignStoppedStorageRoot(input: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options?: INoSqlDbStoppedOperationOptions): Promise<TLocalNoSqlDbStoppedStorageRootAlignmentResult> {
+    return LocalNoSqlDb.runStorageRootAlignment(input, options, false, normalizeStoppedStorageRootAlignmentResult);
+  }
+  /** Abort only the exact incomplete profile append; a complete append must be finished. */
+  public static abortStoppedStorageRootAlignment(input: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options?: INoSqlDbStoppedOperationOptions): Promise<ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult> {
+    return LocalNoSqlDb.runStorageRootAlignment(input, options, true, normalizeStoppedStorageRootAlignmentAbortResult);
+  }
+  private static async runStorageRootAlignment<TResult>(inputArg: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+    options: INoSqlDbStoppedOperationOptions | undefined, abort: boolean,
+    normalize: (value: unknown, input: ILocalNoSqlDbStoppedStorageRootAlignmentInput) => TResult): Promise<TResult> {
+    let input: ILocalNoSqlDbStoppedStorageRootAlignmentInput;
+    try {
+      input = normalizeStoppedStorageRootAlignmentInput(inputArg);
+      validateNoSqlDbStoppedOperationOptions(options);
+      if (abort && input.dryRun) throw new Error('abort cannot be a dry run');
+    } catch { throw new NoSqlDbStoppedOperationError('INVALID_REQUEST'); }
+    if (options?.signal?.aborted) throw new NoSqlDbStoppedOperationError('CANCELLED');
+    if (!['linux', 'darwin'].includes(process.platform)) throw new NoSqlDbStoppedOperationError('UNSUPPORTED');
+    const deadline = Date.now() + (options?.timeoutMs ?? 3_600_000);
+    const remaining = () => {
+      if (options?.signal?.aborted) throw new NoSqlDbStoppedOperationError('CANCELLED');
+      const timeoutMs = deadline - Date.now();
+      if (timeoutMs <= 0) throw new NoSqlDbStoppedOperationError('CANCELLED');
+      return { signal: options?.signal, timeoutMs };
+    };
+    // Share the mutation gate and retained ownership with relocation, including
+    // retries after an earlier sidecar could not confirm termination.
+    return LocalNoSqlDb.withStorageRootRelocationGate(async () => {
+      const retained = LocalNoSqlDb.storageRootRelocationBridge;
+      if (retained) {
+        try { await retained.terminate({ gracePeriodMs: 0 }); }
+        catch { throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED'); }
+        if (!retained.ownershipReleased) throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED');
+        LocalNoSqlDb.storageRootRelocationBridge = undefined;
+      }
+      let bridge: RustDbBridge | undefined;
+      let result: TResult | undefined;
+      let failure: NoSqlDbStoppedOperationError | undefined;
+      let dispatched = false;
+      const method = abort ? 'abortStoppedStorageRootAlignment' : 'alignStoppedStorageRoot';
+      try {
+        remaining();
+        bridge = LocalNoSqlDb.createStorageRootAlignmentBridge(options?.binaryPath);
+        LocalNoSqlDb.storageRootRelocationBridge = bridge;
+        if (!await bridge.spawn(remaining())) throw new NoSqlDbStoppedOperationError('IO');
+        const commandOptions = remaining();
+        dispatched = true;
+        const value = abort ? await bridge[rustDbBridgeStorageRootAlignmentAbort](input, commandOptions)
+          : await bridge[rustDbBridgeStorageRootAlignment](input, commandOptions);
+        result = normalize(value, input);
+      } catch (error) {
+        if (error instanceof NoSqlDbStoppedOperationError) failure = error;
+        else if (isStoppedOperationUnknownMethod(error, method)) failure = new NoSqlDbStoppedOperationError('UNSUPPORTED');
+        else if (error instanceof Error && 'code' in error && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
+          && 'method' in error && error.method === method && 'responseErrorCode' in error
+          && isLocalNoSqlDbStorageRootRelocationErrorCode(error.responseErrorCode)) {
+          failure = new NoSqlDbStoppedOperationError(error.responseErrorCode);
+        } else failure = new NoSqlDbStoppedOperationError(dispatched ? 'RECOVERY_REQUIRED' : 'IO');
+      }
+      if (bridge) {
+        try {
+          await bridge.terminate({ gracePeriodMs: 0 });
+          if (!bridge.ownershipReleased) throw new Error('termination unconfirmed');
+          if (LocalNoSqlDb.storageRootRelocationBridge === bridge) LocalNoSqlDb.storageRootRelocationBridge = undefined;
+        } catch { failure = new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED'); }
+      }
+      if (failure) throw failure;
+      if (result === undefined) throw new NoSqlDbStoppedOperationError('RECOVERY_REQUIRED');
+      return result;
+    });
+  }
+
+  /** Read-only complete owner audit of a stopped source or physically admissible copy. */
+  public static async inspectStoppedStorageRoot(
+    inputArg: ILocalNoSqlDbStoppedStorageRootInspectionInput,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
+  ): Promise<TLocalNoSqlDbStoppedStorageRootInspection> {
+    return LocalNoSqlDb.runOfflineInspection(inputArg, optionsArg,
+      normalizeStoppedStorageRootInspectionInput,
+      (bridge, input, options) => bridge.inspectStoppedStorageRoot(input, options));
+  }
+
   private static async runOfflineInspection<
     TInput extends { folderPath: string },
     TResult,
   >(
     inputArg: TInput,
-    optionsArg: INoSqlDbManagementOperationOptions | undefined,
+    optionsArg: INoSqlDbStoppedOperationOptions | undefined,
     normalizeInputArg: (inputArg: TInput) => TInput,
     inspectArg: (
       bridgeArg: RustDbBridge,
       inputArg: TInput,
-      optionsArg?: INoSqlDbManagementOperationOptions,
+      optionsArg?: INoSqlDbStoppedOperationOptions,
     ) => Promise<TResult>,
   ): Promise<TResult> {
     const validatedInput = normalizeInputArg(inputArg);
-    validateNoSqlDbManagementOperationOptions(optionsArg);
+    validateNoSqlDbStoppedOperationOptions(optionsArg);
     optionsArg?.signal?.throwIfAborted();
 
     const input = normalizeInputArg({
@@ -271,7 +379,7 @@ export class LocalNoSqlDb {
     const deadline = optionsArg?.timeoutMs === undefined
       ? undefined
       : Date.now() + optionsArg.timeoutMs;
-    const bridge = LocalNoSqlDb.createOfflineInspectionBridge();
+    const bridge = LocalNoSqlDb.createOfflineInspectionBridge(optionsArg?.binaryPath);
     let operationFailed = false;
     let operationError: unknown;
     let result: TResult | undefined;
@@ -334,7 +442,7 @@ export class LocalNoSqlDb {
    */
   public static async inspectOfflinePhysicalNamespaces(
     inputArg: ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
-    optionsArg?: INoSqlDbManagementOperationOptions,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
   ): Promise<ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult> {
     return LocalNoSqlDb.runOfflineInspection(
       inputArg,
@@ -351,7 +459,7 @@ export class LocalNoSqlDb {
    */
   public static async inspectOfflineStringValue(
     inputArg: ILocalNoSqlDbOfflineStringValueInspection,
-    optionsArg?: INoSqlDbManagementOperationOptions,
+    optionsArg?: INoSqlDbStoppedOperationOptions,
   ): Promise<TLocalNoSqlDbOfflineStringValueInspectionResult> {
     return LocalNoSqlDb.runOfflineInspection(
       inputArg,

package/ts/ts_nosqldb/file-storage-startup.ts

@@ -1,9 +1,10 @@
 /** Native format admission is read-only until the engine owns the file root. */
-export type TNoSqlDbFileStorageStartup = 'current-format-only';
+export type TNoSqlDbFileStorageStartup = 'current-format-only' | 'existing-only';
 
 export const normalizeNoSqlDbFileStorageStartup = (
   valueArg: unknown,
 ): TNoSqlDbFileStorageStartup => {
   if (valueArg === undefined || valueArg === 'current-format-only') return 'current-format-only';
-  throw new TypeError('NoSQLDB fileStorageStartup must be "current-format-only"; automatic storage conversion has been removed');
+  if (valueArg === 'existing-only') return 'existing-only';
+  throw new TypeError('NoSQLDB fileStorageStartup must be "current-format-only" or "existing-only"; automatic storage conversion has been removed');
 };

package/ts/ts_nosqldb/index.ts

@@ -1,4 +1,11 @@
 // NoSQLDB - Wire protocol compatible embedded database server
+export { NoSqlDbStoppedOperationError } from './stopped-storage.js';
+export type {
+  INoSqlDbStoppedOperationOptions, ILocalNoSqlDbStoppedStorageRootInspectionInput,
+  TLocalNoSqlDbStoppedStorageRootInspection, ILocalNoSqlDbAuditedStorageRoot,
+  ILocalNoSqlDbUnavailableStorageRoot, INoSqlDbPhysicalAdmissionViolation,
+  TNoSqlDbStorageRootBindingChange,
+} from './stopped-storage.js';
 export { NoSqlDbStorageRehearsal } from './classes.storagerehearsal.js';
 export { NoSqlDbStorageRehearsalError, noSqlDbStorageRehearsalErrorCodes } from './storage-rehearsal.js';
 export type {
@@ -102,3 +109,9 @@ export {
 } from './storage-root-relocation.js';
 export type { TNoSqlDbEffectivePayloadInputV1 } from './resource-fencing.js';
 export { createNoSqlDbEffectivePayloadSha256V1 } from './resource-fencing.js';
+
+export type {
+  INoSqlDbStorageRootPins, ILocalNoSqlDbStoppedStorageRootAlignmentInput,
+  ILocalNoSqlDbStoppedStorageRootAlignmentReceipt, TLocalNoSqlDbStoppedStorageRootAlignmentResult,
+  ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult,
+} from './storage-root-alignment.js';

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

@@ -1,5 +1,8 @@
+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 { 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';
@@ -192,7 +195,16 @@ type TOfflinePhysicalNamespaceInspectionCommandParams = {
   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;
@@ -311,6 +323,7 @@ export interface INoSqlDbQueryOptions {
 }
 
 interface INoSqlDbRustConfig {
+  fileStorageStartup?: TNoSqlDbFileStorageStartup;
   storageRehearsalId?: string;
   port?: number;
   host?: string;
@@ -610,7 +623,7 @@ export class RustDbBridge extends EventEmitter {
         { request, timeoutMs: optionsArg.timeoutMs }, optionsArg) as INoSqlDbStorageRehearsalReceipt;
     } catch (error) {
       await this.awaitManagementOperationTermination(error);
-      throw error;
+      throw normalizeStoppedOperationUnknownMethod(error, 'createStoppedStorageRehearsal');
     }
   }
 
@@ -628,7 +641,42 @@ export class RustDbBridge extends EventEmitter {
       ) as ILocalNoSqlDbStoppedStorageRootRelocationReceipt;
     } catch (error) {
       await this.awaitManagementOperationTermination(error);
-      throw 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');
     }
   }
 
@@ -651,7 +699,7 @@ export class RustDbBridge extends EventEmitter {
       ) as ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult;
     } catch (error) {
       await this.awaitManagementOperationTermination(error);
-      throw error;
+      throw normalizeStoppedOperationUnknownMethod(error, 'inspectOfflinePhysicalNamespaces');
     }
   }
 
@@ -669,7 +717,7 @@ export class RustDbBridge extends EventEmitter {
       ) as TLocalNoSqlDbOfflineStringValueInspectionResult;
     } catch (error) {
       await this.awaitManagementOperationTermination(error);
-      throw error;
+      throw normalizeStoppedOperationUnknownMethod(error, 'inspectOfflineStringValue');
     }
   }
 

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

@@ -58,7 +58,7 @@ export interface INoSqlDbServerOptions {
   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. The native owner rejects foreign, mixed and migration staging roots without conversion. */
+  /** 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;
@@ -261,6 +261,7 @@ export class NoSqlDbServer {
         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,

package/ts/ts_nosqldb/service-types.ts

@@ -1,4 +1,7 @@
 export interface INoSqlDbHealth {
+  /** Present on engines supporting stopped root alignment. */
+  providerRootId?: string;
+  lsn?: string | null;
   running: boolean;
   storage?: 'memory' | 'file';
   fileStorageEngine?: 'mvcc';
@@ -271,6 +274,7 @@ export interface INoSqlDbManagementOperationOptions {
 }
 
 export interface INoSqlDbDatabaseResourceFenceState {
+  providerRootId?: string;
   version: 1;
   databaseName: string;
   resourceIdSha256: string;

package/ts/ts_nosqldb/stopped-storage.ts

@@ -0,0 +1,108 @@
+import * as plugins from './plugins.js';
+import { validateNoSqlDbManagementOperationOptions } from './offline-inspection.js';
+import type { INoSqlDbManagementOperationOptions } from './service-types.js';
+import type { TLocalNoSqlDbStorageRootRelocationErrorCode } from './storage-root-relocation.js';
+
+export interface INoSqlDbStoppedOperationOptions extends INoSqlDbManagementOperationOptions {
+  /** Exact executable; invalid explicit paths never fall back to discovery. */
+  binaryPath?: string;
+}
+
+export interface ILocalNoSqlDbStoppedStorageRootInspectionInput { folderPath: string; }
+export type TNoSqlDbStorageRootBindingChange = 'none' | 'path' | 'inode' | 'path+inode';
+export interface INoSqlDbPhysicalAdmissionViolation {
+  relativePath: string;
+  rule: string;
+  observed: string;
+}
+export interface ILocalNoSqlDbAuditedStorageRoot {
+  status: 'audited';
+  bindingState: 'matching' | 'foreign';
+  bindingChange: TNoSqlDbStorageRootBindingChange;
+  storagePurpose: 'production';
+  profileSchema: 1 | 4;
+  providerRootId: string;
+  /** Group/timeline describe shared lineage, not independent provider identity. */
+  groupId: string;
+  timelineId: string;
+  /** All counts and positions are canonical unsigned decimal strings. */
+  lsn: string;
+  records: string;
+  recordsSha256: string;
+  recordsWithoutFencingProfileSha256: string;
+  authUsers: string;
+  authority: {
+    resourceFences: string;
+    receipts: string;
+    publicationHolds: string;
+    activeAllocations: string;
+    retiredAllocations: string;
+    allocationReplays: string;
+    activeGrants: '0';
+    importStages: '0';
+  };
+  generations: { manifest: string; onDisk: string[] };
+  alignmentEligible: boolean;
+  reasons: string[];
+  physicalAdmissionViolations: [];
+}
+export interface ILocalNoSqlDbUnavailableStorageRoot {
+  status: 'unavailable';
+  stage: 'admission' | 'audit';
+  alignmentEligible: false;
+  reasons: string[];
+  /** Bounded advisory evidence. No logical identity or pin is trusted here. */
+  physicalAdmissionViolations: INoSqlDbPhysicalAdmissionViolation[];
+}
+export type TLocalNoSqlDbStoppedStorageRootInspection =
+  ILocalNoSqlDbAuditedStorageRoot | ILocalNoSqlDbUnavailableStorageRoot;
+
+export class NoSqlDbStoppedOperationError extends Error {
+  public readonly responseErrorCode: TLocalNoSqlDbStorageRootRelocationErrorCode;
+  public constructor(public readonly code: TLocalNoSqlDbStorageRootRelocationErrorCode) {
+    super(`NoSQLDB stopped operation failed with code ${code}`);
+    this.name = 'NoSqlDbStoppedOperationError';
+    this.responseErrorCode = code;
+  }
+}
+
+export const validateNoSqlDbStoppedOperationOptions = (options?: INoSqlDbStoppedOperationOptions): void => {
+  validateNoSqlDbManagementOperationOptions(options);
+  if (options?.binaryPath !== undefined && (typeof options.binaryPath !== 'string'
+    || !options.binaryPath.length || options.binaryPath.includes('\0'))) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+};
+
+export const normalizeStoppedStorageRootInspectionInput = (
+  input: ILocalNoSqlDbStoppedStorageRootInspectionInput,
+): ILocalNoSqlDbStoppedStorageRootInspectionInput => {
+  if (!input || Object.getPrototypeOf(input) !== Object.prototype
+    || Reflect.ownKeys(input).length !== 1
+    || !Object.getOwnPropertyDescriptor(input, 'folderPath')?.enumerable
+    || !('value' in Object.getOwnPropertyDescriptor(input, 'folderPath')!)) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+  const folderPath = input.folderPath;
+  if (typeof folderPath !== 'string' || plugins.buffer.Buffer.byteLength(folderPath) > 4095
+    || !plugins.path.isAbsolute(folderPath) || plugins.path.dirname(folderPath) === folderPath
+    || folderPath.endsWith('/') || folderPath.includes('//') || /\p{Cc}/u.test(folderPath)
+    || folderPath.split('/').some(part => part === '.' || part === '..' || part.startsWith('.smartdb-rehearsal-'))) {
+    throw new NoSqlDbStoppedOperationError('INVALID_REQUEST');
+  }
+  return { folderPath };
+};
+
+/** Only a confirmed Rust response for this exact command proves non-dispatch.
+ * Transport errors with the same text remain ambiguous. */
+export const isStoppedOperationUnknownMethod = (error: unknown, method: string): boolean =>
+  error instanceof Error && 'code' in error
+  && error.code === 'ERR_RUST_BRIDGE_REQUEST_RUST_RESPONSE'
+  && 'requestId' in error && typeof error.requestId === 'string' && error.requestId.length > 0
+  && 'method' in error && error.method === method
+  && (('responseErrorCode' in error && error.responseErrorCode === 'UNKNOWN_METHOD')
+    || ((!('responseErrorCode' in error) || error.responseErrorCode === undefined)
+      && error.message === `Unknown method: ${method}`));
+
+export const normalizeStoppedOperationUnknownMethod = (error: unknown, method: string): unknown =>
+  isStoppedOperationUnknownMethod(error, method) ? new NoSqlDbStoppedOperationError('UNSUPPORTED') : error;