@push.rocks/smartdb 5.0.5 → 5.2.0

package/ts/ts_local/classes.localsmartdb.ts

@@ -4,20 +4,32 @@ import * as net from 'net';
 import * as path from 'path';
 import * as os from 'os';
 import {
-  RustDbBridge,
   SmartdbServer,
   type ILocalSmartDbOfflinePhysicalNamespaceInspection,
   type ILocalSmartDbOfflinePhysicalNamespaceInspectionResult,
+  type ILocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationReceipt,
   type ILocalSmartDbOfflineStringValueInspection,
   type ISmartDbManagementOperationOptions,
   type TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/index.js';
+import {
+  RustDbBridge,
+  rustDbBridgeStorageRootRelocation,
+} from '../ts_smartdb/rust-db-bridge.js';
 import { StorageMigrator } from '../ts_migration/index.js';
 import {
   normalizeLocalSmartDbOfflinePhysicalNamespaceInspectionInput,
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from '../ts_smartdb/offline-inspection.js';
+import {
+  assertNoLocalSmartDbStorageRootRelocationWorkspace,
+  isLocalSmartDbStorageRootRelocationErrorCode,
+  LocalSmartDbStorageRootRelocationError,
+  normalizeLocalSmartDbStoppedStorageRootRelocationInput,
+  normalizeLocalSmartDbStoppedStorageRootRelocationReceipt,
+} from '../ts_smartdb/storage-root-relocation.js';
 
 /**
  * Connection information returned by LocalSmartDb.start()
@@ -65,6 +77,8 @@ export interface ILocalSmartDbOptions {
  * ```
  */
 export class LocalSmartDb {
+  private static storageRootRelocationGate: Promise<void> = Promise.resolve();
+  private static storageRootRelocationBridge: RustDbBridge | undefined;
   private options: ILocalSmartDbOptions;
   private server: SmartdbServer | null = null;
   private generatedSocketPath: string | null = null;
@@ -77,6 +91,141 @@ export class LocalSmartDb {
     return new RustDbBridge();
   }
 
+  private static createStorageRootRelocationBridge(): RustDbBridge {
+    return new RustDbBridge();
+  }
+
+  private static async withStorageRootRelocationGate<TResult>(
+    operationArg: () => Promise<TResult>,
+  ): Promise<TResult> {
+    const previous = LocalSmartDb.storageRootRelocationGate;
+    let release!: () => void;
+    LocalSmartDb.storageRootRelocationGate = new Promise<void>((resolveArg) => {
+      release = resolveArg;
+    });
+    await previous;
+    try {
+      return await operationArg();
+    } finally {
+      release();
+    }
+  }
+
+  private static remainingManagementTimeout(
+    deadlineArg: number | undefined,
+  ): number | undefined {
+    if (deadlineArg === undefined) return undefined;
+    const remaining = deadlineArg - Date.now();
+    if (remaining <= 0) {
+      throw new LocalSmartDbStorageRootRelocationError('IO');
+    }
+    return remaining;
+  }
+
+  /**
+   * Relocate one stopped, plain file-storage root without starting its engine.
+   */
+  public static async relocateStoppedStorageRoot(
+    inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbStoppedStorageRootRelocationReceipt> {
+    let input: ILocalSmartDbStoppedStorageRootRelocationInput;
+    try {
+      input = normalizeLocalSmartDbStoppedStorageRootRelocationInput(inputArg);
+      validateSmartDbManagementOperationOptions(optionsArg);
+    } catch (error) {
+      if (error instanceof LocalSmartDbStorageRootRelocationError) throw error;
+      throw new LocalSmartDbStorageRootRelocationError('INVALID_REQUEST');
+    }
+    if (optionsArg?.signal?.aborted) {
+      throw new LocalSmartDbStorageRootRelocationError('IO');
+    }
+    if (process.platform !== 'linux' && process.platform !== 'darwin') {
+      throw new LocalSmartDbStorageRootRelocationError('UNSUPPORTED');
+    }
+    const deadline = optionsArg?.timeoutMs === undefined
+      ? undefined
+      : Date.now() + optionsArg.timeoutMs;
+
+    return LocalSmartDb.withStorageRootRelocationGate(async () => {
+      const retainedBridge = LocalSmartDb.storageRootRelocationBridge;
+      if (retainedBridge) {
+        try {
+          await retainedBridge.terminate({ gracePeriodMs: 0 });
+        } catch {
+          throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (!retainedBridge.ownershipReleased) {
+          throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+        if (LocalSmartDb.storageRootRelocationBridge === retainedBridge) {
+          LocalSmartDb.storageRootRelocationBridge = undefined;
+        }
+      }
+
+      let bridge: RustDbBridge | undefined;
+      let receipt: ILocalSmartDbStoppedStorageRootRelocationReceipt | undefined;
+      let operationError: LocalSmartDbStorageRootRelocationError | undefined;
+      try {
+        bridge = LocalSmartDb.createStorageRootRelocationBridge();
+        LocalSmartDb.storageRootRelocationBridge = bridge;
+        const spawnTimeout = LocalSmartDb.remainingManagementTimeout(deadline);
+        const spawned = await bridge.spawn({
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(spawnTimeout === undefined ? {} : { timeoutMs: spawnTimeout }),
+        });
+        if (!spawned) {
+          throw new LocalSmartDbStorageRootRelocationError('IO');
+        }
+        const commandTimeout = LocalSmartDb.remainingManagementTimeout(deadline);
+        const result = await bridge[rustDbBridgeStorageRootRelocation](input, {
+          ...(optionsArg?.signal ? { signal: optionsArg.signal } : {}),
+          ...(commandTimeout === undefined ? {} : { timeoutMs: commandTimeout }),
+        });
+        receipt = normalizeLocalSmartDbStoppedStorageRootRelocationReceipt(result, input);
+      } catch (error) {
+        if (error instanceof LocalSmartDbStorageRootRelocationError) {
+          operationError = error;
+        } else {
+          const requestWasDispatched = error instanceof Error
+            && 'requestId' in error
+            && typeof error.requestId === 'string';
+          if (
+            requestWasDispatched
+            && error instanceof Error
+            && 'responseErrorCode' in error
+            && isLocalSmartDbStorageRootRelocationErrorCode(error.responseErrorCode)
+          ) {
+            operationError = new LocalSmartDbStorageRootRelocationError(error.responseErrorCode);
+          } else {
+            operationError = new LocalSmartDbStorageRootRelocationError(
+              requestWasDispatched ? 'RECOVERY_REQUIRED' : 'IO',
+            );
+          }
+        }
+      }
+
+      if (bridge) {
+        try {
+          await bridge.terminate({ gracePeriodMs: 0 });
+          if (!bridge.ownershipReleased) {
+            throw new Error('termination was not confirmed');
+          }
+          if (LocalSmartDb.storageRootRelocationBridge === bridge) {
+            LocalSmartDb.storageRootRelocationBridge = undefined;
+          }
+        } catch {
+          operationError = new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+        }
+      }
+      if (operationError) throw operationError;
+      if (!receipt) {
+        throw new LocalSmartDbStorageRootRelocationError('RECOVERY_REQUIRED');
+      }
+      return receipt;
+    });
+  }
+
   private static async runOfflineInspection<
     TInput extends { folderPath: string },
     TResult,
@@ -261,6 +410,7 @@ export class LocalSmartDb {
     await LocalSmartDb.cleanStaleSockets();
 
     // Run storage migration before starting the Rust engine
+    await assertNoLocalSmartDbStorageRootRelocationWorkspace(this.options.folderPath);
     const migrator = new StorageMigrator(this.options.folderPath);
     await migrator.run();
 

package/ts/ts_local/index.ts

@@ -8,3 +8,12 @@ export type {
   ILocalSmartDbOfflineStringValueInspection,
   TLocalSmartDbOfflineStringValueInspectionResult,
 } from '../ts_smartdb/service-types.js';
+export type {
+  ILocalSmartDbStoppedStorageRootRelocationInput,
+  ILocalSmartDbStoppedStorageRootRelocationReceipt,
+  TLocalSmartDbStorageRootRelocationErrorCode,
+} from '../ts_smartdb/storage-root-relocation.js';
+export {
+  LocalSmartDbStorageRootRelocationError,
+  localSmartDbStorageRootRelocationErrorCodes,
+} from '../ts_smartdb/storage-root-relocation.js';

package/ts/ts_smartdb/index.ts

@@ -81,5 +81,14 @@ export {
   normalizeSmartDbResourceFenceError,
   smartDbResourceFenceErrorCodes,
 } from './service-types.js';
+export type {
+  ILocalSmartDbStoppedStorageRootRelocationInput,
+  ILocalSmartDbStoppedStorageRootRelocationReceipt,
+  TLocalSmartDbStorageRootRelocationErrorCode,
+} from './storage-root-relocation.js';
+export {
+  LocalSmartDbStorageRootRelocationError,
+  localSmartDbStorageRootRelocationErrorCodes,
+} from './storage-root-relocation.js';
 export type { TSmartDbEffectivePayloadInputV1 } from './resource-fencing.js';
 export { createSmartDbEffectivePayloadSha256V1 } from './resource-fencing.js';

package/ts/ts_smartdb/plugins.ts

@@ -1,8 +1,10 @@
 // node native scope
 import * as buffer from 'node:buffer';
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 
-export { buffer, crypto };
+export { buffer, crypto, fs, path };
 
 // @push.rocks scope
 import * as smartrust from '@push.rocks/smartrust';

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

@@ -11,6 +11,11 @@ import {
   normalizeLocalSmartDbOfflineInspectionInput,
   validateSmartDbManagementOperationOptions,
 } from './offline-inspection.js';
+import {
+  normalizeLocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationInput,
+  type ILocalSmartDbStoppedStorageRootRelocationReceipt,
+} from './storage-root-relocation.js';
 import type {
   ISmartDbHealth,
   ISmartDbDatabaseTenantInput,
@@ -180,6 +185,10 @@ type TOfflinePhysicalNamespaceInspectionCommandParams = {
 } & ILocalSmartDbOfflinePhysicalNamespaceInspection['limits'];
 
 type TSmartDbCommands = {
+  relocateStoppedStorageRoot: {
+    params: ILocalSmartDbStoppedStorageRootRelocationInput;
+    result: ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  };
   inspectOfflinePhysicalNamespaces: {
     params: TOfflinePhysicalNamespaceInspectionCommandParams;
     result: ILocalSmartDbOfflinePhysicalNamespaceInspectionResult;
@@ -276,6 +285,10 @@ type TSmartDbCommands = {
   };
 };
 
+export const rustDbBridgeStorageRootRelocation = Symbol(
+  'smartdb.internal.storage-root-relocation',
+);
+
 export type TAuthMetadataPermissionTransitionStatus =
   | 'not-present'
   | 'already-target'
@@ -557,6 +570,19 @@ export class RustDbBridge extends EventEmitter {
 
   // --- Convenience methods for each management command ---
 
+  public async [rustDbBridgeStorageRootRelocation](
+    inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+    optionsArg?: ISmartDbManagementOperationOptions,
+  ): Promise<ILocalSmartDbStoppedStorageRootRelocationReceipt> {
+    const input = normalizeLocalSmartDbStoppedStorageRootRelocationInput(inputArg);
+    validateSmartDbManagementOperationOptions(optionsArg);
+    return await this.bridge.sendCommand(
+      'relocateStoppedStorageRoot',
+      input,
+      optionsArg,
+    ) as ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  }
+
   public async inspectOfflinePhysicalNamespaces(
     inputArg: ILocalSmartDbOfflinePhysicalNamespaceInspection,
     optionsArg?: ISmartDbManagementOperationOptions,

package/ts/ts_smartdb/server/SmartdbServer.ts

@@ -8,6 +8,7 @@ import {
   StorageMigrator,
 } from '../../ts_migration/index.js';
 import { validateSmartDbManagementOperationOptions } from '../offline-inspection.js';
+import { assertNoLocalSmartDbStorageRootRelocationWorkspace } from '../storage-root-relocation.js';
 import type {
   IOpLogEntry,
   IOpLogResult,
@@ -226,6 +227,8 @@ export class SmartdbServer {
       checkpoint();
       // Run storage migration for file-based storage before starting Rust engine
       if (this.options.storage === 'file' && this.options.storagePath) {
+        await assertNoLocalSmartDbStorageRootRelocationWorkspace(this.options.storagePath);
+        checkpoint();
         const migrator = new StorageMigrator(this.options.storagePath);
         await migrator.run(startupAbortController.signal);
         checkpoint();

package/ts/ts_smartdb/storage-root-relocation.ts

@@ -0,0 +1,277 @@
+import * as plugins from './plugins.js';
+
+export const localSmartDbStorageRootRelocationErrorCodes = [
+  'INVALID_REQUEST',
+  'UNSUPPORTED',
+  'BUSY',
+  'NOT_FOUND',
+  'DESTINATION_CONFLICT',
+  'IDENTITY_MISMATCH',
+  'STATE_CORRUPT',
+  'IO',
+  'RECOVERY_REQUIRED',
+] as const;
+
+export type TLocalSmartDbStorageRootRelocationErrorCode =
+  (typeof localSmartDbStorageRootRelocationErrorCodes)[number];
+
+export interface ILocalSmartDbStoppedStorageRootRelocationInput {
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  relocationId: string;
+}
+
+export interface ILocalSmartDbStoppedStorageRootRelocationReceipt {
+  format: 'smartdb.storage-root-relocation.receipt.v1';
+  version: 1;
+  relocationId: string;
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  providerRootId: string;
+  storageRootDevice: string;
+  storageRootInode: string;
+  receiptSha256: string;
+  sourceReceiptRetained: true;
+}
+
+export class LocalSmartDbStorageRootRelocationError extends Error {
+  public readonly code: TLocalSmartDbStorageRootRelocationErrorCode;
+
+  public constructor(codeArg: TLocalSmartDbStorageRootRelocationErrorCode) {
+    super(`SmartDB stopped storage-root relocation failed with code ${codeArg}`);
+    this.name = 'LocalSmartDbStorageRootRelocationError';
+    this.code = codeArg;
+  }
+}
+
+const relocationInputKeys = [
+  'sourceFolderPath',
+  'destinationFolderPath',
+  'relocationId',
+] as const;
+const relocationReceiptKeys = [
+  'format',
+  'version',
+  'relocationId',
+  'sourceFolderPath',
+  'destinationFolderPath',
+  'providerRootId',
+  'storageRootDevice',
+  'storageRootInode',
+  'receiptSha256',
+  'sourceReceiptRetained',
+] as const;
+const maximumFolderPathBytes = 4095;
+const maximumRelocationIdBytes = 256;
+const maximumU64Decimal = '18446744073709551615';
+const receiptDigestDomain = 'smartdb.storage-root-relocation.receipt.v1\0';
+
+const relocationError = (
+  codeArg: TLocalSmartDbStorageRootRelocationErrorCode,
+): LocalSmartDbStorageRootRelocationError =>
+  new LocalSmartDbStorageRootRelocationError(codeArg);
+
+const isPlainExactDataObject = (
+  valueArg: unknown,
+  keysArg: readonly string[],
+): valueArg is Record<string, unknown> => {
+  if (
+    typeof valueArg !== 'object'
+    || valueArg === null
+    || Array.isArray(valueArg)
+    || Object.getPrototypeOf(valueArg) !== Object.prototype
+  ) {
+    return false;
+  }
+  const ownKeys = Reflect.ownKeys(valueArg);
+  if (
+    ownKeys.length !== keysArg.length
+    || ownKeys.some((keyArg) => typeof keyArg !== 'string' || !keysArg.includes(keyArg))
+  ) {
+    return false;
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(valueArg);
+  return keysArg.every((keyArg) => {
+    const descriptor = descriptors[keyArg];
+    return descriptor !== undefined
+      && descriptor.enumerable
+      && Object.prototype.hasOwnProperty.call(descriptor, 'value');
+  });
+};
+
+const isValidUnicodeScalarString = (valueArg: string): boolean => {
+  for (let index = 0; index < valueArg.length; index++) {
+    const code = valueArg.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = valueArg.charCodeAt(index + 1);
+      if (next < 0xdc00 || next > 0xdfff) return false;
+      index++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const isNestedPath = (parentArg: string, childArg: string): boolean => {
+  const relative = plugins.path.relative(parentArg, childArg);
+  return relative !== ''
+    && relative !== '..'
+    && !relative.startsWith(`..${plugins.path.sep}`)
+    && !plugins.path.isAbsolute(relative);
+};
+
+const normalizeFolderPath = (valueArg: unknown): string => {
+  if (
+    typeof valueArg !== 'string'
+    || !plugins.path.isAbsolute(valueArg)
+    || !isValidUnicodeScalarString(valueArg)
+    || [...valueArg].some(characterArg => /\p{Cc}/u.test(characterArg))
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const initialBytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+  if (initialBytes < 1 || initialBytes > maximumFolderPathBytes) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const normalized = plugins.path.resolve(valueArg);
+  const normalizedBytes = plugins.buffer.Buffer.byteLength(normalized, 'utf8');
+  if (
+    normalizedBytes < 1
+    || normalizedBytes > maximumFolderPathBytes
+    || plugins.path.parse(normalized).root === normalized
+    || !isValidUnicodeScalarString(normalized)
+    || [...normalized].some(characterArg => /\p{Cc}/u.test(characterArg))
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  return normalized;
+};
+
+export const normalizeLocalSmartDbStoppedStorageRootRelocationInput = (
+  inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+): ILocalSmartDbStoppedStorageRootRelocationInput => {
+  if (!isPlainExactDataObject(inputArg, relocationInputKeys)) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  const sourceFolderPath = normalizeFolderPath(inputArg.sourceFolderPath);
+  const destinationFolderPath = normalizeFolderPath(inputArg.destinationFolderPath);
+  const sourceFolderPathBytes = plugins.buffer.Buffer.byteLength(sourceFolderPath, 'utf8');
+  const destinationFolderPathBytes = plugins.buffer.Buffer.byteLength(destinationFolderPath, 'utf8');
+  if (
+    sourceFolderPath === destinationFolderPath
+    || isNestedPath(sourceFolderPath, destinationFolderPath)
+    || isNestedPath(destinationFolderPath, sourceFolderPath)
+    || destinationFolderPathBytes > sourceFolderPathBytes
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  if (
+    typeof inputArg.relocationId !== 'string'
+    || plugins.buffer.Buffer.byteLength(inputArg.relocationId, 'utf8') > maximumRelocationIdBytes
+    || !/^[A-Za-z0-9][A-Za-z0-9._:@-]*$/.test(inputArg.relocationId)
+  ) {
+    throw relocationError('INVALID_REQUEST');
+  }
+  return {
+    sourceFolderPath,
+    destinationFolderPath,
+    relocationId: inputArg.relocationId,
+  };
+};
+
+const receiptDigest = (
+  receiptArg: Omit<ILocalSmartDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>,
+): string => plugins.crypto
+  .createHash('sha256')
+  .update(receiptDigestDomain, 'utf8')
+  .update(JSON.stringify(receiptArg), 'utf8')
+  .digest('hex');
+
+const isCanonicalU64Decimal = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string'
+  && /^(?:0|[1-9][0-9]{0,19})$/.test(valueArg)
+  && (valueArg.length < 20 || valueArg <= maximumU64Decimal);
+
+const isLowercaseSha256 = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^[0-9a-f]{64}$/.test(valueArg);
+
+export const normalizeLocalSmartDbStoppedStorageRootRelocationReceipt = (
+  valueArg: unknown,
+  inputArg: ILocalSmartDbStoppedStorageRootRelocationInput,
+): ILocalSmartDbStoppedStorageRootRelocationReceipt => {
+  if (!isPlainExactDataObject(valueArg, relocationReceiptKeys)) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  const receipt = valueArg as unknown as ILocalSmartDbStoppedStorageRootRelocationReceipt;
+  if (
+    receipt.format !== 'smartdb.storage-root-relocation.receipt.v1'
+    || receipt.version !== 1
+    || receipt.relocationId !== inputArg.relocationId
+    || receipt.sourceFolderPath !== inputArg.sourceFolderPath
+    || receipt.destinationFolderPath !== inputArg.destinationFolderPath
+    || !isLowercaseSha256(receipt.providerRootId)
+    || !isCanonicalU64Decimal(receipt.storageRootDevice)
+    || !isCanonicalU64Decimal(receipt.storageRootInode)
+    || !isLowercaseSha256(receipt.receiptSha256)
+    || receipt.sourceReceiptRetained !== true
+  ) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  const withoutDigest = {
+    format: receipt.format,
+    version: receipt.version,
+    relocationId: receipt.relocationId,
+    sourceFolderPath: receipt.sourceFolderPath,
+    destinationFolderPath: receipt.destinationFolderPath,
+    providerRootId: receipt.providerRootId,
+    storageRootDevice: receipt.storageRootDevice,
+    storageRootInode: receipt.storageRootInode,
+    sourceReceiptRetained: receipt.sourceReceiptRetained,
+  } satisfies Omit<ILocalSmartDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>;
+  if (receiptDigest(withoutDigest) !== receipt.receiptSha256) {
+    throw relocationError('RECOVERY_REQUIRED');
+  }
+  return { ...withoutDigest, receiptSha256: receipt.receiptSha256 };
+};
+
+export const assertNoLocalSmartDbStorageRootRelocationWorkspace = async (
+  storagePathArg: string,
+): Promise<void> => {
+  const storagePath = plugins.path.resolve(storagePathArg);
+  const internalPath = plugins.path.join(storagePath, '.__rustdb_internal');
+  const workspacePath = plugins.path.join(internalPath, 'storage-root-relocation');
+  try {
+    const storage = await plugins.fs.stat(storagePath);
+    if (!storage.isDirectory()) {
+      throw new Error('not a directory');
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  try {
+    const internal = await plugins.fs.lstat(internalPath);
+    if (internal.isSymbolicLink() || !internal.isDirectory()) {
+      throw new Error('not a safe directory');
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  try {
+    await plugins.fs.lstat(workspacePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new Error('SmartDB storage-root relocation workspace inspection is ambiguous');
+  }
+  throw new Error('SmartDB storage-root relocation recovery must complete before startup');
+};
+
+export const isLocalSmartDbStorageRootRelocationErrorCode = (
+  valueArg: unknown,
+): valueArg is TLocalSmartDbStorageRootRelocationErrorCode =>
+  typeof valueArg === 'string'
+  && localSmartDbStorageRootRelocationErrorCodes.includes(
+    valueArg as TLocalSmartDbStorageRootRelocationErrorCode,
+  );