@lossless.org/nosqldb 8.0.0

package/ts/ts_nosqldb/service-types.ts

@@ -0,0 +1,484 @@
+export interface INoSqlDbHealth {
+  running: boolean;
+  storage?: 'memory' | 'file';
+  fileStorageEngine?: 'mvcc';
+  storagePurpose?: 'production' | 'rehearsal';
+  storageRehearsalId?: string | null;
+  storagePath?: string;
+  resourceFencingVersion?: 1;
+  resourceFencingSupported?: boolean;
+  resourceFencingRequiresDrain?: true;
+  allocationFencingVersion?: 1;
+  allocationFencingSupported?: boolean;
+  allocationFencingRequiresDrain?: true;
+  databaseAllocationReadAccessGrantVersion?: 1;
+  databaseAllocationReadAccessGrantSupported?: true;
+  publicationHoldVersion: 1;
+  publicationHoldSupported: boolean;
+  publicationHoldRequiresExternalDrain: boolean;
+  authEnabled?: boolean;
+  authUsers?: number;
+  usersPathConfigured?: boolean;
+  databaseCount: number;
+  collectionCount: number;
+  uptimeSeconds?: number;
+}
+
+/** Per-operation admission bounds for read-only stopped native storage inspection. */
+export interface ILocalNoSqlDbOfflineInspectionLimits {
+  maximumEntries: number;
+  maximumTotalFileBytes: number;
+  maximumRecords: number;
+  maximumRecordBytes: number;
+  maximumResultBytes: number;
+}
+
+export interface ILocalNoSqlDbOfflineStringValueInspection {
+  folderPath: string;
+  databaseName: string;
+  collectionName: string;
+  match: {
+    field: string;
+    value: string;
+  };
+  valueField: string;
+  limits: ILocalNoSqlDbOfflineInspectionLimits;
+}
+
+export type TLocalNoSqlDbOfflineStringValueInspectionResult =
+  | { status: 'not-found' }
+  | { status: 'found'; value: string };
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits {
+  maximumEntries: number;
+  maximumDatabases: number;
+  maximumCollections: number;
+  maximumIndexes: number;
+  maximumTotalFileBytes: number;
+  maximumRecordsPerCollection: number;
+  maximumRecordBytes: number;
+  maximumResultBytes: number;
+}
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspection {
+  folderPath: string;
+  limits: ILocalNoSqlDbOfflinePhysicalNamespaceInspectionLimits;
+}
+
+export interface ILocalNoSqlDbOfflinePhysicalNamespaceInspectionResult {
+  schemaVersion: 1;
+  databases: Array<{
+    name: string;
+    collections: string[];
+  }>;
+}
+
+export const noSqlDbResourceFenceErrorCodes = [
+  'EFENCE_REQUIRED',
+  'EFENCE_STALE',
+  'EFENCE_SCOPE_MISMATCH',
+  'EFENCE_UNSUPPORTED',
+  'EFENCE_MUTATION_MISMATCH',
+  'EFENCE_OWNERSHIP_MISMATCH',
+  'EFENCE_STATE_CORRUPT',
+  'EFENCE_RECEIPT_LIMIT',
+  'EFENCE_BUSY',
+  'EFENCE_PUBLICATION_HELD',
+  'EFENCE_CAPABILITY_MISMATCH',
+  'EFENCE_NOT_HELD',
+  'EALLOCATION_EXPECTED_ABSENT_CONFLICT',
+  'EALLOCATION_REQUIRED',
+  'EALLOCATION_MISMATCH',
+  'EALLOCATION_GENERATION_EXHAUSTED',
+  'EALLOCATION_DEPROVISIONED',
+] as const;
+
+export type TNoSqlDbResourceFenceErrorCode =
+  (typeof noSqlDbResourceFenceErrorCodes)[number];
+
+export interface INoSqlDbResourceFence {
+  version: 1;
+  scopeId: string;
+  token: number;
+  mutationId: string;
+  payloadSha256: string;
+}
+
+export interface INoSqlDbResourceFenceReceipt
+  extends INoSqlDbResourceFence {
+  kind:
+    | 'smartdb.database.replace.v1'
+    | 'smartdb.database.delete.v1'
+    | 'smartdb.database.ensure.v1'
+    | 'smartdb.database.allocate.v1';
+  /** Digest of the canonical payload interpretation derived by NoSQLDB. */
+  effectivePayloadSha256: string;
+  provider?: 'smartdb';
+  resourceIdSha256?: string;
+  holdPublication?: true;
+  publicationState?: 'held' | 'released';
+  bindingSha256?: string;
+  resultSha256?: string;
+  receiptSha256?: string;
+  publicationCapabilitySha256?: string;
+  /** Present only while publication is held; never returned after release. */
+  publicationCapability?: string;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDatabaseAllocationIdentity {
+  version: 1;
+  provider: 'smartdb';
+  state: 'active';
+  databaseName: string;
+  username: string;
+  allocationId: string;
+  generation: number;
+  principalId: string;
+  resourceIdSha256: string;
+  bindingSha256: string;
+  receiptSha256: string;
+}
+
+export interface INoSqlDbDatabaseAllocationLifecycle {
+  version: 1;
+  provider: 'smartdb';
+  state: 'allocating' | 'active' | 'deprovisioning' | 'deprovisioned';
+  databaseName: string;
+  username: string;
+  allocationId: string;
+  generation: number;
+  principalId: string;
+  resourceIdSha256: string;
+  bindingSha256: string;
+  receiptSha256: string;
+}
+
+export interface INoSqlDbDatabaseAllocationReadAccessGrantIdentity {
+  version: 1;
+  grantId: string;
+  principalId: string;
+  generation: number;
+}
+
+export interface INoSqlDbIssueDatabaseAllocationReadAccessGrantInput {
+  databaseName: string;
+  grantId: string;
+  username: string;
+  password: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbIssueDatabaseAllocationReadAccessGrantResult {
+  databaseName: string;
+  username: string;
+  roles: ['read'];
+  authSource: string;
+  mongodbUri?: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+  grant: INoSqlDbDatabaseAllocationReadAccessGrantIdentity;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export interface INoSqlDbRevokeDatabaseAllocationReadAccessGrantInput {
+  databaseName: string;
+  grantId: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbRevokeDatabaseAllocationReadAccessGrantResult {
+  databaseName: string;
+  grantId: string;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+  revoked: true;
+}
+
+export const noSqlDbAllocationReadAccessGrantErrorCodes = [
+  'EGRANT_INVALID_REQUEST',
+  'EGRANT_CREDENTIAL_MISMATCH',
+  'EGRANT_CONFLICT',
+  'EGRANT_REPLAY_CAPACITY',
+  'EGRANT_STATE_UNAVAILABLE',
+] as const;
+
+export type TNoSqlDbAllocationReadAccessGrantErrorCode =
+  (typeof noSqlDbAllocationReadAccessGrantErrorCodes)[number];
+
+export class NoSqlDbAllocationReadAccessGrantError extends Error {
+  public readonly code: TNoSqlDbAllocationReadAccessGrantErrorCode;
+
+  public constructor(
+    codeArg: TNoSqlDbAllocationReadAccessGrantErrorCode,
+    messageArg: string,
+    causeArg?: unknown,
+  ) {
+    super(`${codeArg}: ${messageArg}`, { cause: causeArg });
+    this.name = 'NoSqlDbAllocationReadAccessGrantError';
+    this.code = codeArg;
+  }
+}
+
+export const normalizeNoSqlDbAllocationReadAccessGrantError = (
+  errorArg: unknown,
+  codeArg?: unknown,
+): Error => {
+  const error =
+    errorArg instanceof Error
+      ? errorArg
+      : new Error(String(errorArg));
+  if (
+    typeof codeArg !== 'string'
+    || !noSqlDbAllocationReadAccessGrantErrorCodes.includes(
+      codeArg as TNoSqlDbAllocationReadAccessGrantErrorCode,
+    )
+  ) {
+    return error;
+  }
+  return new NoSqlDbAllocationReadAccessGrantError(
+    codeArg as TNoSqlDbAllocationReadAccessGrantErrorCode,
+    error.message,
+    error,
+  );
+};
+
+export interface INoSqlDbHeldPublicationReceipt
+  extends INoSqlDbResourceFenceReceipt {
+  provider: 'smartdb';
+  resourceIdSha256: string;
+  holdPublication: true;
+  publicationState: 'held';
+  bindingSha256: string;
+  resultSha256: string;
+  receiptSha256: string;
+  publicationCapabilitySha256: string;
+  publicationCapability: string;
+}
+
+export interface INoSqlDbCommitDatabasePublicationInput {
+  databaseName: string;
+  resourceFence: INoSqlDbHeldPublicationReceipt;
+}
+
+/**
+ * Cancellation and deadline ownership for one durable database-management
+ * operation. Aborting or timing out is fail-stop: NoSQLDB terminates the Rust
+ * engine so the operation cannot continue after the caller has released it.
+ */
+export interface INoSqlDbManagementOperationOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface INoSqlDbDatabaseResourceFenceState {
+  version: 1;
+  databaseName: string;
+  resourceIdSha256: string;
+  scopeId: string;
+  highestToken: number;
+  publicationState: 'requested' | 'publishing' | 'held' | 'released';
+  allocation?: INoSqlDbDatabaseAllocationLifecycle;
+}
+
+export class NoSqlDbResourceFenceError extends Error {
+  public readonly code: TNoSqlDbResourceFenceErrorCode;
+
+  public constructor(
+    codeArg: TNoSqlDbResourceFenceErrorCode,
+    messageArg: string,
+    causeArg?: unknown,
+  ) {
+    super(`${codeArg}: ${messageArg}`, { cause: causeArg });
+    this.name = 'NoSqlDbResourceFenceError';
+    this.code = codeArg;
+  }
+}
+
+export const normalizeNoSqlDbResourceFenceError = (
+  errorArg: unknown,
+): Error => {
+  const error =
+    errorArg instanceof Error
+      ? errorArg
+      : new Error(String(errorArg));
+  const match = /^((?:EFENCE|EALLOCATION)_[A-Z_]+):\s*(.*)$/s.exec(error.message);
+  if (
+    !match ||
+    !noSqlDbResourceFenceErrorCodes.includes(
+      match[1] as TNoSqlDbResourceFenceErrorCode,
+    )
+  ) {
+    return error;
+  }
+  return new NoSqlDbResourceFenceError(
+    match[1] as TNoSqlDbResourceFenceErrorCode,
+    match[2],
+    error,
+  );
+};
+
+export interface INoSqlDbDatabaseTenantInput {
+  databaseName: string;
+  username: string;
+  password: string;
+  roles?: string[];
+}
+
+export interface INoSqlDbEnsureDatabaseTenantInput
+  extends INoSqlDbDatabaseTenantInput {
+  fence: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbAttestDatabaseTenantInput {
+  databaseName: string;
+  username: string;
+  roles: string[];
+  password: string;
+}
+
+export interface INoSqlDbAttestDatabaseTenantResult {
+  matches: boolean;
+}
+
+export interface INoSqlDbAllocateDatabaseTenantInput
+  extends INoSqlDbDatabaseTenantInput {
+  expectedAbsent: true;
+  fence: INoSqlDbResourceFence;
+}
+
+export interface INoSqlDbDeleteDatabaseTenantInput {
+  databaseName: string;
+  /**
+   * Exact tenant user to revoke. For a fenced deletion this identity is
+   * included in the durable mutation and is removed idempotently after the
+   * database deletion is durable. Omitting it from a fenced deletion
+   * preserves auth users; an unfenced omission retains the legacy behavior
+   * of deleting every user for the database. If the database exists, a
+   * fenced deletion fails closed unless this exact user currently owns it.
+   */
+  username?: string;
+  fence?: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
+}
+
+export interface INoSqlDbRotateDatabaseTenantPasswordInput {
+  username: string;
+  password: string;
+}
+
+export interface INoSqlDbDatabaseTenantDescriptor {
+  databaseName: string;
+  username: string;
+  roles: string[];
+  authSource: string;
+  mongodbUri?: string;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbEnsureDatabaseTenantResult
+  extends INoSqlDbDatabaseTenantDescriptor {
+  resourceFence: INoSqlDbResourceFenceReceipt;
+}
+
+export interface INoSqlDbAllocateDatabaseTenantResult
+  extends INoSqlDbDatabaseTenantDescriptor {
+  resourceFence: INoSqlDbResourceFenceReceipt;
+  allocation: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDeleteDatabaseTenantResult {
+  databaseName: string;
+  /**
+   * Users removed during the completing attempt. This can be zero after
+   * crash recovery when the exact user was durably removed by the prior
+   * attempt.
+   */
+  deletedUsers: number;
+  databaseDropped: boolean;
+  /**
+   * Present for fenced calls. False means the bound exact username is now
+   * absent; true means no username was supplied and auth users were preserved.
+   */
+  usersPreserved?: boolean;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export interface INoSqlDbDatabaseExportCollection {
+  name: string;
+  documents: Record<string, any>[];
+  indexes: Record<string, any>[];
+}
+
+export interface INoSqlDbDatabaseExportLimits {
+  maxEncodedBytes?: number;
+  maxCollections?: number;
+  maxDocuments?: number;
+  maxIndexes?: number;
+}
+
+export interface INoSqlDbExportDatabaseInput {
+  databaseName: string;
+  limits?: INoSqlDbDatabaseExportLimits;
+}
+
+export interface INoSqlDbDatabaseContentDigestLimits {
+  maxScannedBsonBytes?: number;
+  maxCollections?: number;
+  maxDocuments?: number;
+  maxIndexes?: number;
+}
+
+export interface INoSqlDbGetDatabaseContentDigestInput {
+  databaseName: string;
+  limits?: INoSqlDbDatabaseContentDigestLimits;
+}
+
+export interface INoSqlDbDatabaseContentDigest {
+  format: 'smartdb.database.content-digest.v1';
+  algorithm: 'sha256';
+  databaseName: string;
+  sha256: string;
+  scannedBsonBytes: number;
+  collections: number;
+  documents: number;
+  indexes: number;
+}
+
+export interface INoSqlDbDatabaseExport {
+  format: 'smartdb.database.export.v1';
+  databaseName: string;
+  exportedAtMs: number;
+  collections: INoSqlDbDatabaseExportCollection[];
+}
+
+export interface INoSqlDbImportDatabaseInput {
+  databaseName: string;
+  source: INoSqlDbDatabaseExport;
+  /**
+   * Exact exclusive tenant owner required for this replacement. When used
+   * with a fence, the username is included in the provider-derived mutation
+   * identity. Omission preserves the original version 1 replacement profile.
+   */
+  username?: string;
+  fence?: INoSqlDbResourceFence;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+  /** Keep the database data plane closed until commitDatabasePublication. */
+  holdPublication?: boolean;
+}
+
+export interface INoSqlDbImportDatabaseResult {
+  databaseName: string;
+  collections: number;
+  documents: number;
+  resourceFence?: INoSqlDbResourceFenceReceipt;
+  allocation?: INoSqlDbDatabaseAllocationIdentity;
+}
+
+export type TNoSqlDbCommitDatabasePublicationResult =
+  | INoSqlDbImportDatabaseResult
+  | INoSqlDbDeleteDatabaseTenantResult;

package/ts/ts_nosqldb/storage-rehearsal.ts

@@ -0,0 +1,215 @@
+import * as plugins from './plugins.js';
+import type { INoSqlDbServerOptions } from './server/classes.nosqldbserver.js';
+
+export const noSqlDbStorageRehearsalErrorCodes = [
+  'INVALID_REQUEST', 'UNSUPPORTED', 'BUSY', 'NOT_FOUND', 'DESTINATION_CONFLICT',
+  'IDENTITY_MISMATCH', 'STATE_CORRUPT', 'SOURCE_CHANGED', 'CAPACITY', 'CANCELLED',
+  'IO', 'RECOVERY_REQUIRED', 'BINARY_UNAVAILABLE',
+] as const;
+export type TNoSqlDbStorageRehearsalErrorCode = typeof noSqlDbStorageRehearsalErrorCodes[number];
+
+/** Errors deliberately contain neither persisted values nor nested engine errors. */
+export class NoSqlDbStorageRehearsalError extends Error {
+  public constructor(public readonly code: TNoSqlDbStorageRehearsalErrorCode) {
+    super(`NoSQLDB storage rehearsal failed with code ${code}`);
+    this.name = 'NoSqlDbStorageRehearsalError';
+  }
+}
+
+export interface INoSqlDbStorageRehearsalOptions {
+  /** Exact executable, with SmartRust's exclusive non-mutating selection contract. */
+  binaryPath?: string;
+}
+
+export interface INoSqlDbStorageRehearsalInput {
+  /** Absolute canonical path of an already initialized, stopped source. */
+  sourceFolderPath: string;
+  /** Absent destination; its existing parent must be private and on the source filesystem. */
+  destinationFolderPath: string;
+  /** Optional previously attested provider identity. The engine always verifies source ownership and bindings. */
+  expectedSourceProviderRootId?: string;
+  /** Stable caller operation ID. Every retry must retain the same request. */
+  operationId: string;
+  limits?: {
+    /** Source files plus directories, including the root. Default/maximum: 100,000. */
+    maximumEntries: number;
+    /** Total source file bytes. Default/maximum: 1 TiB. */
+    maximumBytes: number;
+  };
+}
+
+/** Counts include retained historical records separately from live contents. */
+export interface INoSqlDbStorageRehearsalPreservation {
+  files: number;
+  bytes: number;
+  databases: number;
+  collections: number;
+  documents: number;
+  indexes: number;
+  indexAliases: number;
+  users: number;
+  principalIdentities: number;
+  retiredDatabases: number;
+  retiredCollections: number;
+  retiredDocuments: number;
+  retiredIndexes: number;
+  retiredPrincipals: number;
+  allocationReplays: number;
+  resources: number;
+  receipts: number;
+  maximumFencingToken: string;
+  publicationHolds: number;
+  activeAllocations: number;
+  retiredAllocations: number;
+  sessions: number;
+  retiringSessions: number;
+  retryOutcomes: number;
+  transactionOutcomes: number;
+  obsoleteOutcomes: number;
+  records: number;
+  encodedRecordBytes: number;
+}
+
+/** Immutable creation evidence. Completed retries replay this receipt even after isolated writes. */
+export interface INoSqlDbStorageRehearsalReceipt {
+  format: 'smartdb.storage-rehearsal.receipt.v2';
+  operationId: string;
+  requestSha256: string;
+  storageProfile: 'native-mvcc-authenticated-v1';
+  sourceFolderPath: string;
+  destinationFolderPath: string;
+  sourceProviderRootId: string;
+  destinationProviderRootId: string;
+  sourceStorageRootSha256: string;
+  sourceSnapshotSha256: string;
+  destinationDevice: string;
+  destinationInode: string;
+  groupId: string;
+  timelineId: string;
+  sourceLsn: string;
+  destinationLsn: string;
+  sourceRecordsSha256: string;
+  preservedRecordsSha256: string;
+  scramIterations: number;
+  preservation: INoSqlDbStorageRehearsalPreservation;
+  sourceUnchanged: true;
+  contentsAndIndexesPreserved: true;
+  namespacesPreserved: true;
+  authenticationPreserved: true;
+  historicalFencingPreserved: true;
+  outcomesPreserved: true;
+  filesystemBindingsVerified: true;
+  productionAuthority: false;
+  promotionSupported: false;
+  receiptSha256: string;
+}
+
+export type TNormalizedNoSqlDbStorageRehearsalInput = INoSqlDbStorageRehearsalInput & {
+  limits: NonNullable<INoSqlDbStorageRehearsalInput['limits']>;
+};
+
+const fail = (code: TNoSqlDbStorageRehearsalErrorCode = 'INVALID_REQUEST'): never => {
+  throw new NoSqlDbStorageRehearsalError(code);
+};
+const object = (value: unknown): value is Record<string, unknown> => {
+  try {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return false;
+    return Reflect.ownKeys(value).every((key) => {
+      const property = Object.getOwnPropertyDescriptor(value, key);
+      return typeof key === 'string' && property?.enumerable === true && Object.hasOwn(property, 'value');
+    });
+  } catch { return false; }
+};
+const digest = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+const identifier = (value: unknown): value is string => typeof value === 'string'
+  && /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(value);
+const canonicalPath = (value: unknown): value is string => typeof value === 'string'
+  && value.startsWith('/') && value !== '/' && plugins.buffer.Buffer.byteLength(value) <= 4095
+  && !/[\p{Cc}\p{Cs}]/u.test(value) && !value.endsWith('/') && !value.includes('//')
+  && value.split('/').every((part) => part !== '.' && part !== '..' && !part.startsWith('.smartdb-rehearsal-'));
+const integer = (value: unknown, minimum: number, maximum: number): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum && value <= maximum;
+const exactKeys = (value: Record<string, unknown>, required: readonly string[], optional: readonly string[] = []) =>
+  required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+const sha256 = (domain: string, value: unknown) => plugins.crypto.createHash('sha256').update(domain).update(JSON.stringify(value)).digest('hex');
+
+export const normalizeNoSqlDbStorageRehearsalOptions = (value: unknown): INoSqlDbStorageRehearsalOptions => {
+  try {
+    if (!object(value) || !exactKeys(value, [], ['binaryPath'])
+      || (value.binaryPath !== undefined && (typeof value.binaryPath !== 'string' || value.binaryPath.length === 0))) return fail();
+    return { binaryPath: value.binaryPath as string | undefined };
+  } catch { return fail(); }
+};
+
+export const normalizeNoSqlDbStorageRehearsalOperationOptions = (value: unknown): { timeoutMs: number; signal?: AbortSignal } => {
+  try {
+    if (value === undefined) return { timeoutMs: 3_600_000 };
+    if (!object(value) || !exactKeys(value, [], ['timeoutMs', 'signal'])
+      || (value.timeoutMs !== undefined && !integer(value.timeoutMs, 1, 86_400_000))
+      || (value.signal !== undefined && !(value.signal instanceof AbortSignal))) return fail();
+    return { timeoutMs: value.timeoutMs as number | undefined ?? 3_600_000, signal: value.signal as AbortSignal | undefined };
+  } catch { return fail(); }
+};
+
+export const normalizeNoSqlDbStorageRehearsalInput = (value: unknown): TNormalizedNoSqlDbStorageRehearsalInput => {
+  if (!object(value) || !exactKeys(value, ['sourceFolderPath', 'destinationFolderPath', 'operationId'], ['expectedSourceProviderRootId', 'limits'])
+    || !canonicalPath(value.sourceFolderPath) || !canonicalPath(value.destinationFolderPath)
+    || value.sourceFolderPath === value.destinationFolderPath
+    || value.sourceFolderPath.startsWith(`${value.destinationFolderPath}/`)
+    || value.destinationFolderPath.startsWith(`${value.sourceFolderPath}/`)
+    || (value.expectedSourceProviderRootId !== undefined && !digest(value.expectedSourceProviderRootId))
+    || !identifier(value.operationId)) return fail();
+  const limits = value.limits === undefined ? { maximumEntries: 100_000, maximumBytes: 1024 ** 4 } : value.limits;
+  if (!object(limits) || !exactKeys(limits, ['maximumEntries', 'maximumBytes'])
+    || !integer(limits.maximumEntries, 1, 100_000) || !integer(limits.maximumBytes, 1, 1024 ** 4)) return fail();
+  return {
+    sourceFolderPath: value.sourceFolderPath,
+    destinationFolderPath: value.destinationFolderPath,
+    ...(value.expectedSourceProviderRootId === undefined ? {} : { expectedSourceProviderRootId: value.expectedSourceProviderRootId as string }),
+    operationId: value.operationId,
+    limits: { maximumEntries: limits.maximumEntries, maximumBytes: limits.maximumBytes },
+  };
+};
+
+const preservationKeys = ['files', 'bytes', 'databases', 'collections', 'documents', 'indexes', 'indexAliases', 'users', 'principalIdentities', 'retiredDatabases', 'retiredCollections', 'retiredDocuments', 'retiredIndexes', 'retiredPrincipals', 'allocationReplays', 'resources', 'receipts', 'maximumFencingToken', 'publicationHolds', 'activeAllocations', 'retiredAllocations', 'sessions', 'retiringSessions', 'retryOutcomes', 'transactionOutcomes', 'obsoleteOutcomes', 'records', 'encodedRecordBytes'] as const;
+const receiptKeys = ['format', 'operationId', 'requestSha256', 'storageProfile', 'sourceFolderPath', 'destinationFolderPath', 'sourceProviderRootId', 'destinationProviderRootId', 'sourceStorageRootSha256', 'sourceSnapshotSha256', 'destinationDevice', 'destinationInode', 'groupId', 'timelineId', 'sourceLsn', 'destinationLsn', 'sourceRecordsSha256', 'preservedRecordsSha256', 'scramIterations', 'preservation', 'sourceUnchanged', 'contentsAndIndexesPreserved', 'namespacesPreserved', 'authenticationPreserved', 'historicalFencingPreserved', 'outcomesPreserved', 'filesystemBindingsVerified', 'productionAuthority', 'promotionSupported', 'receiptSha256'] as const;
+const unsigned = (value: unknown): value is string => typeof value === 'string'
+  && /^(0|[1-9][0-9]{0,19})$/.test(value) && BigInt(value) <= 0xffff_ffff_ffff_ffffn;
+
+export const normalizeNoSqlDbStorageRehearsalReceipt = (value: unknown, input: TNormalizedNoSqlDbStorageRehearsalInput): INoSqlDbStorageRehearsalReceipt => {
+  if (!object(value) || !exactKeys(value, receiptKeys) || !object(value.preservation)
+    || !exactKeys(value.preservation, preservationKeys)
+    || !preservationKeys.every((key) => key === 'maximumFencingToken'
+      ? unsigned((value.preservation as Record<string, unknown>)[key])
+      : integer((value.preservation as Record<string, unknown>)[key], 0, Number.MAX_SAFE_INTEGER))
+    || value.format !== 'smartdb.storage-rehearsal.receipt.v2' || value.storageProfile !== 'native-mvcc-authenticated-v1'
+    || value.operationId !== input.operationId || value.sourceFolderPath !== input.sourceFolderPath
+    || value.destinationFolderPath !== input.destinationFolderPath
+    || (input.expectedSourceProviderRootId !== undefined && value.sourceProviderRootId !== input.expectedSourceProviderRootId)
+    || !['sourceProviderRootId', 'destinationProviderRootId', 'sourceSnapshotSha256', 'sourceRecordsSha256', 'preservedRecordsSha256', 'receiptSha256'].every((key) => digest(value[key]))
+    || value.sourceProviderRootId === value.destinationProviderRootId
+    || value.sourceStorageRootSha256 !== plugins.crypto.createHash('sha256').update(`${input.sourceFolderPath}/.__rustdb_mvcc/data`).digest('hex')
+    || value.requestSha256 !== sha256('smartdb.storage-rehearsal.request.v2\0', input)
+    || !integer(value.scramIterations, 4096, 0xffff_ffff)
+    || ![value.destinationDevice, value.destinationInode, value.sourceLsn, value.destinationLsn].every(unsigned)
+    || BigInt(value.sourceLsn as string) < 1n || BigInt(value.sourceLsn as string) + 1n !== BigInt(value.destinationLsn as string)
+    || !identifier(value.groupId) || !identifier(value.timelineId)
+    || !['sourceUnchanged', 'contentsAndIndexesPreserved', 'namespacesPreserved', 'authenticationPreserved', 'historicalFencingPreserved', 'outcomesPreserved', 'filesystemBindingsVerified'].every((key) => value[key] === true)
+    || value.productionAuthority !== false || value.promotionSupported !== false) return fail('STATE_CORRUPT');
+  const preservation = Object.fromEntries(preservationKeys.map((key) => [key, (value.preservation as Record<string, unknown>)[key]]));
+  const normalized = Object.fromEntries(receiptKeys.map((key) => [key,
+    key === 'preservation' ? preservation : key === 'receiptSha256' ? '' : value[key]]));
+  if (sha256('smartdb.storage-rehearsal.receipt.v2\0', normalized) !== value.receiptSha256) return fail('STATE_CORRUPT');
+  normalized.receiptSha256 = value.receiptSha256;
+  return normalized as unknown as INoSqlDbStorageRehearsalReceipt;
+};
+
+export const validateNoSqlDbStorageRehearsalStartup = (options: INoSqlDbServerOptions): void => {
+  if (options.storageRehearsalId === undefined) return;
+  if (!identifier(options.storageRehearsalId) || options.storage !== 'file'
+    || (options.fileStorageStartup !== undefined && options.fileStorageStartup !== 'current-format-only') || !canonicalPath(options.storagePath)
+    || !canonicalPath(options.socketPath) || options.socketPath.startsWith(`${options.storagePath}/`)
+    || options.auth?.enabled !== true || (options.auth.users?.length ?? 0) !== 0
+    || !integer(options.auth.scramIterations, 4096, 0xffff_ffff)) return fail();
+};