@lossless.org/nosqldb 10.11.0 → 11.0.0

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}/.nosqldb-store/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

@@ -0,0 +1,180 @@
+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', 'alignmentEligible', 'reasons', 'physicalAdmissionViolations'], ['generations', 'storageFormat'])
+    || 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')
+    // A format-3 root says so and keeps no generation inventory; any other
+    // report is a paged root's and must carry an eligible one.
+    || !(value.storageFormat === 'format-3'
+      ? !('generations' in value)
+      : !('storageFormat' in value) && 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;
+};