@lossless.org/client 0.1.0

package/ts/objectstorage/internal.exactpathpurge.operations.ts

@@ -0,0 +1,1936 @@
+import * as plugins from './plugins.js';
+import { ExactPathPurgeError } from './classes.exactpathpurgeerror.js';
+import type {
+  IExactPathPurgeCapabilityProbeOptions,
+  IExactPathPurgeCounts,
+  IExactPathPurgeEvidence,
+  IExactPathPurgeOptions,
+  IExactPathPurgeResult,
+  TExactPathPurgeCapabilityProbeFailureReason,
+  TExactPathPurgeCapabilityProbeResult,
+  TExactPathPurgeFailurePhase,
+  TExactPathPurgeFailureReason,
+  TExactPathPurgeVersioningMode,
+} from './interfaces.js';
+import {
+  beginExactPathPurgeCapabilityOperation,
+  beginExactPathPurgeProbeOperation,
+  mintExactPathPurgeCapability,
+  type IExactPathPurgeOperation,
+  type IExactUploadOperation,
+} from './internal.exactupload.capability.js';
+
+interface IExactPathPurgeBucketRef {
+  name: string;
+  smartbucketRef: {
+    readonly storageClient: plugins.s3.S3Client;
+  };
+}
+
+interface IVersionEntry {
+  type: 'version' | 'delete-marker';
+  versionId: string;
+  etag?: string;
+  size?: number;
+  lastModifiedMs: number;
+  isLatest: boolean;
+}
+
+interface IUnversionedEntry {
+  type: 'unversioned';
+  etag: string;
+  size: number;
+  lastModifiedMs: number;
+}
+
+type TPurgeEntry = IVersionEntry | IUnversionedEntry;
+
+interface IExactPathSnapshot {
+  mode: TExactPathPurgeVersioningMode;
+  entries: TPurgeEntry[];
+  counts: IExactPathPurgeCounts;
+  pagesScanned: number;
+  neighborEntriesObserved: number;
+  identity: string;
+  fingerprint: string;
+}
+
+interface IDeadlineSignal {
+  signal: AbortSignal;
+  didTimeout(): boolean;
+  dispose(): void;
+}
+
+interface IIndependentTaskResult<T> {
+  succeeded: boolean;
+  timedOut: boolean;
+  settlement: Promise<void>;
+  value?: T;
+  cause?: unknown;
+}
+
+interface IVerificationResult {
+  remainingSnapshot: IExactPathSnapshot;
+  verificationScansCompleted: number;
+  pagesScanned: number;
+  neighborEntriesObserved: number;
+  verifiedAt?: string;
+}
+
+class ExactPathInventoryFailure extends Error {
+  constructor(
+    public readonly reason: Extract<
+      TExactPathPurgeFailureReason,
+      | 'malformed-provider-response'
+      | 'inventory-limit-exceeded'
+      | 'concurrent-recreation'
+      | 'versioning-mode-changed'
+    >,
+    messageArg: string,
+    optionsArg?: {
+      cause?: unknown;
+    },
+  ) {
+    super(messageArg, optionsArg);
+    this.name = 'ExactPathInventoryFailure';
+  }
+}
+
+class ExactPathPurgeProbeSemanticError extends Error {
+  constructor(
+    public readonly reason: Extract<
+      TExactPathPurgeCapabilityProbeFailureReason,
+      'conditional-delete-not-enforced' | 'versioning-mode-changed'
+    >,
+    messageArg: string,
+    optionsArg?: {
+      cause?: unknown;
+    },
+  ) {
+    super(messageArg, optionsArg);
+    this.name = 'ExactPathPurgeProbeSemanticError';
+  }
+}
+
+class ExactPathPurgeDeadlineError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'ExactPathPurgeDeadlineError';
+  }
+}
+
+const inventoryMaximumEntries = 10_000;
+const inventoryMaximumPages = 100;
+const inventoryPageSize = 1_000;
+const purgeDefaultTimeoutMs = 30_000;
+const purgeMaximumTimeoutMs = 300_000;
+const probeTimeoutMs = 30_000;
+const reconciliationTimeoutMs = 20_000;
+const emptyCounts = (): IExactPathPurgeCounts => ({
+  unversionedObjects: 0,
+  versions: 0,
+  nullVersions: 0,
+  deleteMarkers: 0,
+});
+
+const createEmptyEvidence = (): IExactPathPurgeEvidence => ({
+  initialCounts: emptyCounts(),
+  remainingCounts: emptyCounts(),
+  inventoryScansCompleted: 0,
+  verificationScansCompleted: 0,
+  pagesScanned: 0,
+  neighborEntriesObserved: 0,
+  deleteRequestsAttempted: 0,
+  deleteRequestsAcknowledged: 0,
+});
+
+const copyCounts = (
+  countsArg: IExactPathPurgeCounts,
+): IExactPathPurgeCounts => ({
+  unversionedObjects: countsArg.unversionedObjects,
+  versions: countsArg.versions,
+  nullVersions: countsArg.nullVersions,
+  deleteMarkers: countsArg.deleteMarkers,
+});
+
+const copyEvidence = (
+  evidenceArg: IExactPathPurgeEvidence,
+): IExactPathPurgeEvidence => ({
+  initialCounts: copyCounts(evidenceArg.initialCounts),
+  remainingCounts: copyCounts(evidenceArg.remainingCounts),
+  initialFingerprint: evidenceArg.initialFingerprint,
+  remainingFingerprint: evidenceArg.remainingFingerprint,
+  inventoryScansCompleted: evidenceArg.inventoryScansCompleted,
+  verificationScansCompleted: evidenceArg.verificationScansCompleted,
+  pagesScanned: evidenceArg.pagesScanned,
+  neighborEntriesObserved: evidenceArg.neighborEntriesObserved,
+  deleteRequestsAttempted: evidenceArg.deleteRequestsAttempted,
+  deleteRequestsAcknowledged: evidenceArg.deleteRequestsAcknowledged,
+  verifiedAt: evidenceArg.verifiedAt,
+});
+
+const getHttpStatus = (errorArg: unknown): number | undefined => {
+  if (typeof errorArg !== 'object' || errorArg === null) {
+    return undefined;
+  }
+  const statusCode = (errorArg as {
+    $metadata?: {
+      httpStatusCode?: unknown;
+    };
+  }).$metadata?.httpStatusCode;
+  return typeof statusCode === 'number' ? statusCode : undefined;
+};
+
+const isHttpStatus = (errorArg: unknown, statusCodeArg: number): boolean => {
+  return getHttpStatus(errorArg) === statusCodeArg;
+};
+
+const requireNonEmptyString = (
+  valueArg: unknown,
+  fieldNameArg: string,
+): string => {
+  if (typeof valueArg !== 'string' || valueArg.length === 0) {
+    throw new ExactPathInventoryFailure(
+      'malformed-provider-response',
+      `${fieldNameArg} must be a non-empty string.`,
+    );
+  }
+  return valueArg;
+};
+
+const requireSafeNonNegativeInteger = (
+  valueArg: unknown,
+  fieldNameArg: string,
+): number => {
+  if (
+    typeof valueArg !== 'number' ||
+    !Number.isSafeInteger(valueArg) ||
+    valueArg < 0
+  ) {
+    throw new ExactPathInventoryFailure(
+      'malformed-provider-response',
+      `${fieldNameArg} must be a non-negative safe integer.`,
+    );
+  }
+  return valueArg;
+};
+
+const requireDateMilliseconds = (
+  valueArg: unknown,
+  fieldNameArg: string,
+): number => {
+  if (!(valueArg instanceof Date) || Number.isNaN(valueArg.getTime())) {
+    throw new ExactPathInventoryFailure(
+      'malformed-provider-response',
+      `${fieldNameArg} must be a valid Date.`,
+    );
+  }
+  return valueArg.getTime();
+};
+
+const requireBoolean = (
+  valueArg: unknown,
+  fieldNameArg: string,
+): boolean => {
+  if (typeof valueArg !== 'boolean') {
+    throw new ExactPathInventoryFailure(
+      'malformed-provider-response',
+      `${fieldNameArg} must be a boolean.`,
+    );
+  }
+  return valueArg;
+};
+
+const createDeadlineSignal = (
+  callerSignalArg: AbortSignal | undefined,
+  timeoutMsArg: number,
+  timeoutMessageArg: string,
+): IDeadlineSignal => {
+  const abortController = new AbortController();
+  let timedOut = false;
+  const abortForCaller = (): void => {
+    abortController.abort(
+      callerSignalArg?.reason ??
+        new Error('The exact-path purge operation was aborted.'),
+    );
+  };
+  callerSignalArg?.addEventListener('abort', abortForCaller, {
+    once: true,
+  });
+  if (callerSignalArg?.aborted) {
+    abortForCaller();
+  }
+  const deadlineTimer = setTimeout(() => {
+    timedOut = true;
+    abortController.abort(
+      new ExactPathPurgeDeadlineError(timeoutMessageArg),
+    );
+  }, timeoutMsArg);
+  let disposed = false;
+  return {
+    signal: abortController.signal,
+    didTimeout(): boolean {
+      return timedOut;
+    },
+    dispose(): void {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      clearTimeout(deadlineTimer);
+      callerSignalArg?.removeEventListener('abort', abortForCaller);
+    },
+  };
+};
+
+const detachedProviderSendSettlements = new WeakMap<
+  AbortSignal,
+  Set<Promise<void>>
+>();
+
+const trackDetachedProviderSend = (
+  signalArg: AbortSignal,
+  settlementArg: Promise<void>,
+): void => {
+  let settlements = detachedProviderSendSettlements.get(signalArg);
+  if (!settlements) {
+    settlements = new Set();
+    detachedProviderSendSettlements.set(signalArg, settlements);
+  }
+  settlements.add(settlementArg);
+  void settlementArg.then(() => {
+    settlements?.delete(settlementArg);
+    if (settlements?.size === 0) {
+      detachedProviderSendSettlements.delete(signalArg);
+    }
+  });
+};
+
+const getDetachedProviderSendSettlement = (
+  signalArg: AbortSignal,
+): Promise<void> | undefined => {
+  const settlements = detachedProviderSendSettlements.get(signalArg);
+  if (!settlements || settlements.size === 0) {
+    return undefined;
+  }
+  return Promise.allSettled([...settlements]).then(() => undefined);
+};
+
+const runIndependentTask = async <T>(
+  taskArg: (signalArg: AbortSignal) => Promise<T>,
+  timeoutMsArg: number,
+  operationArg: IExactUploadOperation,
+): Promise<IIndependentTaskResult<T>> => {
+  const abortController = new AbortController();
+  const deadlineToken = Symbol('exact-path-purge-independent-deadline');
+  let resolveDeadline!: (valueArg: typeof deadlineToken) => void;
+  const deadlineOutcome = new Promise<typeof deadlineToken>((resolveArg) => {
+    resolveDeadline = resolveArg;
+  });
+  const deadlineTimer = setTimeout(() => {
+    const deadlineError = new ExactPathPurgeDeadlineError(
+      `Exact-path purge reconciliation exceeded ${timeoutMsArg}ms.`,
+    );
+    abortController.abort(deadlineError);
+    resolveDeadline(deadlineToken);
+  }, timeoutMsArg);
+  let deadlineDisposed = false;
+  const disposeDeadline = (): void => {
+    if (deadlineDisposed) {
+      return;
+    }
+    deadlineDisposed = true;
+    clearTimeout(deadlineTimer);
+  };
+  let releaseOwnedAbort: () => void;
+  try {
+    releaseOwnedAbort = operationArg.registerOwnedIndependentAbort(
+      abortController,
+      disposeDeadline,
+    );
+  } catch (error) {
+    abortController.abort(error);
+    disposeDeadline();
+    throw error;
+  }
+  const taskOutcome = Promise.resolve()
+    .then(() => taskArg(abortController.signal))
+    .then<
+      { status: 'fulfilled'; value: T },
+      { status: 'rejected'; cause: unknown }
+    >(
+      (valueArg) => ({
+        status: 'fulfilled',
+        value: valueArg,
+      }),
+      (causeArg: unknown) => ({
+        status: 'rejected',
+        cause: causeArg,
+      }),
+    );
+  const settlement = taskOutcome.then(async () => {
+    await getDetachedProviderSendSettlement(abortController.signal);
+  });
+  void settlement.then(() => {
+    releaseOwnedAbort();
+  });
+  try {
+    const outcome = await Promise.race([taskOutcome, deadlineOutcome]);
+    if (outcome === deadlineToken) {
+      return {
+        succeeded: false,
+        timedOut: true,
+        settlement,
+        cause:
+          abortController.signal.reason ??
+          new ExactPathPurgeDeadlineError(
+            'Exact-path purge reconciliation exceeded its deadline.',
+          ),
+      };
+    }
+    if (outcome.status === 'rejected') {
+      return {
+        succeeded: false,
+        timedOut: false,
+        settlement,
+        cause: outcome.cause,
+      };
+    }
+    return {
+      succeeded: true,
+      timedOut: false,
+      settlement,
+      value: outcome.value,
+    };
+  } finally {
+    disposeDeadline();
+  }
+};
+
+const assertSignalActive = (signalArg: AbortSignal): void => {
+  if (signalArg.aborted) {
+    throw (
+      signalArg.reason ??
+      new Error('The exact-path purge operation was aborted.')
+    );
+  }
+};
+
+const sendWithOptionalFence = async <T>(
+  sendArg: () => Promise<T>,
+  assertCurrentArg?: () => void,
+  signalArg?: AbortSignal,
+): Promise<T> => {
+  if (signalArg) {
+    assertSignalActive(signalArg);
+  }
+  assertCurrentArg?.();
+  const sendOutcome = Promise.resolve()
+    .then(() => {
+      if (signalArg) {
+        assertSignalActive(signalArg);
+      }
+      assertCurrentArg?.();
+      return sendArg();
+    })
+    .then<
+      { status: 'fulfilled'; value: T },
+      { status: 'rejected'; cause: unknown }
+    >(
+      (valueArg) => ({
+        status: 'fulfilled',
+        value: valueArg,
+      }),
+      (causeArg: unknown) => ({
+        status: 'rejected',
+        cause: causeArg,
+      }),
+    );
+  let outcome:
+    | Awaited<typeof sendOutcome>
+    | {
+        status: 'aborted';
+      };
+  if (signalArg) {
+    let abortListener: (() => void) | undefined;
+    const abortOutcome = new Promise<{ status: 'aborted' }>((resolveArg) => {
+      abortListener = () => {
+        resolveArg({
+          status: 'aborted',
+        });
+      };
+      signalArg.addEventListener('abort', abortListener, {
+        once: true,
+      });
+      if (signalArg.aborted) {
+        abortListener();
+      }
+    });
+    outcome = await Promise.race([sendOutcome, abortOutcome]);
+    if (abortListener) {
+      signalArg.removeEventListener('abort', abortListener);
+    }
+    if (outcome.status === 'aborted') {
+      trackDetachedProviderSend(
+        signalArg,
+        sendOutcome.then(() => undefined),
+      );
+      assertSignalActive(signalArg);
+      throw new Error('Unreachable exact-path purge abort state.');
+    }
+  } else {
+    outcome = await sendOutcome;
+  }
+  if (outcome.status === 'rejected') {
+    throw outcome.cause;
+  }
+  const output = outcome.value;
+  if (signalArg) {
+    assertSignalActive(signalArg);
+  }
+  assertCurrentArg?.();
+  return output;
+};
+
+const finishOperationAfterOwnedSettlements = (
+  operationArg: IExactUploadOperation,
+  additionalSettlementsArg: Promise<void>[] = [],
+): void => {
+  const detachedProviderSettlement =
+    getDetachedProviderSendSettlement(operationArg.signal);
+  const ownedSettlements = detachedProviderSettlement
+    ? [detachedProviderSettlement, ...additionalSettlementsArg]
+    : additionalSettlementsArg;
+  if (ownedSettlements.length === 0) {
+    operationArg.finish();
+    return;
+  }
+  void Promise.allSettled(ownedSettlements).then(() => {
+    operationArg.finish();
+  });
+};
+
+const readVersioningMode = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<TExactPathPurgeVersioningMode> => {
+  const output = await sendWithOptionalFence(
+    () =>
+      clientArg.send(
+        new plugins.s3.GetBucketVersioningCommand({
+          Bucket: bucketNameArg,
+        }),
+        {
+          abortSignal: signalArg,
+        },
+      ),
+    assertCurrentArg,
+    signalArg,
+  );
+  if (output.Status === undefined) {
+    return 'unversioned';
+  }
+  if (output.Status === 'Enabled') {
+    return 'enabled';
+  }
+  if (output.Status === 'Suspended') {
+    return 'suspended';
+  }
+  throw new ExactPathInventoryFailure(
+    'malformed-provider-response',
+    `Unsupported bucket versioning status '${String(output.Status)}'.`,
+  );
+};
+
+const assertExpectedMode = (
+  actualModeArg: TExactPathPurgeVersioningMode,
+  expectedModeArg: TExactPathPurgeVersioningMode,
+): void => {
+  if (actualModeArg !== expectedModeArg) {
+    throw new ExactPathInventoryFailure(
+      'versioning-mode-changed',
+      `Bucket versioning changed from '${expectedModeArg}' to '${actualModeArg}'.`,
+    );
+  }
+};
+
+const stableEntryToken = (entryArg: TPurgeEntry): string => {
+  if (entryArg.type === 'unversioned') {
+    return 'unversioned';
+  }
+  return `${entryArg.type}:${entryArg.versionId}`;
+};
+
+const canonicalEntry = (entryArg: TPurgeEntry): string => {
+  if (entryArg.type === 'unversioned') {
+    return JSON.stringify([
+      entryArg.type,
+      entryArg.etag,
+      entryArg.size,
+      entryArg.lastModifiedMs,
+    ]);
+  }
+  return JSON.stringify([
+    entryArg.type,
+    entryArg.versionId,
+    entryArg.etag ?? null,
+    entryArg.size ?? null,
+    entryArg.lastModifiedMs,
+    entryArg.isLatest,
+  ]);
+};
+
+const stableEntryIdentity = (entryArg: TPurgeEntry): string => {
+  if (entryArg.type === 'unversioned') {
+    return canonicalEntry(entryArg);
+  }
+  return JSON.stringify([
+    entryArg.type,
+    entryArg.versionId,
+    entryArg.etag ?? null,
+    entryArg.size ?? null,
+    entryArg.lastModifiedMs,
+  ]);
+};
+
+const createSnapshot = (
+  modeArg: TExactPathPurgeVersioningMode,
+  entriesArg: TPurgeEntry[],
+  pagesScannedArg: number,
+  neighborEntriesObservedArg: number,
+): IExactPathSnapshot => {
+  const sortedEntries = [...entriesArg].sort((leftArg, rightArg) => {
+    return stableEntryToken(leftArg).localeCompare(stableEntryToken(rightArg));
+  });
+  const canonicalEntries = sortedEntries.map(canonicalEntry);
+  const identity = JSON.stringify([modeArg, canonicalEntries]);
+  const counts = emptyCounts();
+  for (const entry of sortedEntries) {
+    if (entry.type === 'unversioned') {
+      counts.unversionedObjects++;
+    } else if (entry.type === 'delete-marker') {
+      counts.deleteMarkers++;
+    } else {
+      counts.versions++;
+      if (entry.versionId === 'null') {
+        counts.nullVersions++;
+      }
+    }
+  }
+  return {
+    mode: modeArg,
+    entries: sortedEntries,
+    counts,
+    pagesScanned: pagesScannedArg,
+    neighborEntriesObserved: neighborEntriesObservedArg,
+    identity,
+    fingerprint: plugins.crypto
+      .createHash('sha256')
+      .update(identity)
+      .digest('hex'),
+  };
+};
+
+const validateListTruncation = (
+  isTruncatedArg: unknown,
+  fieldNameArg: string,
+): boolean => {
+  if (
+    isTruncatedArg !== undefined &&
+    typeof isTruncatedArg !== 'boolean'
+  ) {
+    throw new ExactPathInventoryFailure(
+      'malformed-provider-response',
+      `${fieldNameArg} must be a boolean when present.`,
+    );
+  }
+  return isTruncatedArg === true;
+};
+
+const inventoryVersionedExactPath = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  modeArg: Extract<TExactPathPurgeVersioningMode, 'enabled' | 'suspended'>,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<IExactPathSnapshot> => {
+  const entries: IVersionEntry[] = [];
+  const exactEntryTokens = new Set<string>();
+  let keyMarker: string | undefined;
+  let versionIdMarker: string | undefined;
+  let neighborEntriesObserved = 0;
+  let pagesScanned = 0;
+
+  for (
+    let pageNumber = 1;
+    pageNumber <= inventoryMaximumPages;
+    pageNumber++
+  ) {
+    pagesScanned++;
+    const output = await sendWithOptionalFence(
+      () =>
+        clientArg.send(
+          new plugins.s3.ListObjectVersionsCommand({
+            Bucket: bucketNameArg,
+            Prefix: pathArg,
+            KeyMarker: keyMarker,
+            VersionIdMarker: versionIdMarker,
+            MaxKeys: inventoryPageSize,
+          }),
+          {
+            abortSignal: signalArg,
+          },
+        ),
+      assertCurrentArg,
+      signalArg,
+    );
+    if (
+      output.Versions !== undefined &&
+      !Array.isArray(output.Versions)
+    ) {
+      throw new ExactPathInventoryFailure(
+        'malformed-provider-response',
+        'ListObjectVersions Versions must be an array.',
+      );
+    }
+    if (
+      output.DeleteMarkers !== undefined &&
+      !Array.isArray(output.DeleteMarkers)
+    ) {
+      throw new ExactPathInventoryFailure(
+        'malformed-provider-response',
+        'ListObjectVersions DeleteMarkers must be an array.',
+      );
+    }
+
+    for (const version of output.Versions ?? []) {
+      const key = requireNonEmptyString(version.Key, 'ObjectVersion Key');
+      if (!key.startsWith(pathArg)) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `ListObjectVersions returned key '${key}' outside the requested prefix.`,
+        );
+      }
+      const versionId = requireNonEmptyString(
+        version.VersionId,
+        `ObjectVersion '${key}' VersionId`,
+      );
+      if (key !== pathArg) {
+        neighborEntriesObserved++;
+        continue;
+      }
+      if (exactEntryTokens.has(versionId)) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `Object version '${versionId}' was returned more than once.`,
+        );
+      }
+      exactEntryTokens.add(versionId);
+      entries.push({
+        type: 'version',
+        versionId,
+        etag: requireNonEmptyString(
+          version.ETag,
+          `ObjectVersion '${key}' ETag`,
+        ),
+        size: requireSafeNonNegativeInteger(
+          version.Size,
+          `ObjectVersion '${key}' Size`,
+        ),
+        lastModifiedMs: requireDateMilliseconds(
+          version.LastModified,
+          `ObjectVersion '${key}' LastModified`,
+        ),
+        isLatest: requireBoolean(
+          version.IsLatest,
+          `ObjectVersion '${key}' IsLatest`,
+        ),
+      });
+    }
+
+    for (const marker of output.DeleteMarkers ?? []) {
+      const key = requireNonEmptyString(marker.Key, 'DeleteMarker Key');
+      if (!key.startsWith(pathArg)) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `ListObjectVersions returned marker key '${key}' outside the requested prefix.`,
+        );
+      }
+      const versionId = requireNonEmptyString(
+        marker.VersionId,
+        `DeleteMarker '${key}' VersionId`,
+      );
+      if (key !== pathArg) {
+        neighborEntriesObserved++;
+        continue;
+      }
+      if (exactEntryTokens.has(versionId)) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `Delete marker '${versionId}' was returned more than once.`,
+        );
+      }
+      exactEntryTokens.add(versionId);
+      entries.push({
+        type: 'delete-marker',
+        versionId,
+        lastModifiedMs: requireDateMilliseconds(
+          marker.LastModified,
+          `DeleteMarker '${key}' LastModified`,
+        ),
+        isLatest: requireBoolean(
+          marker.IsLatest,
+          `DeleteMarker '${key}' IsLatest`,
+        ),
+      });
+    }
+
+    if (entries.length > inventoryMaximumEntries) {
+      throw new ExactPathInventoryFailure(
+        'inventory-limit-exceeded',
+        `Exact path contains more than ${inventoryMaximumEntries} versions and markers.`,
+      );
+    }
+
+    const isTruncated = validateListTruncation(
+      output.IsTruncated,
+      'ListObjectVersions IsTruncated',
+    );
+    if (!isTruncated) {
+      const latestCount = entries.filter((entryArg) => entryArg.isLatest).length;
+      if (entries.length > 0 && latestCount !== 1) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `Exact version inventory must contain exactly one latest entry, received ${latestCount}.`,
+        );
+      }
+      const nullVersionCount = entries.filter(
+        (entryArg) =>
+          entryArg.type === 'version' && entryArg.versionId === 'null',
+      ).length;
+      if (nullVersionCount > 1) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          'Exact version inventory contains more than one null data version.',
+        );
+      }
+      return createSnapshot(
+        modeArg,
+        entries,
+        pagesScanned,
+        neighborEntriesObserved,
+      );
+    }
+    const nextKeyMarker = requireNonEmptyString(
+      output.NextKeyMarker,
+      'ListObjectVersions NextKeyMarker',
+    );
+    const nextVersionIdMarker =
+      output.NextVersionIdMarker === undefined
+        ? undefined
+        : requireNonEmptyString(
+            output.NextVersionIdMarker,
+            'ListObjectVersions NextVersionIdMarker',
+          );
+    if (
+      nextKeyMarker === keyMarker &&
+      nextVersionIdMarker === versionIdMarker
+    ) {
+      throw new ExactPathInventoryFailure(
+        'malformed-provider-response',
+        'ListObjectVersions pagination did not advance.',
+      );
+    }
+    keyMarker = nextKeyMarker;
+    versionIdMarker = nextVersionIdMarker;
+  }
+
+  throw new ExactPathInventoryFailure(
+    'inventory-limit-exceeded',
+    `Exact version inventory exceeded ${inventoryMaximumPages} pages.`,
+  );
+};
+
+const inventoryUnversionedExactPath = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<IExactPathSnapshot> => {
+  let exactEntry: IUnversionedEntry | undefined;
+  let continuationToken: string | undefined;
+  let neighborEntriesObserved = 0;
+  let pagesScanned = 0;
+
+  for (
+    let pageNumber = 1;
+    pageNumber <= inventoryMaximumPages;
+    pageNumber++
+  ) {
+    pagesScanned++;
+    const output = await sendWithOptionalFence(
+      () =>
+        clientArg.send(
+          new plugins.s3.ListObjectsV2Command({
+            Bucket: bucketNameArg,
+            Prefix: pathArg,
+            ContinuationToken: continuationToken,
+            MaxKeys: inventoryPageSize,
+          }),
+          {
+            abortSignal: signalArg,
+          },
+        ),
+      assertCurrentArg,
+      signalArg,
+    );
+    if (output.Contents !== undefined && !Array.isArray(output.Contents)) {
+      throw new ExactPathInventoryFailure(
+        'malformed-provider-response',
+        'ListObjectsV2 Contents must be an array.',
+      );
+    }
+    for (const object of output.Contents ?? []) {
+      const key = requireNonEmptyString(object.Key, 'Object Key');
+      if (!key.startsWith(pathArg)) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          `ListObjectsV2 returned key '${key}' outside the requested prefix.`,
+        );
+      }
+      if (key !== pathArg) {
+        neighborEntriesObserved++;
+        continue;
+      }
+      if (exactEntry) {
+        throw new ExactPathInventoryFailure(
+          'malformed-provider-response',
+          'ListObjectsV2 returned the exact unversioned key more than once.',
+        );
+      }
+      exactEntry = {
+        type: 'unversioned',
+        etag: requireNonEmptyString(object.ETag, `Object '${key}' ETag`),
+        size: requireSafeNonNegativeInteger(
+          object.Size,
+          `Object '${key}' Size`,
+        ),
+        lastModifiedMs: requireDateMilliseconds(
+          object.LastModified,
+          `Object '${key}' LastModified`,
+        ),
+      };
+    }
+    const isTruncated = validateListTruncation(
+      output.IsTruncated,
+      'ListObjectsV2 IsTruncated',
+    );
+    if (!isTruncated) {
+      return createSnapshot(
+        'unversioned',
+        exactEntry ? [exactEntry] : [],
+        pagesScanned,
+        neighborEntriesObserved,
+      );
+    }
+    const nextContinuationToken = requireNonEmptyString(
+      output.NextContinuationToken,
+      'ListObjectsV2 NextContinuationToken',
+    );
+    if (nextContinuationToken === continuationToken) {
+      throw new ExactPathInventoryFailure(
+        'malformed-provider-response',
+        'ListObjectsV2 pagination did not advance.',
+      );
+    }
+    continuationToken = nextContinuationToken;
+  }
+
+  throw new ExactPathInventoryFailure(
+    'inventory-limit-exceeded',
+    `Exact object inventory exceeded ${inventoryMaximumPages} pages.`,
+  );
+};
+
+const inventoryExactPath = (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  modeArg: TExactPathPurgeVersioningMode,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<IExactPathSnapshot> => {
+  if (modeArg === 'unversioned') {
+    return inventoryUnversionedExactPath(
+      clientArg,
+      bucketNameArg,
+      pathArg,
+      signalArg,
+      assertCurrentArg,
+    );
+  }
+  return inventoryVersionedExactPath(
+    clientArg,
+    bucketNameArg,
+    pathArg,
+    modeArg,
+    signalArg,
+    assertCurrentArg,
+  );
+};
+
+const assertSnapshotUnchanged = (
+  initialSnapshotArg: IExactPathSnapshot,
+  currentSnapshotArg: IExactPathSnapshot,
+): void => {
+  if (
+    initialSnapshotArg.mode !== currentSnapshotArg.mode ||
+    initialSnapshotArg.identity !== currentSnapshotArg.identity
+  ) {
+    throw new ExactPathInventoryFailure(
+      'concurrent-recreation',
+      'The exact path changed between its two pre-delete inventories.',
+    );
+  }
+};
+
+const deleteEntry = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  entryArg: TPurgeEntry,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<void> => {
+  await sendWithOptionalFence(
+    () =>
+      clientArg.send(
+        new plugins.s3.DeleteObjectCommand({
+          Bucket: bucketNameArg,
+          Key: pathArg,
+          VersionId:
+            entryArg.type === 'unversioned'
+              ? undefined
+              : entryArg.versionId,
+          IfMatch:
+            entryArg.type === 'delete-marker'
+              ? undefined
+              : entryArg.etag,
+        }),
+        {
+          abortSignal: signalArg,
+        },
+      ),
+    assertCurrentArg,
+    signalArg,
+  );
+};
+
+const snapshotIsEmpty = (snapshotArg: IExactPathSnapshot): boolean => {
+  return snapshotArg.entries.length === 0;
+};
+
+const classifyRemainingSnapshot = (
+  initialSnapshotArg: IExactPathSnapshot,
+  remainingSnapshotArg: IExactPathSnapshot,
+): 'empty' | 'captured-remains' | 'concurrent-recreation' => {
+  if (snapshotIsEmpty(remainingSnapshotArg)) {
+    return 'empty';
+  }
+  const initialEntries = new Map(
+    initialSnapshotArg.entries.map((entryArg) => [
+      stableEntryToken(entryArg),
+      stableEntryIdentity(entryArg),
+    ]),
+  );
+  for (const remainingEntry of remainingSnapshotArg.entries) {
+    const initialIdentity = initialEntries.get(
+      stableEntryToken(remainingEntry),
+    );
+    if (
+      initialIdentity === undefined ||
+      initialIdentity !== stableEntryIdentity(remainingEntry)
+    ) {
+      return 'concurrent-recreation';
+    }
+  }
+  return 'captured-remains';
+};
+
+const verifyExactPathEmpty = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  expectedModeArg: TExactPathPurgeVersioningMode,
+  signalArg: AbortSignal,
+  assertCurrentArg?: () => void,
+): Promise<IVerificationResult> => {
+  let pagesScanned = 0;
+  let neighborEntriesObserved = 0;
+  let verificationScansCompleted = 0;
+  let remainingSnapshot = createSnapshot(
+    expectedModeArg,
+    [],
+    0,
+    0,
+  );
+  for (let scanNumber = 1; scanNumber <= 2; scanNumber++) {
+    const actualMode = await readVersioningMode(
+      clientArg,
+      bucketNameArg,
+      signalArg,
+      assertCurrentArg,
+    );
+    assertExpectedMode(actualMode, expectedModeArg);
+    remainingSnapshot = await inventoryExactPath(
+      clientArg,
+      bucketNameArg,
+      pathArg,
+      expectedModeArg,
+      signalArg,
+      assertCurrentArg,
+    );
+    verificationScansCompleted++;
+    pagesScanned += remainingSnapshot.pagesScanned;
+    neighborEntriesObserved +=
+      remainingSnapshot.neighborEntriesObserved;
+    if (!snapshotIsEmpty(remainingSnapshot)) {
+      return {
+        remainingSnapshot,
+        verificationScansCompleted,
+        pagesScanned,
+        neighborEntriesObserved,
+      };
+    }
+  }
+  return {
+    remainingSnapshot,
+    verificationScansCompleted,
+    pagesScanned,
+    neighborEntriesObserved,
+    verifiedAt: new Date().toISOString(),
+  };
+};
+
+const createPurgeError = (
+  phaseArg: TExactPathPurgeFailurePhase,
+  reasonArg: TExactPathPurgeFailureReason,
+  pathArg: string,
+  evidenceArg: IExactPathPurgeEvidence,
+  causeArg: unknown,
+  versioningModeArg?: TExactPathPurgeVersioningMode,
+): ExactPathPurgeError => {
+  return new ExactPathPurgeError(
+    {
+      phase: phaseArg,
+      reason: reasonArg,
+      destinationPath: pathArg,
+      versioningMode: versioningModeArg,
+      evidence: copyEvidence(evidenceArg),
+    },
+    causeArg,
+  );
+};
+
+const failureReasonForInventoryError = (
+  errorArg: unknown,
+): TExactPathPurgeFailureReason => {
+  if (errorArg instanceof ExactPathInventoryFailure) {
+    return errorArg.reason;
+  }
+  return 'unavailable';
+};
+
+const cleanupProbePath = async (
+  clientArg: plugins.s3.S3Client,
+  bucketNameArg: string,
+  pathArg: string,
+  expectedModeArg: TExactPathPurgeVersioningMode,
+  signalArg: AbortSignal,
+  assertCurrentArg: () => void,
+): Promise<void> => {
+  const actualMode = await readVersioningMode(
+    clientArg,
+    bucketNameArg,
+    signalArg,
+    assertCurrentArg,
+  );
+  assertExpectedMode(actualMode, expectedModeArg);
+  const snapshot = await inventoryExactPath(
+    clientArg,
+    bucketNameArg,
+    pathArg,
+    expectedModeArg,
+    signalArg,
+    assertCurrentArg,
+  );
+  for (const entry of snapshot.entries) {
+    await sendWithOptionalFence(
+      () =>
+        clientArg.send(
+          new plugins.s3.DeleteObjectCommand({
+            Bucket: bucketNameArg,
+            Key: pathArg,
+            VersionId:
+              entry.type === 'unversioned' ? undefined : entry.versionId,
+          }),
+          {
+            abortSignal: signalArg,
+          },
+        ),
+      assertCurrentArg,
+      signalArg,
+    );
+  }
+  const verification = await verifyExactPathEmpty(
+    clientArg,
+    bucketNameArg,
+    pathArg,
+    expectedModeArg,
+    signalArg,
+    assertCurrentArg,
+  );
+  if (!snapshotIsEmpty(verification.remainingSnapshot)) {
+    throw new Error('The exact-path purge probe key remains after cleanup.');
+  }
+};
+
+const headProbeEntry = async (
+  operationArg: IExactUploadOperation,
+  pathArg: string,
+  entryArg: TPurgeEntry,
+): Promise<string> => {
+  const output = await sendWithOptionalFence(
+    () =>
+      operationArg.client.send(
+        new plugins.s3.HeadObjectCommand({
+          Bucket: operationArg.bucketName,
+          Key: pathArg,
+          VersionId:
+            entryArg.type === 'unversioned'
+              ? undefined
+              : entryArg.versionId,
+        }),
+        {
+          abortSignal: operationArg.signal,
+        },
+      ),
+    () => operationArg.assertCurrent(),
+    operationArg.signal,
+  );
+  return requireNonEmptyString(output.ETag, 'HeadObject ETag');
+};
+
+const assertProbeEntryAbsentByHead = async (
+  operationArg: IExactUploadOperation,
+  pathArg: string,
+  entryArg: TPurgeEntry,
+): Promise<void> => {
+  try {
+    await sendWithOptionalFence(
+      () =>
+        operationArg.client.send(
+          new plugins.s3.HeadObjectCommand({
+            Bucket: operationArg.bucketName,
+            Key: pathArg,
+            VersionId:
+              entryArg.type === 'unversioned'
+                ? undefined
+                : entryArg.versionId,
+          }),
+          {
+            abortSignal: operationArg.signal,
+          },
+        ),
+      () => operationArg.assertCurrent(),
+      operationArg.signal,
+    );
+  } catch (error) {
+    operationArg.assertCurrent();
+    if (isHttpStatus(error, 404)) {
+      return;
+    }
+    throw error;
+  }
+  throw new ExactPathPurgeProbeSemanticError(
+    'conditional-delete-not-enforced',
+    'The correctly deleted probe object is still readable by exact identity.',
+  );
+};
+
+const getSingleProbeDataEntry = (
+  snapshotArg: IExactPathSnapshot,
+): IVersionEntry | IUnversionedEntry => {
+  if (
+    snapshotArg.entries.length !== 1 ||
+    snapshotArg.entries[0].type === 'delete-marker'
+  ) {
+    throw new ExactPathPurgeProbeSemanticError(
+      'conditional-delete-not-enforced',
+      'The purge probe object did not produce exactly one data entry.',
+    );
+  }
+  const entry = snapshotArg.entries[0];
+  if (
+    snapshotArg.mode === 'enabled' &&
+    (
+      entry.type === 'unversioned' ||
+      entry.versionId === 'null'
+    )
+  ) {
+    throw new ExactPathPurgeProbeSemanticError(
+      'conditional-delete-not-enforced',
+      'Enabled versioning did not return a concrete object VersionId.',
+    );
+  }
+  if (
+    snapshotArg.mode === 'suspended' &&
+    (
+      entry.type === 'unversioned' ||
+      entry.versionId !== 'null'
+    )
+  ) {
+    throw new ExactPathPurgeProbeSemanticError(
+      'conditional-delete-not-enforced',
+      'Suspended versioning did not return the current null data version.',
+    );
+  }
+  if (
+    snapshotArg.mode === 'unversioned' &&
+    entry.type !== 'unversioned'
+  ) {
+    throw new ExactPathPurgeProbeSemanticError(
+      'conditional-delete-not-enforced',
+      'Unversioned storage returned a versioned probe entry.',
+    );
+  }
+  return entry;
+};
+
+export const probeExactPathPurgeCapability = async (
+  bucketRefArg: IExactPathPurgeBucketRef,
+  optionsArg: IExactPathPurgeCapabilityProbeOptions,
+): Promise<TExactPathPurgeCapabilityProbeResult> => {
+  const timeoutMs = optionsArg.timeoutMs ?? probeTimeoutMs;
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs <= 0 ||
+    timeoutMs > probeTimeoutMs
+  ) {
+    throw new TypeError(
+      `Exact-path purge probe timeoutMs must be a positive safe integer no greater than ${probeTimeoutMs}.`,
+    );
+  }
+  const deadlineSignal = createDeadlineSignal(
+    optionsArg.signal,
+    timeoutMs,
+    `Exact-path purge capability probe exceeded ${timeoutMs}ms.`,
+  );
+  let operation: IExactUploadOperation;
+  try {
+    operation = beginExactPathPurgeProbeOperation(
+      bucketRefArg,
+      deadlineSignal.signal,
+    );
+  } catch (error) {
+    deadlineSignal.dispose();
+    return {
+      supported: false,
+      reason: deadlineSignal.didTimeout() ? 'timeout' : 'unavailable',
+      cause: error,
+    };
+  }
+
+  const probePath = `.smartbucket-probes/exact-path-purge-v1/${plugins.smartunique.uuid4()}`;
+  let versioningMode: TExactPathPurgeVersioningMode | undefined;
+  let failureReason: TExactPathPurgeCapabilityProbeFailureReason | undefined;
+  let failureCause: unknown;
+
+  try {
+    versioningMode = await readVersioningMode(
+      operation.client,
+      operation.bucketName,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    const putProbeObject = async (): Promise<IExactPathSnapshot> => {
+      await sendWithOptionalFence(
+        () =>
+          operation.client.send(
+            new plugins.s3.PutObjectCommand({
+              Bucket: operation.bucketName,
+              Key: probePath,
+              Body: new Uint8Array([1]),
+              ContentLength: 1,
+              Metadata: {
+                'smartbucket-probe': 'exact-path-purge-v1',
+              },
+            }),
+            {
+              abortSignal: operation.signal,
+            },
+          ),
+        () => operation.assertCurrent(),
+        operation.signal,
+      );
+      const actualMode = await readVersioningMode(
+        operation.client,
+        operation.bucketName,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      if (actualMode !== versioningMode) {
+        throw new ExactPathPurgeProbeSemanticError(
+          'versioning-mode-changed',
+          'Bucket versioning changed during the purge probe.',
+        );
+      }
+      return inventoryExactPath(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        versioningMode!,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+    };
+
+    const initialSnapshot = await putProbeObject();
+    const initialEntry = getSingleProbeDataEntry(initialSnapshot);
+    const impossibleEtag = `"smartbucket-never-match-${plugins.smartunique.uuid4()}"`;
+    try {
+      await sendWithOptionalFence(
+        () =>
+          operation.client.send(
+            new plugins.s3.DeleteObjectCommand({
+              Bucket: operation.bucketName,
+              Key: probePath,
+              VersionId:
+                initialEntry.type === 'unversioned'
+                  ? undefined
+                  : initialEntry.versionId,
+              IfMatch: impossibleEtag,
+            }),
+            {
+              abortSignal: operation.signal,
+            },
+          ),
+        () => operation.assertCurrent(),
+        operation.signal,
+      );
+      throw new ExactPathPurgeProbeSemanticError(
+        'conditional-delete-not-enforced',
+        'The provider accepted a mismatched conditional delete.',
+      );
+    } catch (error) {
+      if (error instanceof ExactPathPurgeProbeSemanticError) {
+        throw error;
+      }
+      operation.assertCurrent();
+      if (!isHttpStatus(error, 412)) {
+        throw error;
+      }
+    }
+    const retainedEtag = await headProbeEntry(
+      operation,
+      probePath,
+      initialEntry,
+    );
+    if (retainedEtag !== initialEntry.etag) {
+      throw new ExactPathPurgeProbeSemanticError(
+        'conditional-delete-not-enforced',
+        'The mismatched conditional delete changed the probe object.',
+      );
+    }
+
+    let correctDeleteCause: unknown;
+    try {
+      await deleteEntry(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        initialEntry,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+    } catch (error) {
+      correctDeleteCause = error;
+    }
+    await assertProbeEntryAbsentByHead(
+      operation,
+      probePath,
+      initialEntry,
+    );
+    const afterCorrectDelete = await inventoryExactPath(
+      operation.client,
+      operation.bucketName,
+      probePath,
+      versioningMode,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    if (!snapshotIsEmpty(afterCorrectDelete)) {
+      throw new ExactPathPurgeProbeSemanticError(
+        'conditional-delete-not-enforced',
+        'The correctly matched conditional delete did not remove the probe object.',
+        {
+          cause: correctDeleteCause,
+        },
+      );
+    }
+
+    if (versioningMode !== 'unversioned') {
+      const markerSourceSnapshot = await putProbeObject();
+      getSingleProbeDataEntry(markerSourceSnapshot);
+      await sendWithOptionalFence(
+        () =>
+          operation.client.send(
+            new plugins.s3.DeleteObjectCommand({
+              Bucket: operation.bucketName,
+              Key: probePath,
+            }),
+            {
+              abortSignal: operation.signal,
+            },
+          ),
+        () => operation.assertCurrent(),
+        operation.signal,
+      );
+      const markerSnapshot = await inventoryExactPath(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        versioningMode,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      const marker = markerSnapshot.entries.find(
+        (entryArg): entryArg is IVersionEntry =>
+          entryArg.type === 'delete-marker' && entryArg.isLatest,
+      );
+      if (!marker) {
+        throw new ExactPathPurgeProbeSemanticError(
+          'conditional-delete-not-enforced',
+          'The provider did not expose the expected delete marker.',
+        );
+      }
+      await deleteEntry(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        marker,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      const dataAfterMarker = await inventoryExactPath(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        versioningMode,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      for (const entry of dataAfterMarker.entries) {
+        await deleteEntry(
+          operation.client,
+          operation.bucketName,
+          probePath,
+          entry,
+          operation.signal,
+          () => operation.assertCurrent(),
+        );
+      }
+      const afterMarkerCleanup = await inventoryExactPath(
+        operation.client,
+        operation.bucketName,
+        probePath,
+        versioningMode,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      if (!snapshotIsEmpty(afterMarkerCleanup)) {
+        throw new ExactPathPurgeProbeSemanticError(
+          'conditional-delete-not-enforced',
+          'Exact delete-marker removal did not empty the probe path.',
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof ExactPathPurgeProbeSemanticError) {
+      failureReason = error.reason;
+    } else if (deadlineSignal.didTimeout()) {
+      failureReason = 'timeout';
+      failureCause = error;
+    } else if (operation.signal.aborted) {
+      failureReason = 'aborted';
+      failureCause = operation.signal.reason;
+    } else {
+      failureReason = 'unavailable';
+      failureCause = error;
+    }
+  }
+
+  deadlineSignal.dispose();
+  const primaryProviderSettlement =
+    getDetachedProviderSendSettlement(operation.signal);
+  if (primaryProviderSettlement) {
+    const deferredCleanup = primaryProviderSettlement
+      .then(async () => {
+        try {
+          operation.assertLifecycleCurrent();
+          if (versioningMode === undefined) {
+            return;
+          }
+          const cleanupResult = await runIndependentTask(
+            (signalArg) =>
+              cleanupProbePath(
+                operation.client,
+                operation.bucketName,
+                probePath,
+                versioningMode!,
+                signalArg,
+                () => operation.assertLifecycleCurrent(),
+            ),
+            reconciliationTimeoutMs,
+            operation,
+          );
+          await cleanupResult.settlement;
+        } catch {
+          // Forced lifecycle detach makes deferred cleanup indeterminate.
+        }
+      })
+      .then(
+        () => undefined,
+        () => undefined,
+      );
+    finishOperationAfterOwnedSettlements(operation, [deferredCleanup]);
+    return {
+      supported: false,
+      reason:
+        failureReason ??
+        (deadlineSignal.didTimeout()
+          ? 'timeout'
+          : operation.signal.aborted
+            ? 'aborted'
+            : 'unavailable'),
+      cause: failureCause ?? operation.signal.reason,
+    };
+  }
+  const cleanupResult =
+    versioningMode === undefined
+      ? {
+          succeeded: true,
+          timedOut: false,
+          settlement: Promise.resolve(),
+        }
+      : await runIndependentTask(
+          (signalArg) =>
+            cleanupProbePath(
+              operation.client,
+              operation.bucketName,
+              probePath,
+              versioningMode!,
+              signalArg,
+              () => operation.assertLifecycleCurrent(),
+            ),
+          reconciliationTimeoutMs,
+          operation,
+        );
+  try {
+    if (!cleanupResult.succeeded) {
+      return {
+        supported: false,
+        reason: 'cleanup-failed',
+        cause: cleanupResult.cause,
+      };
+    }
+    if (failureReason) {
+      return {
+        supported: false,
+        reason: failureReason,
+        cause: failureCause,
+      };
+    }
+    return {
+      supported: true,
+      capability: mintExactPathPurgeCapability(
+        bucketRefArg,
+        operation,
+        versioningMode!,
+      ),
+      versioningMode: versioningMode!,
+    };
+  } catch (error) {
+    return {
+      supported: false,
+      reason: deadlineSignal.didTimeout()
+        ? 'timeout'
+        : operation.signal.aborted
+          ? 'aborted'
+          : 'unavailable',
+      cause: error,
+    };
+  } finally {
+    if (cleanupResult.timedOut) {
+      finishOperationAfterOwnedSettlements(operation, [
+        cleanupResult.settlement,
+      ]);
+    } else {
+      finishOperationAfterOwnedSettlements(operation);
+    }
+  }
+};
+
+export const purgeExactPath = async (
+  bucketRefArg: IExactPathPurgeBucketRef,
+  optionsArg: IExactPathPurgeOptions,
+): Promise<IExactPathPurgeResult> => {
+  if (typeof optionsArg.path !== 'string' || optionsArg.path.length === 0) {
+    throw new TypeError('path must be a non-empty string.');
+  }
+  const timeoutMs = optionsArg.timeoutMs ?? purgeDefaultTimeoutMs;
+  if (
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs <= 0 ||
+    timeoutMs > purgeMaximumTimeoutMs
+  ) {
+    throw new TypeError(
+      `Exact-path purge timeoutMs must be a positive safe integer no greater than ${purgeMaximumTimeoutMs}.`,
+    );
+  }
+  const evidence = createEmptyEvidence();
+  const deadlineSignal = createDeadlineSignal(
+    optionsArg.signal,
+    timeoutMs,
+    `Exact-path purge exceeded ${timeoutMs}ms.`,
+  );
+  let operation: IExactPathPurgeOperation;
+  try {
+    operation = beginExactPathPurgeCapabilityOperation(
+      bucketRefArg,
+      optionsArg.capability,
+      deadlineSignal.signal,
+    );
+  } catch (error) {
+    deadlineSignal.dispose();
+    throw createPurgeError(
+      'capability',
+      deadlineSignal.didTimeout() ? 'timeout' : 'unavailable',
+      optionsArg.path,
+      evidence,
+      error,
+    );
+  }
+
+  let initialSnapshot: IExactPathSnapshot;
+  try {
+    const initialMode = await readVersioningMode(
+      operation.client,
+      operation.bucketName,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    assertExpectedMode(initialMode, operation.versioningMode);
+    initialSnapshot = await inventoryExactPath(
+      operation.client,
+      operation.bucketName,
+      optionsArg.path,
+      operation.versioningMode,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    evidence.inventoryScansCompleted++;
+    evidence.pagesScanned += initialSnapshot.pagesScanned;
+    evidence.neighborEntriesObserved +=
+      initialSnapshot.neighborEntriesObserved;
+    evidence.initialCounts = copyCounts(initialSnapshot.counts);
+    evidence.initialFingerprint = initialSnapshot.fingerprint;
+
+    const consistencyMode = await readVersioningMode(
+      operation.client,
+      operation.bucketName,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    assertExpectedMode(consistencyMode, operation.versioningMode);
+    const consistencySnapshot = await inventoryExactPath(
+      operation.client,
+      operation.bucketName,
+      optionsArg.path,
+      operation.versioningMode,
+      operation.signal,
+      () => operation.assertCurrent(),
+    );
+    evidence.inventoryScansCompleted++;
+    evidence.pagesScanned += consistencySnapshot.pagesScanned;
+    evidence.neighborEntriesObserved +=
+      consistencySnapshot.neighborEntriesObserved;
+    assertSnapshotUnchanged(initialSnapshot, consistencySnapshot);
+    if (snapshotIsEmpty(initialSnapshot)) {
+      evidence.remainingCounts = copyCounts(consistencySnapshot.counts);
+      evidence.remainingFingerprint = consistencySnapshot.fingerprint;
+      evidence.verificationScansCompleted = 2;
+      evidence.verifiedAt = new Date().toISOString();
+      deadlineSignal.dispose();
+      operation.finish();
+      return {
+        destinationPath: optionsArg.path,
+        status: 'already-absent',
+        versioningMode: operation.versioningMode,
+        purgedCounts: copyCounts(initialSnapshot.counts),
+        evidence: copyEvidence(evidence),
+      };
+    }
+  } catch (error) {
+    const phase: TExactPathPurgeFailurePhase =
+      error instanceof ExactPathInventoryFailure &&
+      error.message.includes('changed between')
+        ? 'consistency'
+        : 'inventory';
+    const reason = deadlineSignal.didTimeout()
+      ? 'timeout'
+      : operation.signal.aborted
+        ? 'aborted'
+        : failureReasonForInventoryError(error);
+    deadlineSignal.dispose();
+    finishOperationAfterOwnedSettlements(operation);
+    throw createPurgeError(
+      phase,
+      reason,
+      optionsArg.path,
+      evidence,
+      error,
+      operation.versioningMode,
+    );
+  }
+
+  let deleteCause: unknown;
+  for (const entry of initialSnapshot.entries) {
+    evidence.deleteRequestsAttempted++;
+    try {
+      await deleteEntry(
+        operation.client,
+        operation.bucketName,
+        optionsArg.path,
+        entry,
+        operation.signal,
+        () => operation.assertCurrent(),
+      );
+      evidence.deleteRequestsAcknowledged++;
+    } catch (error) {
+      deleteCause = error;
+      break;
+    }
+  }
+  deadlineSignal.dispose();
+
+  const primaryProviderSettlement =
+    getDetachedProviderSendSettlement(operation.signal);
+  if (primaryProviderSettlement) {
+    finishOperationAfterOwnedSettlements(operation);
+    throw createPurgeError(
+      'delete',
+      deadlineSignal.didTimeout()
+        ? 'timeout'
+        : operation.signal.aborted
+          ? 'aborted'
+          : 'delete-unverified',
+      optionsArg.path,
+      evidence,
+      deleteCause ?? operation.signal.reason,
+      operation.versioningMode,
+    );
+  }
+
+  const verificationResult = await runIndependentTask(
+    (signalArg) =>
+      verifyExactPathEmpty(
+        operation.client,
+        operation.bucketName,
+        optionsArg.path,
+        operation.versioningMode,
+        signalArg,
+        () => operation.assertLifecycleCurrent(),
+      ),
+    reconciliationTimeoutMs,
+    operation,
+  );
+
+  try {
+    if (!verificationResult.succeeded || !verificationResult.value) {
+      throw createPurgeError(
+        'verification',
+        'verification-ambiguous',
+        optionsArg.path,
+        evidence,
+        verificationResult.cause,
+        operation.versioningMode,
+      );
+    }
+    const verification = verificationResult.value;
+    evidence.verificationScansCompleted =
+      verification.verificationScansCompleted;
+    evidence.pagesScanned += verification.pagesScanned;
+    evidence.neighborEntriesObserved +=
+      verification.neighborEntriesObserved;
+    evidence.remainingCounts = copyCounts(
+      verification.remainingSnapshot.counts,
+    );
+    evidence.remainingFingerprint =
+      verification.remainingSnapshot.fingerprint;
+    evidence.verifiedAt = verification.verifiedAt;
+
+    const remainingClassification = classifyRemainingSnapshot(
+      initialSnapshot,
+      verification.remainingSnapshot,
+    );
+    if (
+      remainingClassification === 'concurrent-recreation' ||
+      isHttpStatus(deleteCause, 409) ||
+      isHttpStatus(deleteCause, 412)
+    ) {
+      throw createPurgeError(
+        'verification',
+        'concurrent-recreation',
+        optionsArg.path,
+        evidence,
+        deleteCause,
+        operation.versioningMode,
+      );
+    }
+    if (remainingClassification === 'captured-remains') {
+      const reason: TExactPathPurgeFailureReason = deadlineSignal.didTimeout()
+        ? 'timeout'
+        : operation.signal.aborted
+          ? 'aborted'
+          : 'delete-unverified';
+      throw createPurgeError(
+        'delete',
+        reason,
+        optionsArg.path,
+        evidence,
+        deleteCause,
+        operation.versioningMode,
+      );
+    }
+    return {
+      destinationPath: optionsArg.path,
+      status: 'purged',
+      versioningMode: operation.versioningMode,
+      purgedCounts: copyCounts(initialSnapshot.counts),
+      evidence: copyEvidence(evidence),
+    };
+  } finally {
+    if (verificationResult.timedOut) {
+      finishOperationAfterOwnedSettlements(operation, [
+        verificationResult.settlement,
+      ]);
+    } else {
+      finishOperationAfterOwnedSettlements(operation);
+    }
+  }
+};