@lossless.org/nosqldb 10.10.0 → 10.11.0

package/ts/ts_nosqldb/storage-rehearsal.ts

@@ -1,215 +0,0 @@
-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();
-};

package/ts/ts_nosqldb/storage-root-alignment.ts

@@ -1,176 +0,0 @@
-import * as plugins from './plugins.js';
-import { normalizeLocalNoSqlDbStoppedStorageRootRelocationInput } from './storage-root-relocation.js';
-import {
-  NoSqlDbStoppedOperationError, normalizeStoppedStorageRootInspectionInput,
-  type ILocalNoSqlDbAuditedStorageRoot, type TNoSqlDbStorageRootBindingChange,
-} from './stopped-storage.js';
-
-export interface INoSqlDbStorageRootPins {
-  groupId: string;
-  timelineId: string;
-  lsn: string;
-  recordsSha256: string;
-  providerRootId?: string;
-}
-export interface ILocalNoSqlDbStoppedStorageRootAlignmentInput {
-  folderPath: string;
-  /** Retained immutable receipt in a private existing parent outside the root, on the same filesystem. */
-  receiptPath: string;
-  alignmentId: string;
-  identityPolicy: 'fork';
-  attestLineageNeverFenced: true;
-  expect?: INoSqlDbStorageRootPins;
-  acknowledgeUnverifiedCopy?: true;
-  dryRun?: boolean;
-}
-export interface ILocalNoSqlDbStoppedStorageRootAlignmentReceipt {
-  format: 'smartdb.storage-root-alignment.receipt.v1';
-  status: 'aligned';
-  alignmentId: string;
-  folderPath: string;
-  receiptPath: string;
-  requestSha256: string;
-  previousProviderRootId: string;
-  providerRootId: string;
-  bindingChange: Exclude<TNoSqlDbStorageRootBindingChange, 'none'>;
-  groupId: string;
-  timelineId: string;
-  sourceLsn: string;
-  alignedLsn: string;
-  records: string;
-  sourceRecordsSha256: string;
-  alignedRecordsSha256: string;
-  preservedRecordsSha256: string;
-  pinned: boolean;
-  receiptSha256: string;
-}
-export type TLocalNoSqlDbStoppedStorageRootAlignmentResult =
-  | ILocalNoSqlDbStoppedStorageRootAlignmentReceipt
-  | { status: 'eligible'; inspection: ILocalNoSqlDbAuditedStorageRoot }
-  | { status: 'already-bound'; bindingChange: 'none'; inspection: ILocalNoSqlDbAuditedStorageRoot };
-export interface ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult {
-  status: 'aborted' | 'not-pending';
-  alignmentId: string;
-  folderPath: string;
-  receiptPath: string;
-}
-
-function fail(code: 'INVALID_REQUEST' | 'RECOVERY_REQUIRED'): never { throw new NoSqlDbStoppedOperationError(code); }
-const data = (value: unknown, required: string[], optional: string[] = []): value is Record<string, unknown> => {
-  if (!value || Object.getPrototypeOf(value) !== Object.prototype) return false;
-  const keys = Reflect.ownKeys(value);
-  if (keys.some(key => typeof key !== 'string' || ![...required, ...optional].includes(key))) return false;
-  return required.every(key => keys.includes(key)) && keys.every(key => {
-    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
-    return descriptor.enumerable && 'value' in descriptor;
-  });
-};
-const sha = (value: unknown): value is string => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
-const decimal = (value: unknown): value is string => typeof value === 'string'
-  && /^(0|[1-9][0-9]{0,19})$/.test(value) && BigInt(value) <= 18446744073709551615n;
-const lineage = (value: unknown): value is string => typeof value === 'string' && value.length > 0
-  && plugins.buffer.Buffer.byteLength(value) <= 256 && !/\p{Cc}/u.test(value);
-const digest = (domain: string, payload: unknown[]): string => plugins.crypto.createHash('sha256')
-  .update(domain).update(JSON.stringify(payload)).digest('hex');
-
-export const normalizeStoppedStorageRootAlignmentInput = (
-  value: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
-): ILocalNoSqlDbStoppedStorageRootAlignmentInput => {
-  if (!data(value, ['folderPath', 'receiptPath', 'alignmentId', 'identityPolicy', 'attestLineageNeverFenced'],
-    ['expect', 'acknowledgeUnverifiedCopy', 'dryRun'])) fail('INVALID_REQUEST');
-  try {
-    normalizeStoppedStorageRootInspectionInput({ folderPath: value.folderPath });
-    normalizeStoppedStorageRootInspectionInput({ folderPath: value.receiptPath });
-    normalizeLocalNoSqlDbStoppedStorageRootRelocationInput({ sourceFolderPath: value.folderPath,
-      destinationFolderPath: value.receiptPath, relocationId: value.alignmentId });
-  } catch { fail('INVALID_REQUEST'); }
-  if (value.identityPolicy !== 'fork' || value.attestLineageNeverFenced !== true
-    || (value.dryRun !== undefined && typeof value.dryRun !== 'boolean')) fail('INVALID_REQUEST');
-  let expect: INoSqlDbStorageRootPins | undefined;
-  if (value.expect !== undefined) {
-    const pins = value.expect;
-    if (value.acknowledgeUnverifiedCopy !== undefined || !data(pins, ['groupId', 'timelineId', 'lsn', 'recordsSha256'], ['providerRootId'])
-      || !lineage(pins.groupId) || !lineage(pins.timelineId) || !decimal(pins.lsn) || pins.lsn === '0'
-      || !sha(pins.recordsSha256) || (pins.providerRootId !== undefined && !sha(pins.providerRootId))) fail('INVALID_REQUEST');
-    expect = { groupId: pins.groupId, timelineId: pins.timelineId, lsn: pins.lsn, recordsSha256: pins.recordsSha256,
-      ...(pins.providerRootId === undefined ? {} : { providerRootId: pins.providerRootId }) };
-  } else if (value.acknowledgeUnverifiedCopy !== true) fail('INVALID_REQUEST');
-  return { folderPath: value.folderPath, receiptPath: value.receiptPath, alignmentId: value.alignmentId,
-    identityPolicy: 'fork', attestLineageNeverFenced: true,
-    ...(expect ? { expect } : { acknowledgeUnverifiedCopy: true }), ...(value.dryRun ? { dryRun: true } : {}) };
-};
-export const storageRootAlignmentRequestDigest = (request: ILocalNoSqlDbStoppedStorageRootAlignmentInput): string =>
-  digest('smartdb.storage-root-alignment.request.v1\0', [request.folderPath, request.receiptPath, request.alignmentId,
-    request.identityPolicy, request.attestLineageNeverFenced, request.expect ? [request.expect.groupId,
-      request.expect.timelineId, request.expect.lsn, request.expect.recordsSha256, request.expect.providerRootId ?? null] : null,
-    request.acknowledgeUnverifiedCopy ?? null]);
-
-const receiptFields = ['format', 'status', 'alignmentId', 'folderPath', 'receiptPath', 'requestSha256',
-  'previousProviderRootId', 'providerRootId', 'bindingChange', 'groupId', 'timelineId', 'sourceLsn', 'alignedLsn', 'records',
-  'sourceRecordsSha256', 'alignedRecordsSha256', 'preservedRecordsSha256', 'pinned'] as const;
-
-const eligibleGenerations = (value: unknown): boolean => {
-  if (!data(value, ['manifest', 'onDisk']) || !decimal(value.manifest) || !Array.isArray(value.onDisk)
-    || !value.onDisk.length || !value.onDisk.includes(value.manifest)) return false;
-  const manifest = BigInt(value.manifest);
-  return value.onDisk.every(generation => decimal(generation) && BigInt(generation) <= manifest);
-};
-
-const eligibleInspection = (value: unknown, request: ILocalNoSqlDbStoppedStorageRootAlignmentInput): value is ILocalNoSqlDbAuditedStorageRoot => {
-  if (!data(value, ['status', 'bindingState', 'bindingChange', 'storagePurpose', 'profileSchema', 'providerRootId',
-    'groupId', 'timelineId', 'lsn', 'records', 'recordsSha256', 'recordsWithoutFencingProfileSha256', 'authUsers',
-    'authority', 'generations', 'alignmentEligible', 'reasons', 'physicalAdmissionViolations'])
-    || value.status !== 'audited' || value.alignmentEligible !== true || value.storagePurpose !== 'production'
-    || ![1, 4].includes(value.profileSchema as number) || !sha(value.providerRootId) || !sha(value.recordsSha256)
-    || !sha(value.recordsWithoutFencingProfileSha256) || !lineage(value.groupId) || !lineage(value.timelineId)
-    || !decimal(value.lsn) || value.lsn === '0' || !decimal(value.records) || value.records === '0' || value.authUsers !== '0'
-    || !['none', 'path', 'inode', 'path+inode'].includes(value.bindingChange as string)
-    || value.bindingState !== (value.bindingChange === 'none' ? 'matching' : 'foreign')
-    || !data(value.authority, ['resourceFences', 'receipts', 'publicationHolds', 'activeAllocations', 'retiredAllocations',
-      'allocationReplays', 'activeGrants', 'importStages']) || Object.values(value.authority).some(count => count !== '0')
-    || !eligibleGenerations(value.generations)
-    || !Array.isArray(value.reasons) || value.reasons.length || !Array.isArray(value.physicalAdmissionViolations)
-    || value.physicalAdmissionViolations.length) return false;
-  const pins = request.expect;
-  return !pins || (value.groupId === pins.groupId && value.timelineId === pins.timelineId && value.lsn === pins.lsn
-    && value.recordsSha256 === pins.recordsSha256 && (pins.providerRootId === undefined || value.providerRootId === pins.providerRootId));
-};
-
-export const normalizeStoppedStorageRootAlignmentResult = (value: unknown,
-  request: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
-): TLocalNoSqlDbStoppedStorageRootAlignmentResult => {
-  if (!value || typeof value !== 'object' || !('status' in value)) fail('RECOVERY_REQUIRED');
-  if (value.status === 'eligible' || value.status === 'already-bound') {
-    if (!data(value, value.status === 'eligible' ? ['status', 'inspection'] : ['status', 'inspection', 'bindingChange'])) fail('RECOVERY_REQUIRED');
-    const record = value as Record<string, unknown>;
-    const inspection = record.inspection as ILocalNoSqlDbAuditedStorageRoot;
-    if (!eligibleInspection(inspection, request)
-      || (value.status === 'eligible' && !request.dryRun)
-      || (value.status === 'already-bound' && (record.bindingChange !== 'none' || inspection.bindingState !== 'matching'))) fail('RECOVERY_REQUIRED');
-    return value as unknown as TLocalNoSqlDbStoppedStorageRootAlignmentResult;
-  }
-  if (!data(value, [...receiptFields, 'receiptSha256'])) fail('RECOVERY_REQUIRED');
-  const receipt = value as unknown as ILocalNoSqlDbStoppedStorageRootAlignmentReceipt;
-  if (receipt.format !== 'smartdb.storage-root-alignment.receipt.v1' || receipt.status !== 'aligned'
-    || receipt.alignmentId !== request.alignmentId || receipt.folderPath !== request.folderPath || receipt.receiptPath !== request.receiptPath
-    || receipt.requestSha256 !== storageRootAlignmentRequestDigest(request) || receipt.pinned !== (request.expect !== undefined)
-    || ![receipt.previousProviderRootId, receipt.providerRootId, receipt.sourceRecordsSha256, receipt.alignedRecordsSha256,
-      receipt.preservedRecordsSha256, receipt.receiptSha256].every(sha)
-    || receipt.previousProviderRootId === receipt.providerRootId || !lineage(receipt.groupId) || !lineage(receipt.timelineId)
-    || !['path', 'inode', 'path+inode'].includes(receipt.bindingChange)
-    || !decimal(receipt.sourceLsn) || receipt.sourceLsn === '0' || !decimal(receipt.alignedLsn)
-    || BigInt(receipt.sourceLsn) + 1n !== BigInt(receipt.alignedLsn) || !decimal(receipt.records) || receipt.records === '0'
-    || receipt.receiptSha256 !== digest('smartdb.storage-root-alignment.receipt.v1\0', receiptFields.map(key => receipt[key]))) fail('RECOVERY_REQUIRED');
-  if (request.expect && (receipt.groupId !== request.expect.groupId || receipt.timelineId !== request.expect.timelineId
-    || receipt.sourceLsn !== request.expect.lsn || receipt.sourceRecordsSha256 !== request.expect.recordsSha256
-    || (request.expect.providerRootId !== undefined && receipt.previousProviderRootId !== request.expect.providerRootId))) fail('RECOVERY_REQUIRED');
-  return { ...receipt };
-};
-export const normalizeStoppedStorageRootAlignmentAbortResult = (value: unknown,
-  request: ILocalNoSqlDbStoppedStorageRootAlignmentInput,
-): ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult => {
-  if (!data(value, ['status', 'alignmentId', 'folderPath', 'receiptPath'])
-    || (value.status !== 'aborted' && value.status !== 'not-pending') || value.alignmentId !== request.alignmentId
-    || value.folderPath !== request.folderPath || value.receiptPath !== request.receiptPath) fail('RECOVERY_REQUIRED');
-  return value as unknown as ILocalNoSqlDbStoppedStorageRootAlignmentAbortResult;
-};

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

@@ -1,279 +0,0 @@
-import * as plugins from './plugins.js';
-
-export const localNoSqlDbStorageRootRelocationErrorCodes = [
-  'INVALID_REQUEST',
-  'UNSUPPORTED',
-  'BUSY',
-  'NOT_FOUND',
-  'DESTINATION_CONFLICT',
-  'IDENTITY_MISMATCH',
-  'STATE_CORRUPT',
-  'SOURCE_CHANGED',
-  'CAPACITY',
-  'CANCELLED',
-  'IO',
-  'RECOVERY_REQUIRED',
-] as const;
-
-export type TLocalNoSqlDbStorageRootRelocationErrorCode =
-  (typeof localNoSqlDbStorageRootRelocationErrorCodes)[number];
-
-export interface ILocalNoSqlDbStoppedStorageRootRelocationInput {
-  sourceFolderPath: string;
-  destinationFolderPath: string;
-  relocationId: string;
-}
-
-export interface ILocalNoSqlDbStoppedStorageRootRelocationReceipt {
-  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 LocalNoSqlDbStorageRootRelocationError extends Error {
-  public readonly code: TLocalNoSqlDbStorageRootRelocationErrorCode;
-
-  public constructor(codeArg: TLocalNoSqlDbStorageRootRelocationErrorCode) {
-    super(`NoSQLDB stopped storage-root relocation failed with code ${codeArg}`);
-    this.name = 'LocalNoSqlDbStorageRootRelocationError';
-    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: TLocalNoSqlDbStorageRootRelocationErrorCode,
-): LocalNoSqlDbStorageRootRelocationError =>
-  new LocalNoSqlDbStorageRootRelocationError(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 normalizeLocalNoSqlDbStoppedStorageRootRelocationInput = (
-  inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
-): ILocalNoSqlDbStoppedStorageRootRelocationInput => {
-  if (!isPlainExactDataObject(inputArg, relocationInputKeys)) {
-    throw relocationError('INVALID_REQUEST');
-  }
-  const sourceFolderPath = normalizeFolderPath(inputArg.sourceFolderPath);
-  const destinationFolderPath = normalizeFolderPath(inputArg.destinationFolderPath);
-  if (
-    sourceFolderPath === destinationFolderPath
-    || isNestedPath(sourceFolderPath, destinationFolderPath)
-    || isNestedPath(destinationFolderPath, sourceFolderPath)
-  ) {
-    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<ILocalNoSqlDbStoppedStorageRootRelocationReceipt, '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 normalizeLocalNoSqlDbStoppedStorageRootRelocationReceipt = (
-  valueArg: unknown,
-  inputArg: ILocalNoSqlDbStoppedStorageRootRelocationInput,
-): ILocalNoSqlDbStoppedStorageRootRelocationReceipt => {
-  if (!isPlainExactDataObject(valueArg, relocationReceiptKeys)) {
-    throw relocationError('RECOVERY_REQUIRED');
-  }
-  const receipt = valueArg as unknown as ILocalNoSqlDbStoppedStorageRootRelocationReceipt;
-  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<ILocalNoSqlDbStoppedStorageRootRelocationReceipt, 'receiptSha256'>;
-  if (receiptDigest(withoutDigest) !== receipt.receiptSha256) {
-    throw relocationError('RECOVERY_REQUIRED');
-  }
-  return { ...withoutDigest, receiptSha256: receipt.receiptSha256 };
-};
-
-export const assertNoLocalNoSqlDbStorageRootRelocationWorkspace = async (
-  storagePathArg: string,
-): Promise<void> => {
-  const storagePath = plugins.path.resolve(storagePathArg);
-  const internalPath = plugins.path.join(storagePath, '.__rustdb_internal');
-  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('NoSQLDB 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('NoSQLDB storage-root relocation workspace inspection is ambiguous');
-  }
-  for (const operation of ['relocation', 'alignment'] as const) {
-    const workspacePath = plugins.path.join(internalPath, `storage-root-${operation}`);
-    try {
-      await plugins.fs.lstat(workspacePath);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
-      throw new Error(`NoSQLDB storage-root ${operation} workspace inspection is ambiguous`);
-    }
-    throw new Error(`NoSQLDB storage-root ${operation} recovery must complete before startup`);
-  }
-};
-
-export const isLocalNoSqlDbStorageRootRelocationErrorCode = (
-  valueArg: unknown,
-): valueArg is TLocalNoSqlDbStorageRootRelocationErrorCode =>
-  typeof valueArg === 'string'
-  && localNoSqlDbStorageRootRelocationErrorCodes.includes(
-    valueArg as TLocalNoSqlDbStorageRootRelocationErrorCode,
-  );