@lossless.org/nosqldb 8.0.0

package/ts/ts_nosqldb/classes.storagerehearsal.ts

@@ -0,0 +1,109 @@
+import { RustDbBridge, rustDbBridgeStorageRehearsal } from './rust-db-bridge.js';
+import type { INoSqlDbManagementOperationOptions } from './service-types.js';
+import {
+  normalizeNoSqlDbStorageRehearsalInput, normalizeNoSqlDbStorageRehearsalReceipt,
+  normalizeNoSqlDbStorageRehearsalOptions, normalizeNoSqlDbStorageRehearsalOperationOptions,
+  NoSqlDbStorageRehearsalError, noSqlDbStorageRehearsalErrorCodes,
+  type INoSqlDbStorageRehearsalInput, type INoSqlDbStorageRehearsalOptions,
+  type INoSqlDbStorageRehearsalReceipt, type TNoSqlDbStorageRehearsalErrorCode,
+} from './storage-rehearsal.js';
+
+/** Owns one offline rehearsal sidecar at a time. Separate instances are independent;
+ * native root ownership excludes concurrent use of a source or destination. */
+export class NoSqlDbStorageRehearsal {
+  private readonly binaryPath: string | undefined;
+  private bridge: RustDbBridge | undefined;
+  private cancellation: AbortController | undefined;
+  private completion: Promise<void> | undefined;
+
+  public constructor(options: INoSqlDbStorageRehearsalOptions = {}) {
+    this.binaryPath = normalizeNoSqlDbStorageRehearsalOptions(options).binaryPath;
+  }
+
+  /** Create or exactly retry a rehearsal. The default deadline is one hour,
+   * including spawn and the operation; maximum 24 hours. Cleanup confirms exit
+   * before this method settles. Retry the identical request after interruption. */
+  public async createDestination(inputArg: INoSqlDbStorageRehearsalInput,
+    optionsArg?: INoSqlDbManagementOperationOptions): Promise<INoSqlDbStorageRehearsalReceipt> {
+    let input: ReturnType<typeof normalizeNoSqlDbStorageRehearsalInput>;
+    try { input = normalizeNoSqlDbStorageRehearsalInput(inputArg); }
+    catch { throw new NoSqlDbStorageRehearsalError('INVALID_REQUEST'); }
+    const options = normalizeNoSqlDbStorageRehearsalOperationOptions(optionsArg);
+    const { timeoutMs } = options;
+    if (options.signal?.aborted) throw new NoSqlDbStorageRehearsalError('CANCELLED');
+    if (process.platform !== 'linux' && process.platform !== 'darwin') throw new NoSqlDbStorageRehearsalError('UNSUPPORTED');
+    if (this.completion) throw new NoSqlDbStorageRehearsalError('BUSY');
+    const deadline = performance.now() + timeoutMs;
+    const controller = new AbortController();
+    this.cancellation = controller;
+    const cancel = () => controller.abort();
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    let complete!: () => void;
+    this.completion = new Promise<void>((resolve) => { complete = resolve; });
+    let dispatched = false;
+    let receipt: INoSqlDbStorageRehearsalReceipt | undefined;
+    let failure: NoSqlDbStorageRehearsalError | undefined;
+    const remaining = () => {
+      const timeout = Math.ceil(deadline - performance.now());
+      if (timeout <= 0 || controller.signal.aborted) throw new NoSqlDbStorageRehearsalError(dispatched ? 'RECOVERY_REQUIRED' : 'CANCELLED');
+      return timeout;
+    };
+    try {
+      // A failed previous cleanup keeps its bridge here until exit is confirmed.
+      await this.terminateBridge();
+      remaining();
+      const bridge = new RustDbBridge({ binaryPath: this.binaryPath });
+      this.bridge = bridge;
+      if (!await bridge.spawn({ timeoutMs: remaining(), signal: controller.signal })) {
+        throw new NoSqlDbStorageRehearsalError('BINARY_UNAVAILABLE');
+      }
+      const commandTimeout = remaining();
+      dispatched = true;
+      const result = await bridge[rustDbBridgeStorageRehearsal](input, {
+        timeoutMs: commandTimeout, signal: controller.signal,
+      });
+      receipt = normalizeNoSqlDbStorageRehearsalReceipt(result, input);
+    } catch (error) {
+      if (error instanceof NoSqlDbStorageRehearsalError) failure = error;
+      else {
+        const nativeCode = error instanceof Error && 'responseErrorCode' in error ? error.responseErrorCode : undefined;
+        const code: TNoSqlDbStorageRehearsalErrorCode = typeof nativeCode === 'string'
+          && (noSqlDbStorageRehearsalErrorCodes as readonly string[]).includes(nativeCode)
+          ? nativeCode as TNoSqlDbStorageRehearsalErrorCode
+          : dispatched ? 'RECOVERY_REQUIRED' : controller.signal.aborted || performance.now() >= deadline ? 'CANCELLED' : 'BINARY_UNAVAILABLE';
+        failure = new NoSqlDbStorageRehearsalError(code);
+      }
+    } finally {
+      try { await this.terminateBridge(); }
+      catch { failure = new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED'); }
+      options.signal?.removeEventListener('abort', cancel);
+      this.cancellation = undefined;
+      this.completion = undefined;
+      complete();
+    }
+    if (failure) throw failure;
+    if (!receipt) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+    return receipt;
+  }
+
+  /** Cancel active work and confirm sidecar exit. Retry this method if cleanup
+   * reports RECOVERY_REQUIRED; the instance retains unconfirmed ownership. */
+  public async stop(): Promise<void> {
+    const completion = this.completion;
+    this.cancellation?.abort();
+    let failure: unknown;
+    try { await this.terminateBridge(); } catch (error) { failure = error; }
+    await completion;
+    if (failure) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+  }
+
+  private async terminateBridge(): Promise<void> {
+    const bridge = this.bridge;
+    if (!bridge) return;
+    try {
+      await bridge.terminate({ gracePeriodMs: 0 });
+      if (!bridge.ownershipReleased) throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED');
+      if (this.bridge === bridge) this.bridge = undefined;
+    } catch { throw new NoSqlDbStorageRehearsalError('RECOVERY_REQUIRED'); }
+  }
+}

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

@@ -0,0 +1,33 @@
+import {
+  normalizeNoSqlDbFileStorageStartup,
+  type TNoSqlDbFileStorageStartup,
+} from './file-storage-startup.js';
+
+interface IFileStorageOptions {
+  storage?: string;
+  fileStorageStartup?: unknown;
+  auth?: { users?: unknown };
+}
+
+/** Pure, instance-local admission for the sole native serving engine. */
+export const normalizeNoSqlDbFileStorageOptions = (optionsArg: IFileStorageOptions): {
+  fileStorageStartup: TNoSqlDbFileStorageStartup | undefined;
+} => {
+  for (const removed of ['fileStorageEngine', 'persistPath', 'persistIntervalMs']) {
+    if (removed in optionsArg) throw new TypeError(`NoSQLDB ${removed} has been removed; native memory and file storage are selected by storage`);
+  }
+  if (optionsArg.auth && 'usersPath' in optionsArg.auth) {
+    throw new TypeError('NoSQLDB auth.usersPath has been removed; authentication is stored in the native database');
+  }
+  const storage = optionsArg.storage ?? 'memory';
+  if (storage !== 'file' && storage !== 'memory') throw new TypeError('NoSQLDB storage must be "memory" or "file"');
+  if (process.platform !== 'linux' && process.platform !== 'darwin') {
+    throw new TypeError('NoSQLDB native storage requires Linux or macOS');
+  }
+  if (optionsArg.fileStorageStartup !== undefined && storage !== 'file') {
+    throw new TypeError('NoSQLDB fileStorageStartup requires storage: "file"');
+  }
+  return {
+    fileStorageStartup: storage === 'file' ? normalizeNoSqlDbFileStorageStartup(optionsArg.fileStorageStartup) : undefined,
+  };
+};

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

@@ -0,0 +1,9 @@
+/** Native format admission is read-only until the engine owns the file root. */
+export type TNoSqlDbFileStorageStartup = 'current-format-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');
+};

package/ts/ts_nosqldb/index.ts

@@ -0,0 +1,104 @@
+// NoSQLDB - Wire protocol compatible embedded database server
+export { NoSqlDbStorageRehearsal } from './classes.storagerehearsal.js';
+export { NoSqlDbStorageRehearsalError, noSqlDbStorageRehearsalErrorCodes } from './storage-rehearsal.js';
+export type {
+  INoSqlDbStorageRehearsalOptions, INoSqlDbStorageRehearsalInput,
+  INoSqlDbStorageRehearsalReceipt, INoSqlDbStorageRehearsalPreservation,
+  TNoSqlDbStorageRehearsalErrorCode,
+} from './storage-rehearsal.js';
+
+// Export server (the main entry point for using NoSQLDB)
+export { NoSqlDbServer } from './server/classes.nosqldbserver.js';
+export type { TNoSqlDbFileStorageStartup } from './file-storage-startup.js';
+export type {
+  INoSqlDbAuthOptions,
+  INoSqlDbAuthUser,
+  INoSqlDbOplogOptions,
+  INoSqlDbServerOptions,
+  INoSqlDbTlsOptions,
+} from './server/classes.nosqldbserver.js';
+
+// Export bridge for advanced usage and its fail-stop ownership error.
+export {
+  RustDbBridge,
+  NoSqlDbManagementOperationTerminationError,
+} from './rust-db-bridge.js';
+
+// Export oplog / debug types
+export type {
+  IRustDbBridgeOptions,
+  INoSqlDbQueryOptions,
+  IOpLogEntry,
+  IOpLogResult,
+  IOpLogStats,
+  IRevertResult,
+  ICollectionInfo,
+  IDocumentsResult,
+  INoSqlDbMetrics,
+} from './rust-db-bridge.js';
+
+// Export service API types
+export type {
+  INoSqlDbHealth,
+  INoSqlDbResourceFence,
+  INoSqlDbResourceFenceReceipt,
+  INoSqlDbHeldPublicationReceipt,
+  INoSqlDbCommitDatabasePublicationInput,
+  INoSqlDbManagementOperationOptions,
+  INoSqlDbDatabaseResourceFenceState,
+  INoSqlDbDatabaseAllocationIdentity,
+  INoSqlDbDatabaseAllocationLifecycle,
+  INoSqlDbDatabaseAllocationReadAccessGrantIdentity,
+  INoSqlDbIssueDatabaseAllocationReadAccessGrantInput,
+  INoSqlDbIssueDatabaseAllocationReadAccessGrantResult,
+  INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput,
+  INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult,
+  ILocalNoSqlDbOfflineInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult,
+  ILocalNoSqlDbOfflineStringValueInspection,
+  TLocalNoSqlDbOfflineStringValueInspectionResult,
+  TNoSqlDbCommitDatabasePublicationResult,
+  TNoSqlDbResourceFenceErrorCode,
+  TNoSqlDbAllocationReadAccessGrantErrorCode,
+  INoSqlDbDatabaseTenantInput,
+  INoSqlDbAttestDatabaseTenantInput,
+  INoSqlDbAttestDatabaseTenantResult,
+  INoSqlDbEnsureDatabaseTenantInput,
+  INoSqlDbEnsureDatabaseTenantResult,
+  INoSqlDbAllocateDatabaseTenantInput,
+  INoSqlDbAllocateDatabaseTenantResult,
+  INoSqlDbDeleteDatabaseTenantInput,
+  INoSqlDbRotateDatabaseTenantPasswordInput,
+  INoSqlDbDatabaseTenantDescriptor,
+  INoSqlDbDeleteDatabaseTenantResult,
+  INoSqlDbDatabaseExportCollection,
+  INoSqlDbDatabaseExport,
+  INoSqlDbDatabaseExportLimits,
+  INoSqlDbExportDatabaseInput,
+  INoSqlDbDatabaseContentDigestLimits,
+  INoSqlDbGetDatabaseContentDigestInput,
+  INoSqlDbDatabaseContentDigest,
+  INoSqlDbImportDatabaseInput,
+  INoSqlDbImportDatabaseResult,
+} from './service-types.js';
+export {
+  NoSqlDbAllocationReadAccessGrantError,
+  normalizeNoSqlDbAllocationReadAccessGrantError,
+  noSqlDbAllocationReadAccessGrantErrorCodes,
+  NoSqlDbResourceFenceError,
+  normalizeNoSqlDbResourceFenceError,
+  noSqlDbResourceFenceErrorCodes,
+} from './service-types.js';
+export type {
+  ILocalNoSqlDbStoppedStorageRootRelocationInput,
+  ILocalNoSqlDbStoppedStorageRootRelocationReceipt,
+  TLocalNoSqlDbStorageRootRelocationErrorCode,
+} from './storage-root-relocation.js';
+export {
+  LocalNoSqlDbStorageRootRelocationError,
+  localNoSqlDbStorageRootRelocationErrorCodes,
+} from './storage-root-relocation.js';
+export type { TNoSqlDbEffectivePayloadInputV1 } from './resource-fencing.js';
+export { createNoSqlDbEffectivePayloadSha256V1 } from './resource-fencing.js';

package/ts/ts_nosqldb/offline-inspection.ts

@@ -0,0 +1,375 @@
+import * as plugins from './plugins.js';
+import type {
+  ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+  ILocalNoSqlDbOfflineStringValueInspection,
+  INoSqlDbManagementOperationOptions,
+} from './service-types.js';
+
+export const localNoSqlDbOfflineInspectionBounds = {
+  maximumFolderPathBytes: 4095,
+  maximumNamespaceComponentBytes: 255,
+  maximumFieldNameBytes: 255,
+  maximumMatchValueBytes: 1024 * 1024,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  maximumTimeoutMs: 2_147_483_647,
+  limits: {
+    maximumEntries: { minimum: 1, maximum: 100_000 },
+    maximumTotalFileBytes: { minimum: 1, maximum: 1024 ** 4 },
+    maximumRecords: { minimum: 1, maximum: 1_000_000_000 },
+    maximumRecordBytes: { minimum: 5, maximum: 16 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 1, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
+export const localNoSqlDbOfflinePhysicalNamespaceInspectionBounds = {
+  maximumFolderPathBytes: 4095,
+  maximumRequestBytes: 2 * 1024 * 1024,
+  limits: {
+    maximumDatabases: { minimum: 1, maximum: 1_000_000 },
+    maximumCollections: { minimum: 1, maximum: 1_000_000 },
+    maximumIndexes: { minimum: 1, maximum: 1_000_000 },
+    maximumEntries: { minimum: 1, maximum: 100_000 },
+    maximumTotalFileBytes: { minimum: 1, maximum: 1024 * 1024 * 1024 * 1024 },
+    maximumRecordsPerCollection: { minimum: 1, maximum: 1_000_000_000 },
+    maximumRecordBytes: { minimum: 5, maximum: 16 * 1024 * 1024 },
+    maximumResultBytes: { minimum: 32, maximum: 16 * 1024 * 1024 },
+  },
+} as const;
+
+const inputKeys = new Set([
+  'folderPath',
+  'databaseName',
+  'collectionName',
+  'match',
+  'valueField',
+  'limits',
+]);
+const matchKeys = new Set(['field', 'value']);
+const limitKeys = [
+  'maximumEntries',
+  'maximumTotalFileBytes',
+  'maximumRecords',
+  'maximumRecordBytes',
+  'maximumResultBytes',
+] as const;
+const limitKeySet = new Set<string>(limitKeys);
+const requestStructuralBytes = plugins.buffer.Buffer.byteLength(
+  '{"folderPath":,"databaseName":,"collectionName":,"match":{"field":,"value":},"valueField":,"limits":{"maximumEntries":,"maximumTotalFileBytes":,"maximumRecords":,"maximumRecordBytes":,"maximumResultBytes":}}',
+  'utf8',
+);
+const requestEnvelopeBytes = plugins.buffer.Buffer.byteLength(
+  '{"id":"req_9007199254740991","method":"inspectOfflineStringValue","params":}',
+  'utf8',
+);
+
+const physicalNamespaceInputKeys = new Set(['folderPath', 'limits']);
+const physicalNamespaceLimitKeys = [
+  'maximumDatabases',
+  'maximumCollections',
+  'maximumIndexes',
+  'maximumEntries',
+  'maximumTotalFileBytes',
+  'maximumRecordsPerCollection',
+  'maximumRecordBytes',
+  'maximumResultBytes',
+] as const;
+const physicalNamespaceLimitKeySet = new Set<string>(physicalNamespaceLimitKeys);
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+const requirePhysicalNamespacePlainObject = (
+  valueArg: unknown,
+  allowedKeysArg: Set<string>,
+  labelArg: string,
+): Record<string, unknown> => {
+  if (!isRecord(valueArg)) {
+    throw new TypeError(
+      `LocalNoSqlDb offline physical namespace inspection ${labelArg} must be a plain object`,
+    );
+  }
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(
+        `LocalNoSqlDb offline physical namespace inspection ${labelArg} contains unknown key '${key}'`,
+      );
+    }
+  }
+  if (Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError(
+      `LocalNoSqlDb offline physical namespace inspection ${labelArg} must be a plain object`,
+    );
+  }
+  for (const key of allowedKeysArg) {
+    if (!Object.prototype.propertyIsEnumerable.call(valueArg, key)) {
+      throw new TypeError(
+        `LocalNoSqlDb offline physical namespace inspection ${labelArg} must contain own enumerable key '${key}'`,
+      );
+    }
+  }
+  return valueArg;
+};
+
+const rejectUnknownEnumerableKeys = (
+  valueArg: object,
+  allowedKeysArg: Set<string>,
+  labelArg: string,
+): void => {
+  for (const key in valueArg) {
+    if (!allowedKeysArg.has(key)) {
+      throw new TypeError(`LocalNoSqlDb offline inspection ${labelArg} contains unknown key '${key}'`);
+    }
+  }
+};
+
+const encodedJsonStringBytes = (valueArg: string): number => {
+  let bytes = 2;
+  for (let index = 0; index < valueArg.length; index++) {
+    const code = valueArg.charCodeAt(index);
+    if (
+      code === 0x22
+      || code === 0x5c
+      || code === 0x08
+      || code === 0x09
+      || code === 0x0a
+      || code === 0x0c
+      || code === 0x0d
+    ) {
+      bytes += 2;
+    } else if (code <= 0x1f) {
+      bytes += 6;
+    } else if (code <= 0x7f) {
+      bytes += 1;
+    } else if (code <= 0x7ff) {
+      bytes += 2;
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = valueArg.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index++;
+      } else {
+        bytes += 6;
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      bytes += 6;
+    } else {
+      bytes += 3;
+    }
+  }
+  return bytes;
+};
+
+const validateString = (
+  valueArg: unknown,
+  labelArg: string,
+  minimumBytesArg: number,
+  maximumBytesArg: number,
+  rejectControlsArg: boolean,
+): void => {
+  if (typeof valueArg !== 'string') {
+    throw new TypeError(`LocalNoSqlDb offline inspection ${labelArg} must be a string`);
+  }
+  const bytes = plugins.buffer.Buffer.byteLength(valueArg, 'utf8');
+  if (bytes < minimumBytesArg || bytes > maximumBytesArg) {
+    throw new RangeError(
+      `LocalNoSqlDb offline inspection ${labelArg} must be between ${minimumBytesArg} and ${maximumBytesArg} UTF-8 bytes`,
+    );
+  }
+  if (rejectControlsArg) {
+    for (const character of valueArg) {
+      if (/\p{Cc}/u.test(character)) {
+        throw new TypeError(
+          `LocalNoSqlDb offline inspection ${labelArg} must not contain control characters`,
+        );
+      }
+    }
+  }
+};
+
+export const normalizeLocalNoSqlDbOfflineInspectionInput = (
+  inputArg: ILocalNoSqlDbOfflineStringValueInspection,
+): ILocalNoSqlDbOfflineStringValueInspection => {
+  if (!isRecord(inputArg as unknown)) {
+    throw new TypeError('LocalNoSqlDb offline inspection input must be an object');
+  }
+  rejectUnknownEnumerableKeys(inputArg, inputKeys, 'input');
+  const inputRecord = inputArg as unknown as Record<string, unknown>;
+  const match = inputRecord.match;
+  if (!isRecord(match)) {
+    throw new TypeError('LocalNoSqlDb offline inspection match must be an object');
+  }
+  rejectUnknownEnumerableKeys(match, matchKeys, 'match');
+  const limits = inputRecord.limits;
+  if (!isRecord(limits)) {
+    throw new TypeError('LocalNoSqlDb offline inspection limits must be an object');
+  }
+  rejectUnknownEnumerableKeys(limits, limitKeySet, 'limits');
+
+  const normalized = {
+    folderPath: inputRecord.folderPath,
+    databaseName: inputRecord.databaseName,
+    collectionName: inputRecord.collectionName,
+    match: {
+      field: match.field,
+      value: match.value,
+    },
+    valueField: inputRecord.valueField,
+    limits: {
+      maximumEntries: limits.maximumEntries,
+      maximumTotalFileBytes: limits.maximumTotalFileBytes,
+      maximumRecords: limits.maximumRecords,
+      maximumRecordBytes: limits.maximumRecordBytes,
+      maximumResultBytes: limits.maximumResultBytes,
+    },
+  } as unknown as ILocalNoSqlDbOfflineStringValueInspection;
+
+  const bounds = localNoSqlDbOfflineInspectionBounds;
+  validateString(normalized.folderPath, 'folderPath', 1, bounds.maximumFolderPathBytes, true);
+  for (const [label, value] of [
+    ['databaseName', normalized.databaseName],
+    ['collectionName', normalized.collectionName],
+  ] as const) {
+    validateString(value, label, 1, bounds.maximumNamespaceComponentBytes, true);
+    if (value === '.' || value === '..' || value.includes('/') || value.includes('\\')) {
+      throw new TypeError(
+        `LocalNoSqlDb offline inspection ${label} must be one canonical path component`,
+      );
+    }
+  }
+  validateString(normalized.match.field, 'match.field', 1, bounds.maximumFieldNameBytes, true);
+  validateString(normalized.valueField, 'valueField', 1, bounds.maximumFieldNameBytes, true);
+  validateString(
+    normalized.match.value,
+    'match.value',
+    0,
+    bounds.maximumMatchValueBytes,
+    false,
+  );
+
+  for (const key of limitKeys) {
+    const value = normalized.limits[key];
+    const range = bounds.limits[key as keyof typeof bounds.limits];
+    if (!Number.isSafeInteger(value) || value < range.minimum || value > range.maximum) {
+      throw new RangeError(
+        `LocalNoSqlDb offline inspection limits.${key} must be a safe integer between ${range.minimum} and ${range.maximum}`,
+      );
+    }
+  }
+  if (plugins.buffer.Buffer.byteLength(normalized.match.value, 'utf8') > normalized.limits.maximumRecordBytes) {
+    throw new RangeError(
+      'LocalNoSqlDb offline inspection match.value must not exceed limits.maximumRecordBytes',
+    );
+  }
+
+  let requestBytes = 32 // Reserve the optional native deadline field.
+    + requestEnvelopeBytes
+    + requestStructuralBytes
+    + encodedJsonStringBytes(normalized.folderPath)
+    + encodedJsonStringBytes(normalized.databaseName)
+    + encodedJsonStringBytes(normalized.collectionName)
+    + encodedJsonStringBytes(normalized.match.field)
+    + encodedJsonStringBytes(normalized.match.value)
+    + encodedJsonStringBytes(normalized.valueField);
+  for (const key of limitKeys) {
+    requestBytes += String(normalized.limits[key]).length;
+  }
+  if (requestBytes > bounds.maximumRequestBytes) {
+    throw new RangeError(
+      `LocalNoSqlDb offline inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
+export const normalizeLocalNoSqlDbOfflinePhysicalNamespaceInspectionInput = (
+  inputArg: ILocalNoSqlDbOfflinePhysicalNamespaceInspection,
+): ILocalNoSqlDbOfflinePhysicalNamespaceInspection => {
+  const inputRecord = requirePhysicalNamespacePlainObject(
+    inputArg,
+    physicalNamespaceInputKeys,
+    'input',
+  );
+  const limits = requirePhysicalNamespacePlainObject(
+    inputRecord.limits,
+    physicalNamespaceLimitKeySet,
+    'limits',
+  );
+  const normalized: ILocalNoSqlDbOfflinePhysicalNamespaceInspection = {
+    folderPath: inputRecord.folderPath as string,
+    limits: {
+      maximumDatabases: limits.maximumDatabases as number,
+      maximumCollections: limits.maximumCollections as number,
+      maximumIndexes: limits.maximumIndexes as number,
+      maximumEntries: limits.maximumEntries as number,
+      maximumTotalFileBytes: limits.maximumTotalFileBytes as number,
+      maximumRecordsPerCollection: limits.maximumRecordsPerCollection as number,
+      maximumRecordBytes: limits.maximumRecordBytes as number,
+      maximumResultBytes: limits.maximumResultBytes as number,
+    },
+  };
+  const bounds = localNoSqlDbOfflinePhysicalNamespaceInspectionBounds;
+  if (typeof normalized.folderPath !== 'string') {
+    throw new TypeError(
+      'LocalNoSqlDb offline physical namespace inspection folderPath must be a string',
+    );
+  }
+  const folderPathBytes = plugins.buffer.Buffer.byteLength(normalized.folderPath, 'utf8');
+  if (folderPathBytes < 1 || folderPathBytes > bounds.maximumFolderPathBytes) {
+    throw new RangeError(
+      `LocalNoSqlDb offline physical namespace inspection folderPath must be between 1 and ${bounds.maximumFolderPathBytes} UTF-8 bytes`,
+    );
+  }
+  for (const character of normalized.folderPath) {
+    if (/\p{Cc}/u.test(character)) {
+      throw new TypeError(
+        'LocalNoSqlDb offline physical namespace inspection folderPath must not contain control characters',
+      );
+    }
+  }
+
+  for (const key of physicalNamespaceLimitKeys) {
+    const value = normalized.limits[key];
+    const range = bounds.limits[key];
+    if (!Number.isSafeInteger(value) || value < range.minimum || value > range.maximum) {
+      throw new RangeError(
+        `LocalNoSqlDb offline physical namespace inspection limits.${key} must be a safe integer between ${range.minimum} and ${range.maximum}`,
+      );
+    }
+  }
+
+  const requestBytes = plugins.buffer.Buffer.byteLength(JSON.stringify({
+    id: 'req_9007199254740991',
+    method: 'inspectOfflinePhysicalNamespaces',
+    params: {
+      folderPath: normalized.folderPath,
+      ...normalized.limits,
+    },
+  }), 'utf8');
+  if (requestBytes > bounds.maximumRequestBytes) {
+    throw new RangeError(
+      `LocalNoSqlDb offline physical namespace inspection request exceeds the ${bounds.maximumRequestBytes}-byte serialized limit`,
+    );
+  }
+  return normalized;
+};
+
+export const validateNoSqlDbManagementOperationOptions = (
+  optionsArg?: INoSqlDbManagementOperationOptions,
+): void => {
+  if (optionsArg === undefined) return;
+  if (!isRecord(optionsArg as unknown)) {
+    throw new TypeError('NoSQLDB management operation options must be an object');
+  }
+  if (
+    optionsArg.timeoutMs !== undefined
+    && (
+      !Number.isSafeInteger(optionsArg.timeoutMs)
+      || optionsArg.timeoutMs <= 0
+      || optionsArg.timeoutMs > localNoSqlDbOfflineInspectionBounds.maximumTimeoutMs
+    )
+  ) {
+    throw new RangeError(
+      `NoSQLDB management operation timeoutMs must be an integer between 1 and ${localNoSqlDbOfflineInspectionBounds.maximumTimeoutMs}`,
+    );
+  }
+};

package/ts/ts_nosqldb/plugins.ts

@@ -0,0 +1,12 @@
+// 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, fs, path };
+
+// @push.rocks scope
+import * as smartrust from '@push.rocks/smartrust';
+
+export { smartrust };