@backblaze-labs/b2-sdk 0.3.0 → 0.4.0

package/dist/sync/download-staging.cjs

@@ -1,3 +1,4 @@
+const require_filesystem_errors = require("./filesystem-errors.cjs");
 const require_path_safety = require("./path-safety.cjs");
 //#region src/sync/download-staging.ts
 /** @internal */
@@ -12,6 +13,9 @@ var MAX_CLEANUP_WARNING_ENTRIES = 3;
 /** @internal */
 var DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024;
 var reapedManagedDirectories = /* @__PURE__ */ new Map();
+var activeManagedDirectoryCreations = /* @__PURE__ */ new Map();
+/** @internal */
+var downloadStagingTestHooks = {};
 /**
 * Checks whether a single path segment matches the SDK-managed staging directory name.
 * @param segment - Candidate path segment.
@@ -32,48 +36,122 @@ function isDownloadStagingDirectorySegment(segment) {
 * @param statForDeviceCheck - Stat function used to verify filesystem devices.
 * @param beforeStagingMarkerWrite - Test hook called before marker creation.
 * @param activityEntryLimit - Maximum entry count inspected for stale staging activity.
+* @param afterManagedStagingMarkerWrite - Test hook called after managed-root marker creation.
 *
-* @returns The resolved staging directory path.
+* @returns The resolved managed and per-run staging directory paths.
 *
 * @internal
 */
-async function createDownloadStagingDirectory(rootRealPath, path, randomUUID, statForDeviceCheck, beforeStagingMarkerWrite, activityEntryLimit = DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT) {
+async function createDownloadStagingDirectory(rootRealPath, path, randomUUID, statForDeviceCheck, beforeStagingMarkerWrite, activityEntryLimit = DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT, afterManagedStagingMarkerWrite) {
 	const { chmod, lstat, mkdir, readdir, realpath, rm } = await import("node:fs/promises");
 	const managedDirectory = path.join(rootRealPath, DOWNLOAD_STAGING_DIRECTORY_NAME);
+	const releaseManagedDirectoryCreation = retainDownloadStagingRootCreation(managedDirectory);
 	try {
-		await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
+		try {
+			await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
+		} catch (err) {
+			if (!require_path_safety.hasErrorCode(err, "EEXIST")) throw err;
+		}
+		if (!(await lstat(managedDirectory)).isDirectory()) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`);
+		const realManagedDirectory = await realpath(managedDirectory);
+		require_path_safety.assertPathInsideRoot(rootRealPath, realManagedDirectory, path);
+		await assertDownloadPathSameDevice(rootRealPath, realManagedDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
+		if (!await isManagedDownloadStagingRoot(realManagedDirectory)) {
+			if ((await readdir(realManagedDirectory)).length > 0 && !await isManagedDownloadStagingRoot(realManagedDirectory)) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`);
+		}
+		await beforeStagingMarkerWrite?.(realManagedDirectory);
+		await writeStagingMarker(realManagedDirectory, path);
+		await afterManagedStagingMarkerWrite?.(realManagedDirectory);
+		/* v8 ignore next -- best-effort chmod */
+		await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
+		await reapStaleDownloadStagingDirectoriesOnce(realManagedDirectory, path, Date.now(), activityEntryLimit);
+		const stagingDirectory = path.join(realManagedDirectory, `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`);
+		await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
+		/* v8 ignore next -- best-effort chmod */
+		await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
+		try {
+			const realStagingDirectory = await realpath(stagingDirectory);
+			require_path_safety.assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path);
+			await assertDownloadPathSameDevice(rootRealPath, realStagingDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
+			await beforeStagingMarkerWrite?.(realStagingDirectory);
+			await writeStagingMarker(realStagingDirectory, path);
+			return {
+				managedDirectory: realManagedDirectory,
+				stagingDirectory: realStagingDirectory
+			};
+		} catch (err) {
+			/* v8 ignore next -- best-effort cleanup */
+			await rm(stagingDirectory, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+			throw err;
+		}
+	} finally {
+		releaseManagedDirectoryCreation();
+	}
+}
+/**
+* Removes the SDK root marker and the now-empty SDK-managed staging root
+* once all per-run `.download` entries are gone.
+* @param rootRealPath - Resolved local sync root path.
+* @param managedDirectory - Resolved SDK-managed staging root path.
+* @param path - Node path module used for platform-specific path operations.
+*
+* @internal
+*/
+async function removeDownloadStagingRootMarkerAndDirectory(rootRealPath, managedDirectory, path) {
+	try {
+		await removeDownloadStagingRootMarkerAndDirectoryCore(rootRealPath, managedDirectory, path);
 	} catch (err) {
-		if (!require_path_safety.hasErrorCode(err, "EEXIST")) throw err;
+		emitCleanupWarning(`failed to remove B2 SDK download staging root: ${require_filesystem_errors.localFilesystemErrorReason(err)}`);
 	}
-	if (!(await lstat(managedDirectory)).isDirectory()) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`);
-	const realManagedDirectory = await realpath(managedDirectory);
+}
+async function removeDownloadStagingRootMarkerAndDirectoryCore(rootRealPath, managedDirectory, path) {
+	const { lstat, readdir, realpath, rmdir, unlink } = await import("node:fs/promises");
+	if (downloadStagingRootCreationIsActive(managedDirectory)) return;
+	const managedStats = await lstat(managedDirectory).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return void 0;
+		throw err;
+	});
+	if (managedStats === void 0 || !managedStats.isDirectory()) return;
+	const realManagedDirectory = await realpath(managedDirectory).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return void 0;
+		throw err;
+	});
+	if (realManagedDirectory === void 0) return;
 	require_path_safety.assertPathInsideRoot(rootRealPath, realManagedDirectory, path);
-	await assertDownloadPathSameDevice(rootRealPath, realManagedDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
-	if (!await isManagedDownloadStagingRoot(realManagedDirectory)) {
-		if ((await readdir(realManagedDirectory)).length > 0 && !await isManagedDownloadStagingRoot(realManagedDirectory)) throw new Error(`unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`);
-	}
-	await beforeStagingMarkerWrite?.(realManagedDirectory);
-	await writeStagingMarker(realManagedDirectory, path);
-	/* v8 ignore next -- best-effort chmod */
-	await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
-	await reapStaleDownloadStagingDirectoriesOnce(realManagedDirectory, path, Date.now(), activityEntryLimit);
-	const stagingDirectory = path.join(realManagedDirectory, `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`);
-	await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE });
-	/* v8 ignore next -- best-effort chmod */
-	await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {});
+	if (downloadStagingRootCreationIsActive(realManagedDirectory)) return;
+	const markerPath = path.join(realManagedDirectory, DOWNLOAD_STAGING_MARKER_NAME);
+	if ((await lstat(markerPath).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return void 0;
+		throw err;
+	}))?.isFile() !== true) return;
+	await downloadStagingTestHooks.afterCleanupMarkerStat?.(realManagedDirectory);
+	const entries = await readdir(realManagedDirectory, { withFileTypes: true }).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return void 0;
+		throw err;
+	});
+	if (entries === void 0) return;
+	if (entries.length !== 1 || entries[0]?.name !== ".b2sdk-staging-marker.partial") return;
+	if (await realpath(managedDirectory).catch(() => void 0) !== realManagedDirectory) return;
+	if (downloadStagingRootCreationIsActive(realManagedDirectory)) return;
+	await downloadStagingTestHooks.beforeCleanupMarkerUnlink?.(markerPath);
+	if (!await unlink(markerPath).then(() => true).catch((err) => {
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return false;
+		throw err;
+	})) return;
 	try {
-		const realStagingDirectory = await realpath(stagingDirectory);
-		require_path_safety.assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path);
-		await assertDownloadPathSameDevice(rootRealPath, realStagingDirectory, statForDeviceCheck, "unsafe local destination path: cannot stage download across filesystems");
-		await beforeStagingMarkerWrite?.(realStagingDirectory);
-		await writeStagingMarker(realStagingDirectory, path);
-		return realStagingDirectory;
+		await rmdir(realManagedDirectory);
 	} catch (err) {
-		/* v8 ignore next -- best-effort cleanup */
-		await rm(stagingDirectory, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		if (require_path_safety.hasErrorCode(err, "ENOENT")) return;
+		if (require_path_safety.hasErrorCode(err, "ENOTEMPTY") || require_path_safety.hasErrorCode(err, "EEXIST")) {
+			await restoreDownloadStagingRootMarker(realManagedDirectory, path);
+			return;
+		}
+		await restoreDownloadStagingRootMarker(realManagedDirectory, path).catch((restoreErr) => {
+			emitCleanupWarning(`failed to restore B2 SDK download staging marker: ${require_filesystem_errors.localFilesystemErrorReason(restoreErr)}`);
+		});
 		throw err;
 	}
 }
@@ -119,7 +197,9 @@ async function writeStagingMarker(directory, path) {
 		/* v8 ignore next -- best-effort chmod */
 		await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {});
 	} catch (err) {
-		if (require_path_safety.hasErrorCode(err, "EEXIST") || require_path_safety.hasErrorCode(err, "ELOOP")) {
+		if (require_path_safety.hasErrorCode(err, "EEXIST") || 
+		/* v8 ignore next -- ELOOP depends on platform-specific O_NOFOLLOW behavior */
+		require_path_safety.hasErrorCode(err, "ELOOP")) {
 			if ((await lstat(markerPath).catch(() => void 0))?.isFile() === true) return;
 			throw new Error("unsafe local destination path: staging marker is not a regular file");
 		}
@@ -129,6 +209,24 @@ async function writeStagingMarker(directory, path) {
 		await handle?.close().catch(() => {});
 	}
 }
+function retainDownloadStagingRootCreation(managedDirectory) {
+	activeManagedDirectoryCreations.set(managedDirectory, (activeManagedDirectoryCreations.get(managedDirectory) ?? 0) + 1);
+	return () => {
+		const count = activeManagedDirectoryCreations.get(managedDirectory);
+		/* v8 ignore next -- releases are paired with retains in a single closure */
+		if (count === void 0 || count <= 1) activeManagedDirectoryCreations.delete(managedDirectory);
+		else activeManagedDirectoryCreations.set(managedDirectory, count - 1);
+	};
+}
+function downloadStagingRootCreationIsActive(managedDirectory) {
+	return activeManagedDirectoryCreations.has(managedDirectory);
+}
+async function restoreDownloadStagingRootMarker(managedDirectory, path) {
+	const { lstat, realpath } = await import("node:fs/promises");
+	if ((await lstat(managedDirectory).catch(() => void 0))?.isDirectory() !== true) return;
+	if (await realpath(managedDirectory).catch(() => void 0) !== managedDirectory) return;
+	await writeStagingMarker(managedDirectory, path);
+}
 /**
 * Verifies that a candidate path is on the same filesystem device as the root.
 * @param rootRealPath - Resolved local sync root path.
@@ -149,6 +247,7 @@ async function reapStaleDownloadStagingDirectoriesOnce(managedDirectory, path, n
 		return;
 	}
 	const next = reapStaleDownloadStagingDirectories(managedDirectory, path, nowMillis, activityEntryLimit).finally(() => {
+		/* v8 ignore next -- this map entry cannot be replaced until the current cleanup settles */
 		if (reapedManagedDirectories.get(managedDirectory) === next) reapedManagedDirectories.delete(managedDirectory);
 	});
 	reapedManagedDirectories.set(managedDirectory, next);
@@ -160,8 +259,10 @@ async function reapStaleDownloadStagingDirectories(managedDirectory, path, nowMi
 	try {
 		entries = await readdir(managedDirectory, { withFileTypes: true });
 	} catch (err) {
+		/* v8 ignore next -- concurrent managed-root removal is a filesystem race without a stable hook */
 		if (require_path_safety.hasErrorCode(err, "ENOENT")) return;
-		emitCleanupWarning("failed to inspect B2 SDK download staging entries");
+		/* v8 ignore next -- platform-specific root permission failures cannot be simulated portably */
+		emitCleanupWarning(`failed to inspect B2 SDK download staging entries: ${require_filesystem_errors.localFilesystemErrorReason(err)}`);
 		return;
 	}
 	const cleanupErrors = [];
@@ -176,11 +277,14 @@ async function reapStaleDownloadStagingDirectories(managedDirectory, path, nowMi
 				operation: "inspect"
 			});
 		});
+		/* v8 ignore next -- requires a concurrent delete between activity read and realpath */
 		if (realCandidate === void 0) return;
 		try {
 			require_path_safety.assertPathInsideRoot(managedDirectory, realCandidate, path);
 			const latestActivity = await readManagedStagingEntryActivity(candidate, path, activityEntryLimit);
-			if (latestActivity === void 0 || latestActivity.signature !== activity.signature || !stagingActivityIsStale(latestActivity, nowMillis)) return;
+			if (latestActivity === void 0 || latestActivity.signature !== activity.signature || !stagingActivityIsStale(latestActivity, nowMillis))
+ /* v8 ignore next -- requires concurrent writes between the first and second activity reads */
+			return;
 			await rm(realCandidate, {
 				recursive: true,
 				force: true
@@ -206,7 +310,7 @@ async function readManagedStagingEntryActivity(candidate, path, activityEntryLim
 		if (entries.length > activityEntryLimit) return void 0;
 		const statsParts = [`.:${stagingStatsSignature(directoryStats)}`, `${DOWNLOAD_STAGING_MARKER_NAME}:${stagingStatsSignature(markerStats)}`];
 		let newestActivityMs = Math.max(stagingStatsActivityMs(directoryStats), stagingStatsActivityMs(markerStats));
-		for (const entry of [...entries].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+		for (const entry of [...entries].sort(compareDirectoryEntriesByName)) {
 			const stats = await lstat(path.join(candidate, entry.name));
 			statsParts.push(`${entry.name}:${stagingStatsSignature(stats)}`);
 			newestActivityMs = Math.max(newestActivityMs, stagingStatsActivityMs(stats));
@@ -219,6 +323,12 @@ async function readManagedStagingEntryActivity(candidate, path, activityEntryLim
 		return;
 	}
 }
+function compareDirectoryEntriesByName(a, b) {
+	if (a.name < b.name) return -1;
+	if (a.name > b.name) return 1;
+	/* v8 ignore next -- duplicate directory names cannot occur in a single readdir result */
+	return 0;
+}
 function stagingStatsActivityMs(stats) {
 	return stats.mtimeMs;
 }
@@ -246,7 +356,7 @@ async function forEachWithConcurrency(items, concurrency, fn) {
 		while (index < items.length) {
 			const item = items[index];
 			index += 1;
-			if (item !== void 0) await fn(item);
+			await fn(item);
 		}
 	});
 	await Promise.all(workers);
@@ -260,7 +370,9 @@ exports.DOWNLOAD_STAGING_DIRECTORY_NAME = DOWNLOAD_STAGING_DIRECTORY_NAME;
 exports.DOWNLOAD_STAGING_MARKER_NAME = DOWNLOAD_STAGING_MARKER_NAME;
 exports.assertDownloadPathSameDevice = assertDownloadPathSameDevice;
 exports.createDownloadStagingDirectory = createDownloadStagingDirectory;
+exports.downloadStagingTestHooks = downloadStagingTestHooks;
 exports.isDownloadStagingDirectorySegment = isDownloadStagingDirectorySegment;
 exports.isManagedDownloadStagingRoot = isManagedDownloadStagingRoot;
+exports.removeDownloadStagingRootMarkerAndDirectory = removeDownloadStagingRootMarkerAndDirectory;
 
 //# sourceMappingURL=download-staging.cjs.map

package/dist/sync/download-staging.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"download-staging.cjs","names":[],"sources":["../../src/sync/download-staging.ts"],"sourcesContent":["import { assertPathInsideRoot, hasErrorCode, noFollowFlag } from './path-safety.ts'\n\ntype DeviceStat = { readonly dev: number | bigint }\ntype DeviceStatFn = (path: string) => Promise<DeviceStat>\n\n/** @internal */\nexport const DOWNLOAD_STAGING_DIRECTORY_NAME = '.b2sdk-download-staging'\n/** @internal */\nexport const DOWNLOAD_STAGING_MARKER_NAME = '.b2sdk-staging-marker.partial'\n\nconst CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME = canonicalLocalFilesystemSegment(\n  DOWNLOAD_STAGING_DIRECTORY_NAME,\n)\nconst DOWNLOAD_STAGING_ENTRY_SUFFIX = '.download'\nconst STALE_DOWNLOAD_STAGING_AGE_MS = 24 * 60 * 60 * 1000\nconst MAX_STAGING_CLEANUP_CONCURRENCY = 8\nconst MAX_CLEANUP_WARNING_ENTRIES = 3\n/** @internal */\nexport const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024\nconst reapedManagedDirectories = new Map<string, Promise<void>>()\n\ntype StagingActivitySnapshot = {\n  readonly newestActivityMs: number\n  readonly signature: string\n}\n\ntype CleanupWarning = {\n  readonly entryName: string\n  readonly operation: 'inspect' | 'remove'\n}\n\n/**\n * Checks whether a single path segment matches the SDK-managed staging directory name.\n * @param segment - Candidate path segment.\n *\n * @returns True when the segment is the reserved staging directory name under\n * local filesystem canonicalization.\n *\n * @internal\n */\nexport function isDownloadStagingDirectorySegment(segment: string | undefined): boolean {\n  return (\n    segment !== undefined &&\n    canonicalLocalFilesystemSegment(segment) === CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME\n  )\n}\n\n/**\n * Creates a private SDK-managed staging directory under a local sync root.\n * @param rootRealPath - Resolved local sync root path.\n * @param path - Node path module used for platform-specific path operations.\n * @param randomUUID - UUID provider used to create unique staging entries.\n * @param statForDeviceCheck - Stat function used to verify filesystem devices.\n * @param beforeStagingMarkerWrite - Test hook called before marker creation.\n * @param activityEntryLimit - Maximum entry count inspected for stale staging activity.\n *\n * @returns The resolved staging directory path.\n *\n * @internal\n */\nexport async function createDownloadStagingDirectory(\n  rootRealPath: string,\n  path: typeof import('node:path'),\n  randomUUID: () => string,\n  statForDeviceCheck: DeviceStatFn,\n  beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void,\n  activityEntryLimit = DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT,\n): Promise<string> {\n  const { chmod, lstat, mkdir, readdir, realpath, rm } = await import('node:fs/promises')\n  const managedDirectory = path.join(rootRealPath, DOWNLOAD_STAGING_DIRECTORY_NAME)\n  try {\n    await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n  } catch (err) {\n    if (!hasErrorCode(err, 'EEXIST')) throw err\n  }\n  const managedStats = await lstat(managedDirectory)\n  if (!managedStats.isDirectory()) {\n    throw new Error(\n      `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`,\n    )\n  }\n  const realManagedDirectory = await realpath(managedDirectory)\n  assertPathInsideRoot(rootRealPath, realManagedDirectory, path)\n  await assertDownloadPathSameDevice(\n    rootRealPath,\n    realManagedDirectory,\n    statForDeviceCheck,\n    'unsafe local destination path: cannot stage download across filesystems',\n  )\n\n  if (!(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n    const entries = await readdir(realManagedDirectory)\n    if (entries.length > 0 && !(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n      throw new Error(\n        `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`,\n      )\n    }\n  }\n  await beforeStagingMarkerWrite?.(realManagedDirectory)\n  await writeStagingMarker(realManagedDirectory, path)\n  /* v8 ignore next -- best-effort chmod */\n  await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n  await reapStaleDownloadStagingDirectoriesOnce(\n    realManagedDirectory,\n    path,\n    Date.now(),\n    activityEntryLimit,\n  )\n\n  const stagingDirectory = path.join(\n    realManagedDirectory,\n    `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`,\n  )\n  await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n  /* v8 ignore next -- best-effort chmod */\n  await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n  try {\n    const realStagingDirectory = await realpath(stagingDirectory)\n    assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path)\n    await assertDownloadPathSameDevice(\n      rootRealPath,\n      realStagingDirectory,\n      statForDeviceCheck,\n      'unsafe local destination path: cannot stage download across filesystems',\n    )\n    await beforeStagingMarkerWrite?.(realStagingDirectory)\n    await writeStagingMarker(realStagingDirectory, path)\n    return realStagingDirectory\n  } catch (err) {\n    /* v8 ignore next -- best-effort cleanup */\n    await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n    throw err\n  }\n}\n\n/**\n * Returns true when a scan-root entry is an SDK-managed download staging root.\n * @param directory - Candidate directory to inspect.\n *\n * @returns True when the directory contains SDK staging markers.\n *\n * @internal\n */\nexport async function isManagedDownloadStagingRoot(directory: string): Promise<boolean> {\n  const { lstat, readdir } = await import('node:fs/promises')\n  const path = await import('node:path')\n\n  try {\n    const markerStats = await lstat(path.join(directory, DOWNLOAD_STAGING_MARKER_NAME))\n    if (markerStats.isFile()) return true\n  } catch (err) {\n    if (!hasErrorCode(err, 'ENOENT')) return false\n  }\n\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(directory, { withFileTypes: true })\n  } catch {\n    return false\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) continue\n    try {\n      const markerStats = await lstat(\n        path.join(directory, entry.name, DOWNLOAD_STAGING_MARKER_NAME),\n      )\n      if (markerStats.isFile()) return true\n    } catch {\n      // Keep checking siblings; one corrupt entry should not hide user content.\n    }\n  }\n  return false\n}\n\nconst PRIVATE_DOWNLOAD_FILE_MODE = 0o600\nconst PRIVATE_DOWNLOAD_DIRECTORY_MODE = 0o700\n\nasync function writeStagingMarker(\n  directory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  const { constants } = await import('node:fs')\n  const { lstat, open } = await import('node:fs/promises')\n  const markerPath = path.join(directory, DOWNLOAD_STAGING_MARKER_NAME)\n  let handle: Awaited<ReturnType<typeof open>> | undefined\n  try {\n    handle = await open(\n      markerPath,\n      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(constants),\n      PRIVATE_DOWNLOAD_FILE_MODE,\n    )\n    /* v8 ignore next -- best-effort chmod */\n    await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {})\n  } catch (err) {\n    if (hasErrorCode(err, 'EEXIST') || hasErrorCode(err, 'ELOOP')) {\n      const markerStats = await lstat(markerPath).catch(() => undefined)\n      if (markerStats?.isFile() === true) return\n      throw new Error('unsafe local destination path: staging marker is not a regular file')\n    }\n    throw err\n  } finally {\n    /* v8 ignore next -- best-effort close */\n    await handle?.close().catch(() => {})\n  }\n}\n\n/**\n * Verifies that a candidate path is on the same filesystem device as the root.\n * @param rootRealPath - Resolved local sync root path.\n * @param candidateRealPath - Resolved candidate path to compare.\n * @param statForDeviceCheck - Stat function used to read device IDs.\n * @param message - Error message used when devices differ.\n *\n * @internal\n */\nexport async function assertDownloadPathSameDevice(\n  rootRealPath: string,\n  candidateRealPath: string,\n  statForDeviceCheck: DeviceStatFn,\n  message: string,\n): Promise<void> {\n  const [rootStats, candidateStats] = await Promise.all([\n    statForDeviceCheck(rootRealPath),\n    statForDeviceCheck(candidateRealPath),\n  ])\n  if (rootStats.dev !== candidateStats.dev) throw new Error(message)\n}\n\nasync function reapStaleDownloadStagingDirectoriesOnce(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n  activityEntryLimit: number,\n): Promise<void> {\n  const previous = reapedManagedDirectories.get(managedDirectory)\n  if (previous !== undefined) {\n    await previous\n    return\n  }\n\n  const next = reapStaleDownloadStagingDirectories(\n    managedDirectory,\n    path,\n    nowMillis,\n    activityEntryLimit,\n  ).finally(() => {\n    if (reapedManagedDirectories.get(managedDirectory) === next) {\n      reapedManagedDirectories.delete(managedDirectory)\n    }\n  })\n  reapedManagedDirectories.set(managedDirectory, next)\n  await next\n}\n\nasync function reapStaleDownloadStagingDirectories(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n  activityEntryLimit: number,\n): Promise<void> {\n  const { readdir, realpath, rm } = await import('node:fs/promises')\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(managedDirectory, { withFileTypes: true })\n  } catch (err) {\n    if (hasErrorCode(err, 'ENOENT')) return\n    emitCleanupWarning('failed to inspect B2 SDK download staging entries')\n    return\n  }\n\n  const cleanupErrors: CleanupWarning[] = []\n  await forEachWithConcurrency(entries, MAX_STAGING_CLEANUP_CONCURRENCY, async (entry) => {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) return\n    const candidate = path.join(managedDirectory, entry.name)\n    const activity = await readManagedStagingEntryActivity(candidate, path, activityEntryLimit)\n    if (activity === undefined || !stagingActivityIsStale(activity, nowMillis)) return\n    const realCandidate = await realpath(candidate).catch(() => {\n      cleanupErrors.push({ entryName: entry.name, operation: 'inspect' })\n      return undefined\n    })\n    if (realCandidate === undefined) return\n    try {\n      assertPathInsideRoot(managedDirectory, realCandidate, path)\n      const latestActivity = await readManagedStagingEntryActivity(\n        candidate,\n        path,\n        activityEntryLimit,\n      )\n      if (\n        latestActivity === undefined ||\n        latestActivity.signature !== activity.signature ||\n        !stagingActivityIsStale(latestActivity, nowMillis)\n      ) {\n        return\n      }\n      await rm(realCandidate, { recursive: true, force: true })\n    } catch {\n      cleanupErrors.push({ entryName: entry.name, operation: 'remove' })\n    }\n  })\n\n  if (cleanupErrors.length > 0) {\n    const noun = cleanupErrors.length === 1 ? 'entry' : 'entries'\n    emitCleanupWarning(\n      `failed to reap ${cleanupErrors.length} stale B2 SDK download staging ${noun}: ${cleanupErrors\n        .slice(0, MAX_CLEANUP_WARNING_ENTRIES)\n        .map(formatCleanupWarning)\n        .join('; ')}`,\n    )\n  }\n}\n\nasync function readManagedStagingEntryActivity(\n  candidate: string,\n  path: typeof import('node:path'),\n  activityEntryLimit: number,\n): Promise<StagingActivitySnapshot | undefined> {\n  const { lstat, readdir } = await import('node:fs/promises')\n\n  try {\n    const [directoryStats, markerStats] = await Promise.all([\n      lstat(candidate),\n      lstat(path.join(candidate, DOWNLOAD_STAGING_MARKER_NAME)),\n    ])\n    if (!directoryStats.isDirectory() || !markerStats.isFile()) return undefined\n\n    const entries = await readdir(candidate, { withFileTypes: true })\n    if (entries.length > activityEntryLimit) return undefined\n\n    const statsParts = [\n      `.:${stagingStatsSignature(directoryStats)}`,\n      `${DOWNLOAD_STAGING_MARKER_NAME}:${stagingStatsSignature(markerStats)}`,\n    ]\n    let newestActivityMs = Math.max(\n      stagingStatsActivityMs(directoryStats),\n      stagingStatsActivityMs(markerStats),\n    )\n\n    for (const entry of [...entries].sort((a, b) =>\n      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,\n    )) {\n      const stats = await lstat(path.join(candidate, entry.name))\n      statsParts.push(`${entry.name}:${stagingStatsSignature(stats)}`)\n      newestActivityMs = Math.max(newestActivityMs, stagingStatsActivityMs(stats))\n    }\n\n    return { newestActivityMs, signature: statsParts.join('|') }\n  } catch {\n    return undefined\n  }\n}\n\nfunction stagingStatsActivityMs(stats: { readonly mtimeMs: number }) {\n  return stats.mtimeMs\n}\n\nfunction stagingStatsSignature(stats: {\n  readonly ctimeMs: number\n  readonly dev: number | bigint\n  readonly ino: number | bigint\n  readonly mtimeMs: number\n  readonly size: number\n}): string {\n  return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`\n}\n\nfunction stagingActivityIsStale(activity: StagingActivitySnapshot, nowMillis: number): boolean {\n  return nowMillis - activity.newestActivityMs >= STALE_DOWNLOAD_STAGING_AGE_MS\n}\n\nfunction formatCleanupWarning(error: CleanupWarning): string {\n  return `${error.operation} ${safeWarningName(error.entryName)}`\n}\n\nfunction safeWarningName(name: string): string {\n  const chars = Array.from(name)\n  const bounded = chars.slice(0, 80).join('')\n  const suffix = chars.length > 80 ? '...' : ''\n  return JSON.stringify(`${bounded.replace(/[^A-Za-z0-9._-]/g, '?')}${suffix}`)\n}\n\nfunction canonicalLocalFilesystemSegment(segment: string): string {\n  return segment.normalize('NFC').toLocaleLowerCase('en-US')\n}\n\nasync function forEachWithConcurrency<T>(\n  items: readonly T[],\n  concurrency: number,\n  fn: (item: T) => Promise<void>,\n): Promise<void> {\n  let index = 0\n  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {\n    while (index < items.length) {\n      const item = items[index]\n      index += 1\n      if (item !== undefined) await fn(item)\n    }\n  })\n  await Promise.all(workers)\n}\n\nfunction emitCleanupWarning(message: string): void {\n  const processLike = (\n    globalThis as {\n      process?: {\n        emitWarning?: (warning: string, options?: { readonly code?: string }) => void\n      }\n    }\n  ).process\n  processLike?.emitWarning?.(message, { code: 'B2SDK_DOWNLOAD_STAGING_CLEANUP_FAILED' })\n}\n"],"mappings":"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"}
+{"version":3,"file":"download-staging.cjs","names":[],"sources":["../../src/sync/download-staging.ts"],"sourcesContent":["import { localFilesystemErrorReason } from './filesystem-errors.ts'\nimport { assertPathInsideRoot, hasErrorCode, noFollowFlag } from './path-safety.ts'\n\ntype DeviceStat = { readonly dev: number | bigint }\ntype DeviceStatFn = (path: string) => Promise<DeviceStat>\n\n/** @internal */\nexport const DOWNLOAD_STAGING_DIRECTORY_NAME = '.b2sdk-download-staging'\n/** @internal */\nexport const DOWNLOAD_STAGING_MARKER_NAME = '.b2sdk-staging-marker.partial'\n\nconst CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME = canonicalLocalFilesystemSegment(\n  DOWNLOAD_STAGING_DIRECTORY_NAME,\n)\nconst DOWNLOAD_STAGING_ENTRY_SUFFIX = '.download'\nconst STALE_DOWNLOAD_STAGING_AGE_MS = 24 * 60 * 60 * 1000\nconst MAX_STAGING_CLEANUP_CONCURRENCY = 8\nconst MAX_CLEANUP_WARNING_ENTRIES = 3\n/** @internal */\nexport const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024\nconst reapedManagedDirectories = new Map<string, Promise<void>>()\nconst activeManagedDirectoryCreations = new Map<string, number>()\n\n/** @internal */\nexport const downloadStagingTestHooks: {\n  afterCleanupMarkerStat?: (managedDirectory: string) => Promise<void> | void\n  beforeCleanupMarkerUnlink?: (markerPath: string) => Promise<void> | void\n} = {}\n\ntype StagingActivitySnapshot = {\n  readonly newestActivityMs: number\n  readonly signature: string\n}\n\ntype CleanupWarning = {\n  readonly entryName: string\n  readonly operation: 'inspect' | 'remove'\n}\n\n/** @internal */\nexport interface DownloadStagingDirectory {\n  /** Resolved SDK-managed staging root shared by download runs under one sync root. */\n  readonly managedDirectory: string\n  /** Resolved per-run staging directory for one download. */\n  readonly stagingDirectory: string\n}\n\n/**\n * Checks whether a single path segment matches the SDK-managed staging directory name.\n * @param segment - Candidate path segment.\n *\n * @returns True when the segment is the reserved staging directory name under\n * local filesystem canonicalization.\n *\n * @internal\n */\nexport function isDownloadStagingDirectorySegment(segment: string | undefined): boolean {\n  return (\n    segment !== undefined &&\n    canonicalLocalFilesystemSegment(segment) === CANONICAL_DOWNLOAD_STAGING_DIRECTORY_NAME\n  )\n}\n\n/**\n * Creates a private SDK-managed staging directory under a local sync root.\n * @param rootRealPath - Resolved local sync root path.\n * @param path - Node path module used for platform-specific path operations.\n * @param randomUUID - UUID provider used to create unique staging entries.\n * @param statForDeviceCheck - Stat function used to verify filesystem devices.\n * @param beforeStagingMarkerWrite - Test hook called before marker creation.\n * @param activityEntryLimit - Maximum entry count inspected for stale staging activity.\n * @param afterManagedStagingMarkerWrite - Test hook called after managed-root marker creation.\n *\n * @returns The resolved managed and per-run staging directory paths.\n *\n * @internal\n */\nexport async function createDownloadStagingDirectory(\n  rootRealPath: string,\n  path: typeof import('node:path'),\n  randomUUID: () => string,\n  statForDeviceCheck: DeviceStatFn,\n  beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void,\n  activityEntryLimit = DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT,\n  afterManagedStagingMarkerWrite?: (directory: string) => Promise<void> | void,\n): Promise<DownloadStagingDirectory> {\n  const { chmod, lstat, mkdir, readdir, realpath, rm } = await import('node:fs/promises')\n  const managedDirectory = path.join(rootRealPath, DOWNLOAD_STAGING_DIRECTORY_NAME)\n  const releaseManagedDirectoryCreation = retainDownloadStagingRootCreation(managedDirectory)\n  try {\n    try {\n      await mkdir(managedDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n    } catch (err) {\n      if (!hasErrorCode(err, 'EEXIST')) throw err\n    }\n    const managedStats = await lstat(managedDirectory)\n    if (!managedStats.isDirectory()) {\n      throw new Error(\n        `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is not a directory`,\n      )\n    }\n    const realManagedDirectory = await realpath(managedDirectory)\n    assertPathInsideRoot(rootRealPath, realManagedDirectory, path)\n    await assertDownloadPathSameDevice(\n      rootRealPath,\n      realManagedDirectory,\n      statForDeviceCheck,\n      'unsafe local destination path: cannot stage download across filesystems',\n    )\n\n    if (!(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n      const entries = await readdir(realManagedDirectory)\n      if (entries.length > 0 && !(await isManagedDownloadStagingRoot(realManagedDirectory))) {\n        throw new Error(\n          `unsafe local destination path: ${DOWNLOAD_STAGING_DIRECTORY_NAME} is reserved for SDK download staging`,\n        )\n      }\n    }\n    await beforeStagingMarkerWrite?.(realManagedDirectory)\n    await writeStagingMarker(realManagedDirectory, path)\n    await afterManagedStagingMarkerWrite?.(realManagedDirectory)\n    /* v8 ignore next -- best-effort chmod */\n    await chmod(realManagedDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n    await reapStaleDownloadStagingDirectoriesOnce(\n      realManagedDirectory,\n      path,\n      Date.now(),\n      activityEntryLimit,\n    )\n\n    const stagingDirectory = path.join(\n      realManagedDirectory,\n      `${Date.now()}-${randomUUID()}${DOWNLOAD_STAGING_ENTRY_SUFFIX}`,\n    )\n    await mkdir(stagingDirectory, { mode: PRIVATE_DOWNLOAD_DIRECTORY_MODE })\n    /* v8 ignore next -- best-effort chmod */\n    await chmod(stagingDirectory, PRIVATE_DOWNLOAD_DIRECTORY_MODE).catch(() => {})\n    try {\n      const realStagingDirectory = await realpath(stagingDirectory)\n      assertPathInsideRoot(realManagedDirectory, realStagingDirectory, path)\n      await assertDownloadPathSameDevice(\n        rootRealPath,\n        realStagingDirectory,\n        statForDeviceCheck,\n        'unsafe local destination path: cannot stage download across filesystems',\n      )\n      await beforeStagingMarkerWrite?.(realStagingDirectory)\n      await writeStagingMarker(realStagingDirectory, path)\n      return {\n        managedDirectory: realManagedDirectory,\n        stagingDirectory: realStagingDirectory,\n      }\n    } catch (err) {\n      /* v8 ignore next -- best-effort cleanup */\n      await rm(stagingDirectory, { recursive: true, force: true }).catch(() => {})\n      throw err\n    }\n  } finally {\n    releaseManagedDirectoryCreation()\n  }\n}\n\n/**\n * Removes the SDK root marker and the now-empty SDK-managed staging root\n * once all per-run `.download` entries are gone.\n * @param rootRealPath - Resolved local sync root path.\n * @param managedDirectory - Resolved SDK-managed staging root path.\n * @param path - Node path module used for platform-specific path operations.\n *\n * @internal\n */\nexport async function removeDownloadStagingRootMarkerAndDirectory(\n  rootRealPath: string,\n  managedDirectory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  try {\n    await removeDownloadStagingRootMarkerAndDirectoryCore(rootRealPath, managedDirectory, path)\n  } catch (err) {\n    emitCleanupWarning(\n      `failed to remove B2 SDK download staging root: ${localFilesystemErrorReason(err)}`,\n    )\n  }\n}\n\nasync function removeDownloadStagingRootMarkerAndDirectoryCore(\n  rootRealPath: string,\n  managedDirectory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  const { lstat, readdir, realpath, rmdir, unlink } = await import('node:fs/promises')\n  if (downloadStagingRootCreationIsActive(managedDirectory)) return\n\n  const managedStats = await lstat(managedDirectory).catch((err: unknown) => {\n    if (hasErrorCode(err, 'ENOENT')) return undefined\n    throw err\n  })\n  if (managedStats === undefined || !managedStats.isDirectory()) return\n\n  const realManagedDirectory = await realpath(managedDirectory).catch((err: unknown) => {\n    if (hasErrorCode(err, 'ENOENT')) return undefined\n    throw err\n  })\n  if (realManagedDirectory === undefined) return\n  assertPathInsideRoot(rootRealPath, realManagedDirectory, path)\n  if (downloadStagingRootCreationIsActive(realManagedDirectory)) return\n\n  const markerPath = path.join(realManagedDirectory, DOWNLOAD_STAGING_MARKER_NAME)\n  const markerStats = await lstat(markerPath).catch((err: unknown) => {\n    if (hasErrorCode(err, 'ENOENT')) return undefined\n    throw err\n  })\n  if (markerStats?.isFile() !== true) return\n\n  await downloadStagingTestHooks.afterCleanupMarkerStat?.(realManagedDirectory)\n  const entries = await readdir(realManagedDirectory, { withFileTypes: true }).catch(\n    (err: unknown) => {\n      if (hasErrorCode(err, 'ENOENT')) return undefined\n      throw err\n    },\n  )\n  if (entries === undefined) return\n  if (entries.length !== 1 || entries[0]?.name !== DOWNLOAD_STAGING_MARKER_NAME) return\n  const currentRealManagedDirectory = await realpath(managedDirectory).catch(() => undefined)\n  if (currentRealManagedDirectory !== realManagedDirectory) return\n  if (downloadStagingRootCreationIsActive(realManagedDirectory)) return\n\n  await downloadStagingTestHooks.beforeCleanupMarkerUnlink?.(markerPath)\n  const markerRemoved = await unlink(markerPath)\n    .then(() => true)\n    .catch((err: unknown) => {\n      if (hasErrorCode(err, 'ENOENT')) return false\n      throw err\n    })\n  if (!markerRemoved) return\n  try {\n    await rmdir(realManagedDirectory)\n  } catch (err) {\n    if (hasErrorCode(err, 'ENOENT')) return\n    if (hasErrorCode(err, 'ENOTEMPTY') || hasErrorCode(err, 'EEXIST')) {\n      await restoreDownloadStagingRootMarker(realManagedDirectory, path)\n      return\n    }\n    await restoreDownloadStagingRootMarker(realManagedDirectory, path).catch((restoreErr) => {\n      emitCleanupWarning(\n        `failed to restore B2 SDK download staging marker: ${localFilesystemErrorReason(\n          restoreErr,\n        )}`,\n      )\n    })\n    throw err\n  }\n}\n\n/**\n * Returns true when a scan-root entry is an SDK-managed download staging root.\n * @param directory - Candidate directory to inspect.\n *\n * @returns True when the directory contains SDK staging markers.\n *\n * @internal\n */\nexport async function isManagedDownloadStagingRoot(directory: string): Promise<boolean> {\n  const { lstat, readdir } = await import('node:fs/promises')\n  const path = await import('node:path')\n\n  try {\n    const markerStats = await lstat(path.join(directory, DOWNLOAD_STAGING_MARKER_NAME))\n    if (markerStats.isFile()) return true\n  } catch (err) {\n    if (!hasErrorCode(err, 'ENOENT')) return false\n  }\n\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(directory, { withFileTypes: true })\n  } catch {\n    return false\n  }\n\n  for (const entry of entries) {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) continue\n    try {\n      const markerStats = await lstat(\n        path.join(directory, entry.name, DOWNLOAD_STAGING_MARKER_NAME),\n      )\n      if (markerStats.isFile()) return true\n    } catch {\n      // Keep checking siblings; one corrupt entry should not hide user content.\n    }\n  }\n  return false\n}\n\nconst PRIVATE_DOWNLOAD_FILE_MODE = 0o600\nconst PRIVATE_DOWNLOAD_DIRECTORY_MODE = 0o700\n\nasync function writeStagingMarker(\n  directory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  const { constants } = await import('node:fs')\n  const { lstat, open } = await import('node:fs/promises')\n  const markerPath = path.join(directory, DOWNLOAD_STAGING_MARKER_NAME)\n  let handle: Awaited<ReturnType<typeof open>> | undefined\n  try {\n    handle = await open(\n      markerPath,\n      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(constants),\n      PRIVATE_DOWNLOAD_FILE_MODE,\n    )\n    /* v8 ignore next -- best-effort chmod */\n    await handle.chmod(PRIVATE_DOWNLOAD_FILE_MODE).catch(() => {})\n  } catch (err) {\n    const markerAlreadyExists = hasErrorCode(err, 'EEXIST')\n    if (\n      markerAlreadyExists ||\n      /* v8 ignore next -- ELOOP depends on platform-specific O_NOFOLLOW behavior */\n      hasErrorCode(err, 'ELOOP')\n    ) {\n      const markerStats = await lstat(markerPath).catch(() => undefined)\n      if (markerStats?.isFile() === true) return\n      throw new Error('unsafe local destination path: staging marker is not a regular file')\n    }\n    throw err\n  } finally {\n    /* v8 ignore next -- best-effort close */\n    await handle?.close().catch(() => {})\n  }\n}\n\nfunction retainDownloadStagingRootCreation(managedDirectory: string): () => void {\n  activeManagedDirectoryCreations.set(\n    managedDirectory,\n    (activeManagedDirectoryCreations.get(managedDirectory) ?? 0) + 1,\n  )\n  return () => {\n    const count = activeManagedDirectoryCreations.get(managedDirectory)\n    /* v8 ignore next -- releases are paired with retains in a single closure */\n    if (count === undefined || count <= 1) {\n      activeManagedDirectoryCreations.delete(managedDirectory)\n    } else {\n      activeManagedDirectoryCreations.set(managedDirectory, count - 1)\n    }\n  }\n}\n\nfunction downloadStagingRootCreationIsActive(managedDirectory: string): boolean {\n  return activeManagedDirectoryCreations.has(managedDirectory)\n}\n\nasync function restoreDownloadStagingRootMarker(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n): Promise<void> {\n  const { lstat, realpath } = await import('node:fs/promises')\n  const managedStats = await lstat(managedDirectory).catch(() => undefined)\n  if (managedStats?.isDirectory() !== true) return\n  const currentRealManagedDirectory = await realpath(managedDirectory).catch(() => undefined)\n  if (currentRealManagedDirectory !== managedDirectory) return\n  await writeStagingMarker(managedDirectory, path)\n}\n\n/**\n * Verifies that a candidate path is on the same filesystem device as the root.\n * @param rootRealPath - Resolved local sync root path.\n * @param candidateRealPath - Resolved candidate path to compare.\n * @param statForDeviceCheck - Stat function used to read device IDs.\n * @param message - Error message used when devices differ.\n *\n * @internal\n */\nexport async function assertDownloadPathSameDevice(\n  rootRealPath: string,\n  candidateRealPath: string,\n  statForDeviceCheck: DeviceStatFn,\n  message: string,\n): Promise<void> {\n  const [rootStats, candidateStats] = await Promise.all([\n    statForDeviceCheck(rootRealPath),\n    statForDeviceCheck(candidateRealPath),\n  ])\n  if (rootStats.dev !== candidateStats.dev) throw new Error(message)\n}\n\nasync function reapStaleDownloadStagingDirectoriesOnce(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n  activityEntryLimit: number,\n): Promise<void> {\n  const previous = reapedManagedDirectories.get(managedDirectory)\n  if (previous !== undefined) {\n    await previous\n    return\n  }\n\n  const next = reapStaleDownloadStagingDirectories(\n    managedDirectory,\n    path,\n    nowMillis,\n    activityEntryLimit,\n  ).finally(() => {\n    /* v8 ignore next -- this map entry cannot be replaced until the current cleanup settles */\n    if (reapedManagedDirectories.get(managedDirectory) === next) {\n      reapedManagedDirectories.delete(managedDirectory)\n    }\n  })\n  reapedManagedDirectories.set(managedDirectory, next)\n  await next\n}\n\nasync function reapStaleDownloadStagingDirectories(\n  managedDirectory: string,\n  path: typeof import('node:path'),\n  nowMillis: number,\n  activityEntryLimit: number,\n): Promise<void> {\n  const { readdir, realpath, rm } = await import('node:fs/promises')\n  let entries: import('node:fs').Dirent[]\n  try {\n    entries = await readdir(managedDirectory, { withFileTypes: true })\n  } catch (err) {\n    /* v8 ignore next -- concurrent managed-root removal is a filesystem race without a stable hook */\n    if (hasErrorCode(err, 'ENOENT')) return\n    /* v8 ignore next -- platform-specific root permission failures cannot be simulated portably */\n    emitCleanupWarning(\n      `failed to inspect B2 SDK download staging entries: ${localFilesystemErrorReason(err)}`,\n    )\n    return\n  }\n\n  const cleanupErrors: CleanupWarning[] = []\n  await forEachWithConcurrency(entries, MAX_STAGING_CLEANUP_CONCURRENCY, async (entry) => {\n    if (!entry.isDirectory() || !entry.name.endsWith(DOWNLOAD_STAGING_ENTRY_SUFFIX)) return\n    const candidate = path.join(managedDirectory, entry.name)\n    const activity = await readManagedStagingEntryActivity(candidate, path, activityEntryLimit)\n    if (activity === undefined || !stagingActivityIsStale(activity, nowMillis)) return\n    const realCandidate = await realpath(candidate).catch(() => {\n      cleanupErrors.push({ entryName: entry.name, operation: 'inspect' })\n      return undefined\n    })\n    /* v8 ignore next -- requires a concurrent delete between activity read and realpath */\n    if (realCandidate === undefined) return\n    try {\n      assertPathInsideRoot(managedDirectory, realCandidate, path)\n      const latestActivity = await readManagedStagingEntryActivity(\n        candidate,\n        path,\n        activityEntryLimit,\n      )\n      if (\n        latestActivity === undefined ||\n        latestActivity.signature !== activity.signature ||\n        !stagingActivityIsStale(latestActivity, nowMillis)\n      ) {\n        /* v8 ignore next -- requires concurrent writes between the first and second activity reads */\n        return\n      }\n      await rm(realCandidate, { recursive: true, force: true })\n    } catch {\n      cleanupErrors.push({ entryName: entry.name, operation: 'remove' })\n    }\n  })\n\n  if (cleanupErrors.length > 0) {\n    const noun = cleanupErrors.length === 1 ? 'entry' : 'entries'\n    emitCleanupWarning(\n      `failed to reap ${cleanupErrors.length} stale B2 SDK download staging ${noun}: ${cleanupErrors\n        .slice(0, MAX_CLEANUP_WARNING_ENTRIES)\n        .map(formatCleanupWarning)\n        .join('; ')}`,\n    )\n  }\n}\n\nasync function readManagedStagingEntryActivity(\n  candidate: string,\n  path: typeof import('node:path'),\n  activityEntryLimit: number,\n): Promise<StagingActivitySnapshot | undefined> {\n  const { lstat, readdir } = await import('node:fs/promises')\n\n  try {\n    const [directoryStats, markerStats] = await Promise.all([\n      lstat(candidate),\n      lstat(path.join(candidate, DOWNLOAD_STAGING_MARKER_NAME)),\n    ])\n    if (!directoryStats.isDirectory() || !markerStats.isFile()) return undefined\n\n    const entries = await readdir(candidate, { withFileTypes: true })\n    if (entries.length > activityEntryLimit) return undefined\n\n    const statsParts = [\n      `.:${stagingStatsSignature(directoryStats)}`,\n      `${DOWNLOAD_STAGING_MARKER_NAME}:${stagingStatsSignature(markerStats)}`,\n    ]\n    let newestActivityMs = Math.max(\n      stagingStatsActivityMs(directoryStats),\n      stagingStatsActivityMs(markerStats),\n    )\n\n    for (const entry of [...entries].sort(compareDirectoryEntriesByName)) {\n      const stats = await lstat(path.join(candidate, entry.name))\n      statsParts.push(`${entry.name}:${stagingStatsSignature(stats)}`)\n      newestActivityMs = Math.max(newestActivityMs, stagingStatsActivityMs(stats))\n    }\n\n    return { newestActivityMs, signature: statsParts.join('|') }\n  } catch {\n    return undefined\n  }\n}\n\nfunction compareDirectoryEntriesByName(\n  a: { readonly name: string },\n  b: { readonly name: string },\n): number {\n  if (a.name < b.name) return -1\n  if (a.name > b.name) return 1\n  /* v8 ignore next -- duplicate directory names cannot occur in a single readdir result */\n  return 0\n}\n\nfunction stagingStatsActivityMs(stats: { readonly mtimeMs: number }) {\n  return stats.mtimeMs\n}\n\nfunction stagingStatsSignature(stats: {\n  readonly ctimeMs: number\n  readonly dev: number | bigint\n  readonly ino: number | bigint\n  readonly mtimeMs: number\n  readonly size: number\n}): string {\n  return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`\n}\n\nfunction stagingActivityIsStale(activity: StagingActivitySnapshot, nowMillis: number): boolean {\n  return nowMillis - activity.newestActivityMs >= STALE_DOWNLOAD_STAGING_AGE_MS\n}\n\nfunction formatCleanupWarning(error: CleanupWarning): string {\n  return `${error.operation} ${safeWarningName(error.entryName)}`\n}\n\nfunction safeWarningName(name: string): string {\n  const chars = Array.from(name)\n  const bounded = chars.slice(0, 80).join('')\n  const suffix = chars.length > 80 ? '...' : ''\n  return JSON.stringify(`${bounded.replace(/[^A-Za-z0-9._-]/g, '?')}${suffix}`)\n}\n\nfunction canonicalLocalFilesystemSegment(segment: string): string {\n  return segment.normalize('NFC').toLocaleLowerCase('en-US')\n}\n\nasync function forEachWithConcurrency<T>(\n  items: readonly T[],\n  concurrency: number,\n  fn: (item: T) => Promise<void>,\n): Promise<void> {\n  let index = 0\n  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {\n    while (index < items.length) {\n      const item = items[index] as T\n      index += 1\n      await fn(item)\n    }\n  })\n  await Promise.all(workers)\n}\n\nfunction emitCleanupWarning(message: string): void {\n  const processLike = (\n    globalThis as {\n      process?: {\n        emitWarning?: (warning: string, options?: { readonly code?: string }) => void\n      }\n    }\n  ).process\n  processLike?.emitWarning?.(message, { code: 'B2SDK_DOWNLOAD_STAGING_CLEANUP_FAILED' })\n}\n"],"mappings":"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"}

package/dist/sync/download-staging.d.cts

@@ -8,6 +8,18 @@ export declare const DOWNLOAD_STAGING_DIRECTORY_NAME = ".b2sdk-download-staging"
 export declare const DOWNLOAD_STAGING_MARKER_NAME = ".b2sdk-staging-marker.partial";
 /** @internal */
 export declare const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024;
+/** @internal */
+export declare const downloadStagingTestHooks: {
+    afterCleanupMarkerStat?: (managedDirectory: string) => Promise<void> | void;
+    beforeCleanupMarkerUnlink?: (markerPath: string) => Promise<void> | void;
+};
+/** @internal */
+export interface DownloadStagingDirectory {
+    /** Resolved SDK-managed staging root shared by download runs under one sync root. */
+    readonly managedDirectory: string;
+    /** Resolved per-run staging directory for one download. */
+    readonly stagingDirectory: string;
+}
 /**
  * Checks whether a single path segment matches the SDK-managed staging directory name.
  * @param segment - Candidate path segment.
@@ -26,12 +38,23 @@ export declare function isDownloadStagingDirectorySegment(segment: string | unde
  * @param statForDeviceCheck - Stat function used to verify filesystem devices.
  * @param beforeStagingMarkerWrite - Test hook called before marker creation.
  * @param activityEntryLimit - Maximum entry count inspected for stale staging activity.
+ * @param afterManagedStagingMarkerWrite - Test hook called after managed-root marker creation.
  *
- * @returns The resolved staging directory path.
+ * @returns The resolved managed and per-run staging directory paths.
+ *
+ * @internal
+ */
+export declare function createDownloadStagingDirectory(rootRealPath: string, path: typeof import('node:path'), randomUUID: () => string, statForDeviceCheck: DeviceStatFn, beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void, activityEntryLimit?: number, afterManagedStagingMarkerWrite?: (directory: string) => Promise<void> | void): Promise<DownloadStagingDirectory>;
+/**
+ * Removes the SDK root marker and the now-empty SDK-managed staging root
+ * once all per-run `.download` entries are gone.
+ * @param rootRealPath - Resolved local sync root path.
+ * @param managedDirectory - Resolved SDK-managed staging root path.
+ * @param path - Node path module used for platform-specific path operations.
  *
  * @internal
  */
-export declare function createDownloadStagingDirectory(rootRealPath: string, path: typeof import('node:path'), randomUUID: () => string, statForDeviceCheck: DeviceStatFn, beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void, activityEntryLimit?: number): Promise<string>;
+export declare function removeDownloadStagingRootMarkerAndDirectory(rootRealPath: string, managedDirectory: string, path: typeof import('node:path')): Promise<void>;
 /**
  * Returns true when a scan-root entry is an SDK-managed download staging root.
  * @param directory - Candidate directory to inspect.

package/dist/sync/download-staging.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"download-staging.d.ts","sourceRoot":"","sources":["../../src/sync/download-staging.js"],"names":[],"mappings":"AAEA,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,gBAAgB;AAChB,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AACxE,gBAAgB;AAChB,eAAO,MAAM,4BAA4B,kCAAkC,CAAA;AAS3E,gBAAgB;AAChB,eAAO,MAAM,qCAAqC,OAAO,CAAA;AAazD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,WAAW,CAAC,EAChC,UAAU,EAAE,MAAM,MAAM,EACxB,kBAAkB,EAAE,YAAY,EAChC,wBAAwB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACtE,kBAAkB,SAAwC,GACzD,OAAO,CAAC,MAAM,CAAC,CAkEjB;AAED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BtF;AAkCD;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,kBAAkB,EAAE,YAAY,EAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"download-staging.d.ts","sourceRoot":"","sources":["../../src/sync/download-staging.js"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,gBAAgB;AAChB,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AACxE,gBAAgB;AAChB,eAAO,MAAM,4BAA4B,kCAAkC,CAAA;AAS3E,gBAAgB;AAChB,eAAO,MAAM,qCAAqC,OAAO,CAAA;AAIzD,gBAAgB;AAChB,eAAO,MAAM,wBAAwB,EAAE;IACrC,sBAAsB,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3E,yBAAyB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACpE,CAAA;AAYN,gBAAgB;AAChB,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,WAAW,CAAC,EAChC,UAAU,EAAE,MAAM,MAAM,EACxB,kBAAkB,EAAE,YAAY,EAChC,wBAAwB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACtE,kBAAkB,SAAwC,EAC1D,8BAA8B,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAC3E,OAAO,CAAC,wBAAwB,CAAC,CA2EnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,2CAA2C,CAC/D,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,WAAW,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf;AAuED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BtF;AAuED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,kBAAkB,EAAE,YAAY,EAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/sync/download-staging.d.ts

@@ -8,6 +8,18 @@ export declare const DOWNLOAD_STAGING_DIRECTORY_NAME = ".b2sdk-download-staging"
 export declare const DOWNLOAD_STAGING_MARKER_NAME = ".b2sdk-staging-marker.partial";
 /** @internal */
 export declare const DOWNLOAD_STAGING_ACTIVITY_ENTRY_LIMIT = 1024;
+/** @internal */
+export declare const downloadStagingTestHooks: {
+    afterCleanupMarkerStat?: (managedDirectory: string) => Promise<void> | void;
+    beforeCleanupMarkerUnlink?: (markerPath: string) => Promise<void> | void;
+};
+/** @internal */
+export interface DownloadStagingDirectory {
+    /** Resolved SDK-managed staging root shared by download runs under one sync root. */
+    readonly managedDirectory: string;
+    /** Resolved per-run staging directory for one download. */
+    readonly stagingDirectory: string;
+}
 /**
  * Checks whether a single path segment matches the SDK-managed staging directory name.
  * @param segment - Candidate path segment.
@@ -26,12 +38,23 @@ export declare function isDownloadStagingDirectorySegment(segment: string | unde
  * @param statForDeviceCheck - Stat function used to verify filesystem devices.
  * @param beforeStagingMarkerWrite - Test hook called before marker creation.
  * @param activityEntryLimit - Maximum entry count inspected for stale staging activity.
+ * @param afterManagedStagingMarkerWrite - Test hook called after managed-root marker creation.
  *
- * @returns The resolved staging directory path.
+ * @returns The resolved managed and per-run staging directory paths.
+ *
+ * @internal
+ */
+export declare function createDownloadStagingDirectory(rootRealPath: string, path: typeof import('node:path'), randomUUID: () => string, statForDeviceCheck: DeviceStatFn, beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void, activityEntryLimit?: number, afterManagedStagingMarkerWrite?: (directory: string) => Promise<void> | void): Promise<DownloadStagingDirectory>;
+/**
+ * Removes the SDK root marker and the now-empty SDK-managed staging root
+ * once all per-run `.download` entries are gone.
+ * @param rootRealPath - Resolved local sync root path.
+ * @param managedDirectory - Resolved SDK-managed staging root path.
+ * @param path - Node path module used for platform-specific path operations.
  *
  * @internal
  */
-export declare function createDownloadStagingDirectory(rootRealPath: string, path: typeof import('node:path'), randomUUID: () => string, statForDeviceCheck: DeviceStatFn, beforeStagingMarkerWrite?: (directory: string) => Promise<void> | void, activityEntryLimit?: number): Promise<string>;
+export declare function removeDownloadStagingRootMarkerAndDirectory(rootRealPath: string, managedDirectory: string, path: typeof import('node:path')): Promise<void>;
 /**
  * Returns true when a scan-root entry is an SDK-managed download staging root.
  * @param directory - Candidate directory to inspect.

package/dist/sync/download-staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download-staging.d.ts","sourceRoot":"","sources":["../../src/sync/download-staging.js"],"names":[],"mappings":"AAEA,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,gBAAgB;AAChB,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AACxE,gBAAgB;AAChB,eAAO,MAAM,4BAA4B,kCAAkC,CAAA;AAS3E,gBAAgB;AAChB,eAAO,MAAM,qCAAqC,OAAO,CAAA;AAazD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,WAAW,CAAC,EAChC,UAAU,EAAE,MAAM,MAAM,EACxB,kBAAkB,EAAE,YAAY,EAChC,wBAAwB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACtE,kBAAkB,SAAwC,GACzD,OAAO,CAAC,MAAM,CAAC,CAkEjB;AAED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BtF;AAkCD;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,kBAAkB,EAAE,YAAY,EAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"download-staging.d.ts","sourceRoot":"","sources":["../../src/sync/download-staging.js"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AACnD,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEzD,gBAAgB;AAChB,eAAO,MAAM,+BAA+B,4BAA4B,CAAA;AACxE,gBAAgB;AAChB,eAAO,MAAM,4BAA4B,kCAAkC,CAAA;AAS3E,gBAAgB;AAChB,eAAO,MAAM,qCAAqC,OAAO,CAAA;AAIzD,gBAAgB;AAChB,eAAO,MAAM,wBAAwB,EAAE;IACrC,sBAAsB,CAAC,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3E,yBAAyB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACpE,CAAA;AAYN,gBAAgB;AAChB,MAAM,WAAW,wBAAwB;IACvC,qFAAqF;IACrF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,8BAA8B,CAClD,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,WAAW,CAAC,EAChC,UAAU,EAAE,MAAM,MAAM,EACxB,kBAAkB,EAAE,YAAY,EAChC,wBAAwB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACtE,kBAAkB,SAAwC,EAC1D,8BAA8B,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAC3E,OAAO,CAAC,wBAAwB,CAAC,CA2EnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,2CAA2C,CAC/D,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,cAAc,WAAW,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf;AAuED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BtF;AAuED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,kBAAkB,EAAE,YAAY,EAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf"}