@lossless.org/nosqldb 10.0.0 → 10.2.0

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

@@ -0,0 +1,176 @@
+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

@@ -240,7 +240,6 @@ export const assertNoLocalNoSqlDbStorageRootRelocationWorkspace = async (
 ): 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()) {
@@ -259,13 +258,16 @@ export const assertNoLocalNoSqlDbStorageRootRelocationWorkspace = async (
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
     throw new Error('NoSQLDB 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('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`);
   }
-  throw new Error('NoSQLDB storage-root relocation recovery must complete before startup');
 };
 
 export const isLocalNoSqlDbStorageRootRelocationErrorCode = (