@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/path-safety.js

@@ -0,0 +1,105 @@
+//#region src/sync/path-safety.ts
+var RESERVED_SYNC_TEMP_FILE_RE = /^\.b2sdk-[0-9a-f]{24}-[^/\\]+-[0-9a-f]{32}\.partial$/i;
+var UUID_HEX_RE = /^[0-9a-f]{32}$/i;
+/**
+* Checks whether a basename is reserved for SDK-owned sync partial files.
+* @param name - Basename to inspect.
+*
+* @returns Whether the basename matches the SDK reserved partial-file pattern.
+*
+* @internal
+*/
+function isReservedSyncTempFileName(name) {
+	return RESERVED_SYNC_TEMP_FILE_RE.test(name);
+}
+/**
+* Rejects sync paths whose basename is reserved for SDK-owned temporary files.
+* @param relativePath - Sync-relative path using slash separators.
+*
+* @throws If any path segment uses the SDK's reserved temporary-file pattern.
+*
+* @internal
+*/
+function assertSyncPathAllowed(relativePath) {
+	if (relativePath.split(/[\\/]+/).filter(Boolean).some((part) => isReservedSyncTempFileName(part))) throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`);
+}
+/**
+* Creates a download staging basename inside the SDK-reserved temp namespace.
+* @param finalName - Final destination basename.
+* @param uuid - UUID used to make the temp basename unique.
+*
+* @returns A basename that local and B2 scanners reject as SDK-owned temp data.
+*
+* @throws If the provided UUID cannot be normalized to 32 hex characters.
+*
+* @internal
+*/
+function makeReservedSyncTempFileName(finalName, uuid) {
+	if (finalName.length === 0 || /[\\/]/.test(finalName)) throw new Error("invalid sync temporary-file basename");
+	const hex = uuid.replaceAll("-", "").toLowerCase();
+	if (!UUID_HEX_RE.test(hex)) throw new Error("invalid sync temporary-file nonce");
+	return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`;
+}
+/**
+* Validates B2 relative names before they are materialized on a local filesystem.
+*
+* @param relPath - B2-style relative path.
+*
+* @returns Validated path segments.
+*
+* @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.
+*
+* @internal
+*/
+function safeRelativePathSegments(relPath) {
+	assertSyncPathAllowed(relPath);
+	if (relPath.length === 0 || relPath.includes("\0") || relPath.includes("\\") || relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath)) throw new Error("unsafe local destination path");
+	const segments = relPath.split("/");
+	if (segments.some((segment) => segment.length === 0 || segment === "." || segment === ".." || segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ") || WINDOWS_RESERVED_NAME.test(segment))) throw new Error("unsafe local destination path");
+	return segments;
+}
+var WINDOWS_RESERVED_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3])(?:\..*)?$/i;
+/**
+* Throws if {@link target} is outside {@link root} or names the root itself.
+*
+* @param root - Resolved filesystem root.
+* @param target - Candidate path to validate.
+* @param path - Node path module.
+*
+* @throws When the target is outside the root or equal to the root.
+*
+* @internal
+*/
+function assertPathInsideRoot(root, target, path) {
+	const relative = path.relative(root, target);
+	if (relative.length === 0 || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error("unsafe local destination path");
+}
+/**
+* Returns the platform's no-follow open flag when available.
+*
+* @param constants - Node filesystem constants.
+*
+* @returns The `O_NOFOLLOW` bit or `0`.
+*
+* @internal
+*/
+function noFollowFlag(constants) {
+	return constants.O_NOFOLLOW ?? 0;
+}
+/**
+* Checks whether an unknown thrown value has a specific Node error code.
+*
+* @param err - Unknown thrown value.
+* @param code - Expected Node error code.
+*
+* @returns True when the value exposes the expected code.
+*
+* @internal
+*/
+function hasErrorCode(err, code) {
+	return err.code === code;
+}
+//#endregion
+export { assertPathInsideRoot, assertSyncPathAllowed, hasErrorCode, isReservedSyncTempFileName, makeReservedSyncTempFileName, noFollowFlag, safeRelativePathSegments };
+
+//# sourceMappingURL=path-safety.js.map

package/dist/sync/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","names":[],"sources":["../../src/sync/path-safety.ts"],"sourcesContent":["const RESERVED_SYNC_TEMP_FILE_RE = /^\\.b2sdk-[0-9a-f]{24}-[^/\\\\]+-[0-9a-f]{32}\\.partial$/i\nconst UUID_HEX_RE = /^[0-9a-f]{32}$/i\n\n/**\n * Checks whether a basename is reserved for SDK-owned sync partial files.\n * @param name - Basename to inspect.\n *\n * @returns Whether the basename matches the SDK reserved partial-file pattern.\n *\n * @internal\n */\nexport function isReservedSyncTempFileName(name: string): boolean {\n  return RESERVED_SYNC_TEMP_FILE_RE.test(name)\n}\n\n/**\n * Rejects sync paths whose basename is reserved for SDK-owned temporary files.\n * @param relativePath - Sync-relative path using slash separators.\n *\n * @throws If any path segment uses the SDK's reserved temporary-file pattern.\n *\n * @internal\n */\nexport function assertSyncPathAllowed(relativePath: string): void {\n  const parts = relativePath.split(/[\\\\/]+/).filter(Boolean)\n  if (parts.some((part) => isReservedSyncTempFileName(part))) {\n    throw new Error(`Sync path uses reserved SDK temporary-file name: ${relativePath}`)\n  }\n}\n\n/**\n * Creates a download staging basename inside the SDK-reserved temp namespace.\n * @param finalName - Final destination basename.\n * @param uuid - UUID used to make the temp basename unique.\n *\n * @returns A basename that local and B2 scanners reject as SDK-owned temp data.\n *\n * @throws If the provided UUID cannot be normalized to 32 hex characters.\n *\n * @internal\n */\nexport function makeReservedSyncTempFileName(finalName: string, uuid: string): string {\n  if (finalName.length === 0 || /[\\\\/]/.test(finalName)) {\n    throw new Error('invalid sync temporary-file basename')\n  }\n  const hex = uuid.replaceAll('-', '').toLowerCase()\n  if (!UUID_HEX_RE.test(hex)) {\n    throw new Error('invalid sync temporary-file nonce')\n  }\n  return `.b2sdk-${hex.slice(0, 24)}-${finalName}-${hex}.partial`\n}\n\n/**\n * Validates B2 relative names before they are materialized on a local filesystem.\n *\n * @param relPath - B2-style relative path.\n *\n * @returns Validated path segments.\n *\n * @throws When the path is empty, absolute, platform-ambiguous, or contains traversal.\n *\n * @internal\n */\nexport function safeRelativePathSegments(relPath: string): string[] {\n  assertSyncPathAllowed(relPath)\n  if (\n    relPath.length === 0 ||\n    relPath.includes('\\0') ||\n    relPath.includes('\\\\') ||\n    relPath.startsWith('/') ||\n    /^[A-Za-z]:/.test(relPath)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n\n  const segments = relPath.split('/')\n  if (\n    segments.some(\n      (segment) =>\n        segment.length === 0 ||\n        segment === '.' ||\n        segment === '..' ||\n        segment.includes(':') ||\n        segment.endsWith('.') ||\n        segment.endsWith(' ') ||\n        WINDOWS_RESERVED_NAME.test(segment),\n    )\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n  return segments\n}\n\nconst WINDOWS_RESERVED_NAME =\n  /^(con|prn|aux|nul|conin\\$|conout\\$|com[0-9\\u00b9\\u00b2\\u00b3]|lpt[0-9\\u00b9\\u00b2\\u00b3])(?:\\..*)?$/i\n\n/**\n * Throws if {@link target} is outside {@link root} or names the root itself.\n *\n * @param root - Resolved filesystem root.\n * @param target - Candidate path to validate.\n * @param path - Node path module.\n *\n * @throws When the target is outside the root or equal to the root.\n *\n * @internal\n */\nexport function assertPathInsideRoot(\n  root: string,\n  target: string,\n  path: typeof import('node:path'),\n): void {\n  const relative = path.relative(root, target)\n  if (\n    relative.length === 0 ||\n    relative === '..' ||\n    relative.startsWith(`..${path.sep}`) ||\n    path.isAbsolute(relative)\n  ) {\n    throw new Error('unsafe local destination path')\n  }\n}\n\n/**\n * Returns the platform's no-follow open flag when available.\n *\n * @param constants - Node filesystem constants.\n *\n * @returns The `O_NOFOLLOW` bit or `0`.\n *\n * @internal\n */\nexport function noFollowFlag(constants: { readonly O_NOFOLLOW?: number }): number {\n  return constants.O_NOFOLLOW ?? 0\n}\n\n/**\n * Checks whether an unknown thrown value has a specific Node error code.\n *\n * @param err - Unknown thrown value.\n * @param code - Expected Node error code.\n *\n * @returns True when the value exposes the expected code.\n *\n * @internal\n */\nexport function hasErrorCode(err: unknown, code: string): boolean {\n  return (err as { readonly code?: unknown }).code === code\n}\n"],"mappings":";AAAA,IAAM,6BAA6B;AACnC,IAAM,cAAc;;;;;;;;;AAUpB,SAAgB,2BAA2B,MAAuB;CAChE,OAAO,2BAA2B,KAAK,IAAI;AAC7C;;;;;;;;;AAUA,SAAgB,sBAAsB,cAA4B;CAEhE,IADc,aAAa,MAAM,QAAQ,CAAC,CAAC,OAAO,OAC9C,CAAA,CAAM,MAAM,SAAS,2BAA2B,IAAI,CAAC,GACvD,MAAM,IAAI,MAAM,oDAAoD,cAAc;AAEtF;;;;;;;;;;;;AAaA,SAAgB,6BAA6B,WAAmB,MAAsB;CACpF,IAAI,UAAU,WAAW,KAAK,QAAQ,KAAK,SAAS,GAClD,MAAM,IAAI,MAAM,sCAAsC;CAExD,MAAM,MAAM,KAAK,WAAW,KAAK,EAAE,CAAC,CAAC,YAAY;CACjD,IAAI,CAAC,YAAY,KAAK,GAAG,GACvB,MAAM,IAAI,MAAM,mCAAmC;CAErD,OAAO,UAAU,IAAI,MAAM,GAAG,EAAE,EAAE,GAAG,UAAU,GAAG,IAAI;AACxD;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,SAA2B;CAClE,sBAAsB,OAAO;CAC7B,IACE,QAAQ,WAAW,KACnB,QAAQ,SAAS,IAAI,KACrB,QAAQ,SAAS,IAAI,KACrB,QAAQ,WAAW,GAAG,KACtB,aAAa,KAAK,OAAO,GAEzB,MAAM,IAAI,MAAM,+BAA+B;CAGjD,MAAM,WAAW,QAAQ,MAAM,GAAG;CAClC,IACE,SAAS,MACN,YACC,QAAQ,WAAW,KACnB,YAAY,OACZ,YAAY,QACZ,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,QAAQ,SAAS,GAAG,KACpB,sBAAsB,KAAK,OAAO,CACtC,GAEA,MAAM,IAAI,MAAM,+BAA+B;CAEjD,OAAO;AACT;AAEA,IAAM,wBACJ;;;;;;;;;;;;AAaF,SAAgB,qBACd,MACA,QACA,MACM;CACN,MAAM,WAAW,KAAK,SAAS,MAAM,MAAM;CAC3C,IACE,SAAS,WAAW,KACpB,aAAa,QACb,SAAS,WAAW,KAAK,KAAK,KAAK,KACnC,KAAK,WAAW,QAAQ,GAExB,MAAM,IAAI,MAAM,+BAA+B;AAEnD;;;;;;;;;;AAWA,SAAgB,aAAa,WAAqD;CAChF,OAAO,UAAU,cAAc;AACjC;;;;;;;;;;;AAYA,SAAgB,aAAa,KAAc,MAAuB;CAChE,OAAQ,IAAoC,SAAS;AACvD"}

package/dist/sync/paths.d.cts

@@ -0,0 +1,19 @@
+export { assertSyncPathAllowed } from './path-safety.js';
+interface PathOperations {
+    isAbsolute(path: string): boolean;
+    resolve(...paths: string[]): string;
+    readonly sep: string;
+}
+/**
+ * Resolves a sync-relative path under a local root without allowing traversal
+ * or SDK-reserved temporary-file names.
+ * @param root - Absolute local sync root.
+ * @param relativePath - Sync-relative path to resolve.
+ * @param path - Node path operations for the local platform.
+ *
+ * @returns The absolute local filesystem path.
+ *
+ * @throws If the path is absolute, escapes the root, or uses a reserved basename.
+ */
+export declare function resolveSafeLocalPath(root: string, relativePath: string, path: PathOperations): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sync/paths.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sync/paths.js"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,UAAU,cAAc;IACtB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,GACnB,MAAM,CAYR"}

package/dist/sync/paths.d.ts

@@ -0,0 +1,19 @@
+export { assertSyncPathAllowed } from './path-safety.js';
+interface PathOperations {
+    isAbsolute(path: string): boolean;
+    resolve(...paths: string[]): string;
+    readonly sep: string;
+}
+/**
+ * Resolves a sync-relative path under a local root without allowing traversal
+ * or SDK-reserved temporary-file names.
+ * @param root - Absolute local sync root.
+ * @param relativePath - Sync-relative path to resolve.
+ * @param path - Node path operations for the local platform.
+ *
+ * @returns The absolute local filesystem path.
+ *
+ * @throws If the path is absolute, escapes the root, or uses a reserved basename.
+ */
+export declare function resolveSafeLocalPath(root: string, relativePath: string, path: PathOperations): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/sync/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/sync/paths.js"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAExD,UAAU,cAAc;IACtB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,cAAc,GACnB,MAAM,CAYR"}

package/dist/sync/policies/compare.cjs

@@ -1,14 +1,392 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_concurrency = require("../../upload/concurrency.cjs");
+const require_sha1 = require("../../util/sha1.cjs");
+const require_to_error = require("../../util/to-error.cjs");
+const require_local_sha1 = require("../local-sha1.cjs");
+const require_sha1_metadata = require("../sha1-metadata.cjs");
+//#region src/sync/policies/compare.ts
+/**
+* Determines whether two files should be considered different based on the compare mode.
+* For `sha1`, callers that use the low-level policy helpers should first prepare the pair so
+* local hashes and comparable B2 hashes are populated.
+*
+* @param source - The source file metadata.
+* @param dest - The destination file metadata.
+* @param compareMode - The comparison strategy: 'modtime', 'size', 'sha1', or 'none'.
+* @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).
+*
+* @returns `true` if the files are considered different.
+*
+* @throws When `compareMode` is not one of the supported compare modes.
+*/
 function filesAreDifferent(source, dest, compareMode, threshold = 0) {
-  switch (compareMode) {
-    case "none":
-      return false;
-    case "size":
-      return Math.abs(source.size - dest.size) > threshold;
-    case "modtime":
-      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold;
-  }
+	switch (compareMode) {
+		case "none": return false;
+		case "size": return Math.abs(source.size - dest.size) > threshold;
+		case "sha1": return sha1ValuesAreDifferent(source, dest);
+		case "modtime": return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold;
+		default: throw new Error(`Unsupported compare mode: ${String(compareMode)}`);
+	}
 }
+/**
+* Throws when a runtime compare mode value is unsupported.
+*
+* @param compareMode - User-supplied compare mode.
+*
+* @throws When `compareMode` is not one of the supported values.
+*/
+function assertSupportedCompareMode(compareMode) {
+	switch (compareMode) {
+		case "none":
+		case "size":
+		case "sha1":
+		case "modtime": return;
+		default: throw new Error(`Unsupported compare mode: ${String(compareMode)}`);
+	}
+}
+function sha1ValuesAreDifferent(source, dest) {
+	if (source.size !== dest.size) return true;
+	const sourceSha1 = comparableSha1(source);
+	const destSha1 = comparableSha1(dest);
+	if (sourceSha1.kind === "untrusted" || destSha1.kind === "untrusted") return true;
+	if (sourceSha1.kind === "unavailable" || destSha1.kind === "unavailable") return true;
+	return sourceSha1.value !== destSha1.value;
+}
+/**
+* Prepares a pair for the selected compare mode.
+*
+* For `sha1`, this fills missing B2 hashes from comparable metadata and, when an explicit local
+* reader is supplied, hashes the local side only when size cannot already prove a difference.
+* Reader failures are converted into per-file sync events instead of aborting the whole run.
+*
+* @param pair - Source/destination pair from {@link zipFolders}.
+* @param compareMode - The comparison strategy.
+* @param options - Optional hashing dependencies and cancellation signal.
+*
+* @returns The prepared pair plus any preparation events.
+*/
+async function preparePairForCompare(pair, compareMode, options = {}) {
+	assertSupportedCompareMode(compareMode);
+	if (compareMode !== "sha1") return readyComparePair(pair);
+	const [source, dest] = pair;
+	if (source === null || dest === null) return readyComparePair(pair);
+	if (source.size !== dest.size) return readyComparePair(pair);
+	const metadataPair = [withB2ContentSha1(source), withB2ContentSha1(dest)];
+	if (hasUnavailableB2Sha1(metadataPair)) return skipped(metadataPair, unavailableSha1Event(metadataPair));
+	if (options.readB2Sha1 === void 0 && hasUntrustedSha1(metadataPair) && !hasVerifiableUntrustedSha1(metadataPair)) return readyComparePair(metadataPair);
+	const [metadataSource, metadataDest] = metadataPair;
+	if (metadataSource === null || metadataDest === null) return readyComparePair(metadataPair);
+	const sourceResult = await prepareLocalPathSha1(metadataSource, options);
+	if (sourceResult.aborted) return aborted(metadataPair);
+	if (sourceResult.event) return skipped(metadataPair, sourceResult.event, sourceResult.error, sourceResult.bytesHashed);
+	const destResult = await prepareLocalPathSha1(metadataDest, options);
+	if (destResult.aborted) return aborted([sourceResult.path, destResult.path]);
+	if (destResult.event) return skipped([sourceResult.path, destResult.path], destResult.event, destResult.error, sourceResult.bytesHashed);
+	const preparedPair = [sourceResult.path, destResult.path];
+	const sourceState = comparableSha1(sourceResult.path);
+	const destState = comparableSha1(destResult.path);
+	const bytesHashed = sourceResult.bytesHashed + destResult.bytesHashed;
+	if (sourceState.kind === "unavailable" || destState.kind === "unavailable") return skipped(preparedPair, unavailableSha1Event(preparedPair), void 0, bytesHashed);
+	const shouldVerifyB2Bytes = untrustedSha1CouldSuppressTransfer(sourceState, destState);
+	const readB2Sha1 = options.readB2Sha1;
+	if (shouldVerifyB2Bytes && hasB2Path(preparedPair) && readB2Sha1 !== void 0) return verifyB2Sha1Bytes(preparedPair, {
+		...options,
+		readB2Sha1
+	}, bytesHashed);
+	return readyComparePair(preparedPair, bytesHashed);
+}
+/**
+* Prepares a list of pairs for the selected compare mode with bounded concurrency.
+*
+* @param pairs - Source/destination pairs from {@link zipFolders}.
+* @param compareMode - The comparison strategy.
+* @param options - Optional hashing dependencies, cancellation signal, and concurrency.
+*
+* @returns Prepared results in the same order as the input pairs.
+*/
+async function preparePairsForCompare(pairs, compareMode, options = {}) {
+	assertSupportedCompareMode(compareMode);
+	if (compareMode !== "sha1") return pairs.map((pair) => ({
+		originalPair: pair,
+		prepared: readyComparePair(pair)
+	}));
+	return require_concurrency.mapConcurrent(pairs, normalizeConcurrency(options.concurrency), async (pair) => {
+		if (options.signal?.aborted) return {
+			originalPair: pair,
+			prepared: aborted(pair)
+		};
+		return {
+			originalPair: pair,
+			prepared: await preparePairForCompare(pair, compareMode, options)
+		};
+	});
+}
+async function prepareLocalPathSha1(path, options) {
+	if (!isLocalSyncPath(path)) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: false
+	};
+	if (options.signal?.aborted) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: true
+	};
+	try {
+		const state = require_sha1_metadata.syncSha1StateOf(path);
+		if (state.kind === "verified") return {
+			path: {
+				...path,
+				contentSha1: state.value
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		if (state.kind === "unavailable") return {
+			path: {
+				...path,
+				contentSha1: null
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		const readLocalSha1 = options.readLocalSha1;
+		if (readLocalSha1 === void 0) return {
+			path: {
+				...path,
+				contentSha1: path.contentSha1 ?? null
+			},
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: false
+		};
+		const contentSha1 = await readLocalSha1(path, options.signal, { ...options.sha1ReadTimeoutMillis !== void 0 ? { timeoutMillis: options.sha1ReadTimeoutMillis } : {} });
+		return {
+			path: {
+				...path,
+				contentSha1
+			},
+			bytesHashed: require_sha1.normalizeVerifiableSha1(contentSha1) === null ? 0 : path.size,
+			bytesVerified: 0,
+			aborted: false
+		};
+	} catch (err) {
+		if (options.signal?.aborted || require_local_sha1.isAbortError(err)) return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: true
+		};
+		const error = require_to_error.toError(err);
+		return {
+			path,
+			bytesHashed: 0,
+			event: {
+				type: "error",
+				path: path.relativePath,
+				size: 0,
+				message: `failed to hash local file for sha1 comparison: ${require_local_sha1.formatHashError(error)}`
+			},
+			error,
+			bytesVerified: 0,
+			aborted: false
+		};
+	}
+}
+async function verifyB2Sha1Bytes(pair, options, bytesHashed) {
+	const [source, dest] = pair;
+	/* v8 ignore next -- callers only verify B2 bytes for paired compare results */
+	if (source === null || dest === null) return readyComparePair(pair, bytesHashed);
+	const sourceResult = await prepareUntrustedB2PathSha1(source, options);
+	const sourceBytesVerified = sourceResult.bytesVerified;
+	if (sourceResult.aborted) return aborted(pair);
+	if (sourceResult.event) return skipped([sourceResult.path, dest], sourceResult.event, sourceResult.error, bytesHashed, sourceBytesVerified);
+	const destResult = await prepareUntrustedB2PathSha1(dest, options);
+	const bytesVerified = sourceBytesVerified + destResult.bytesVerified;
+	/* v8 ignore next -- destination abort mirrors the covered source abort path */
+	if (destResult.aborted) return aborted([sourceResult.path, destResult.path]);
+	if (destResult.event) return skipped([sourceResult.path, destResult.path], destResult.event, destResult.error, bytesHashed, bytesVerified);
+	return readyComparePair([sourceResult.path, destResult.path], bytesHashed, bytesVerified);
+}
+async function prepareUntrustedB2PathSha1(path, options) {
+	if (!isB2SyncPath(path) || comparableSha1(path).kind !== "untrusted") return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: false
+	};
+	return prepareB2PathSha1(path, options);
+}
+async function prepareB2PathSha1(path, options) {
+	/* v8 ignore next -- pre-aborted B2 reads are covered at pair level */
+	if (options.signal?.aborted) return {
+		path,
+		bytesHashed: 0,
+		bytesVerified: 0,
+		aborted: true
+	};
+	try {
+		const result = await options.readB2Sha1(path, options.signal);
+		const contentSha1 = typeof result === "object" && result !== null ? result.contentSha1 : result;
+		const bytesVerified = typeof result === "object" && result !== null ? Math.max(0, result.bytesRead) : 0;
+		const preparedPath = {
+			...path,
+			contentSha1,
+			contentSha1State: require_sha1_metadata.syncSha1StateOf({ contentSha1 })
+		};
+		if (contentSha1 === null) return {
+			path: preparedPath,
+			bytesHashed: 0,
+			bytesVerified,
+			event: unavailableSha1PathEvent(path),
+			aborted: false
+		};
+		return {
+			path: preparedPath,
+			bytesHashed: 0,
+			bytesVerified,
+			aborted: false
+		};
+	} catch (err) {
+		if (options.signal?.aborted || require_local_sha1.isAbortError(err)) return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			aborted: true
+		};
+		const error = require_to_error.toError(err);
+		return {
+			path,
+			bytesHashed: 0,
+			bytesVerified: 0,
+			event: {
+				type: "skip",
+				path: path.relativePath,
+				size: 0,
+				message: `sha1 comparison skipped because B2 verification failed: ${require_local_sha1.formatHashError(error)}`
+			},
+			aborted: false
+		};
+	}
+}
+function comparableSha1(path) {
+	const state = require_sha1_metadata.syncSha1StateOf(path);
+	if (state.kind === "verified") return {
+		kind: "verified",
+		value: state.value
+	};
+	if (state.kind === "untrusted") return {
+		kind: "untrusted",
+		value: state.value
+	};
+	return { kind: "unavailable" };
+}
+function untrustedSha1CouldSuppressTransfer(source, dest) {
+	if (source.kind === "untrusted" && dest.kind === "verified") return source.value === dest.value;
+	if (dest.kind === "untrusted" && source.kind === "verified") return dest.value === source.value;
+	if (source.kind === "untrusted" && dest.kind === "untrusted") return source.value !== null && source.value === dest.value;
+	return false;
+}
+function withB2ContentSha1(path) {
+	if (!isB2SyncPath(path) || path.contentSha1 !== void 0 || path.contentSha1State !== void 0) return path;
+	const contentSha1 = require_sha1_metadata.selectB2ComparableSha1(path.selectedVersion);
+	return {
+		...path,
+		contentSha1,
+		contentSha1State: require_sha1_metadata.syncSha1StateOf({ contentSha1 })
+	};
+}
+function hasUnavailableB2Sha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && isB2SyncPath(source) && comparableSha1(source).kind === "unavailable" || dest !== null && isB2SyncPath(dest) && comparableSha1(dest).kind === "unavailable";
+}
+function hasUntrustedSha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && comparableSha1(source).kind === "untrusted" || dest !== null && comparableSha1(dest).kind === "untrusted";
+}
+function hasVerifiableUntrustedSha1(pair) {
+	const [source, dest] = pair;
+	return source !== null && verifiableUntrustedSha1(source) || dest !== null && verifiableUntrustedSha1(dest);
+}
+function verifiableUntrustedSha1(path) {
+	const state = comparableSha1(path);
+	return state.kind === "untrusted" && state.value !== null;
+}
+function hasB2Path(pair) {
+	const [source, dest] = pair;
+	return source !== null && isB2SyncPath(source) || dest !== null && isB2SyncPath(dest);
+}
+function isB2SyncPath(path) {
+	return "selectedVersion" in path;
+}
+function isLocalSyncPath(path) {
+	return "absolutePath" in path;
+}
+/**
+* Creates a successful no-op compare preparation result for a pair.
+*
+* @param pair - Source/destination pair from {@link zipFolders}.
+* @param bytesHashed - Local file bytes read while preparing the pair.
+* @param bytesVerified - B2 bytes read while verifying untrusted SHA-1 metadata.
+*
+* @returns A ready preparation result that allows action generation.
+*/
+function readyComparePair(pair, bytesHashed = 0, bytesVerified = 0) {
+	return {
+		pair,
+		events: [],
+		errors: [],
+		bytesHashed,
+		bytesVerified,
+		skipActionGeneration: false,
+		aborted: false
+	};
+}
+function skipped(pair, event, error, bytesHashed = 0, bytesVerified = 0) {
+	return {
+		pair,
+		events: [event],
+		errors: error !== void 0 ? [error] : [],
+		bytesHashed,
+		bytesVerified,
+		skipActionGeneration: true,
+		aborted: false
+	};
+}
+function aborted(pair) {
+	return {
+		pair,
+		events: [],
+		errors: [],
+		bytesHashed: 0,
+		bytesVerified: 0,
+		skipActionGeneration: true,
+		aborted: true
+	};
+}
+function unavailableSha1Event(pair) {
+	return unavailableSha1PathEvent({ relativePath: (pair[0] ?? pair[1])?.relativePath ?? "" });
+}
+function unavailableSha1PathEvent(path) {
+	return {
+		type: "skip",
+		path: path.relativePath,
+		size: 0,
+		message: "sha1 comparison skipped because a verifiable SHA-1 is unavailable"
+	};
+}
+function normalizeConcurrency(value) {
+	if (value === void 0 || !Number.isFinite(value) || value < 1) return 1;
+	return Math.max(1, Math.floor(value));
+}
+//#endregion
+exports.assertSupportedCompareMode = assertSupportedCompareMode;
 exports.filesAreDifferent = filesAreDifferent;
-//# sourceMappingURL=compare.cjs.map
+exports.preparePairForCompare = preparePairForCompare;
+exports.preparePairsForCompare = preparePairsForCompare;
+exports.readyComparePair = readyComparePair;
+
+//# sourceMappingURL=compare.cjs.map

package/dist/sync/policies/compare.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"compare.cjs","sources":["../../../src/sync/policies/compare.ts"],"sourcesContent":["import type { CompareMode, SyncPath } from '../types.ts'\n\n/**\n * Determines whether two files should be considered different based on the compare mode.\n *\n * @param source - The source file metadata.\n * @param dest - The destination file metadata.\n * @param compareMode - The comparison strategy: 'modtime', 'size', or 'none'.\n * @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).\n *\n * @returns `true` if the files are considered different.\n */\nexport function filesAreDifferent(\n  source: SyncPath,\n  dest: SyncPath,\n  compareMode: CompareMode,\n  threshold = 0,\n): boolean {\n  switch (compareMode) {\n    case 'none':\n      return false\n    case 'size':\n      return Math.abs(source.size - dest.size) > threshold\n    case 'modtime':\n      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold\n  }\n}\n"],"names":[],"mappings":";;AAYO,SAAS,kBACd,QACA,MACA,aACA,YAAY,GACH;AACT,UAAQ,aAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO,KAAK,IAAI,OAAO,OAAO,KAAK,IAAI,IAAI;AAAA,IAC7C,KAAK;AACH,aAAO,KAAK,IAAI,OAAO,gBAAgB,KAAK,aAAa,IAAI;AAAA,EAAA;AAEnE;;"}
+{"version":3,"file":"compare.cjs","names":[],"sources":["../../../src/sync/policies/compare.ts"],"sourcesContent":["import { mapConcurrent } from '../../upload/concurrency.ts'\nimport { normalizeVerifiableSha1 } from '../../util/sha1.ts'\nimport { toError } from '../../util/to-error.ts'\nimport { formatHashError, isAbortError, type LocalSha1Reader } from '../local-sha1.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport { selectB2ComparableSha1, syncSha1StateOf } from '../sha1-metadata.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  LocalSyncPath,\n  SyncEvent,\n  SyncPath,\n  SyncSkipEvent,\n} from '../types.ts'\n\nexport { selectB2ComparableSha1 } from '../sha1-metadata.ts'\n\n/** Result from a B2 SHA-1 verification read. */\nexport interface B2Sha1ReadResult {\n  /** SHA-1 digest of the selected B2 bytes, or null when unavailable. */\n  readonly contentSha1: string | null\n  /** Number of B2 bytes downloaded and hashed while verifying. */\n  readonly bytesRead: number\n}\n\n/** Reads a B2 file and returns the SHA-1 digest of its actual bytes, or null when unavailable. */\nexport type B2Sha1Reader = (\n  path: B2SyncPath,\n  signal?: AbortSignal,\n) => Promise<string | null | B2Sha1ReadResult>\n\n/** Options for preparing a file pair before comparison. */\nexport interface PreparePairForCompareOptions {\n  /** Signal used to abort local file hashing. */\n  readonly signal?: AbortSignal\n  /** Optional idle/no-progress timeout for local SHA-1 reads. */\n  readonly sha1ReadTimeoutMillis?: number\n  /** Optional local hashing override for tests or custom runtimes. */\n  readonly readLocalSha1?: LocalSha1Reader\n  /** Optional B2 hashing override used to verify metadata matches before skipping. */\n  readonly readB2Sha1?: B2Sha1Reader\n}\n\n/** Options for preparing multiple file pairs before comparison. */\nexport interface PreparePairsForCompareOptions extends PreparePairForCompareOptions {\n  /** Maximum number of file pairs to prepare concurrently. */\n  readonly concurrency?: number\n}\n\n/** Result of preparing a file pair before policy comparison. */\nexport interface ComparePreparationResult {\n  /** The pair with compare-mode metadata populated where possible. */\n  readonly pair: SyncPair\n  /** Events surfaced while preparing the pair, such as per-file hash errors or skips. */\n  readonly events: readonly SyncEvent[]\n  /** Errors surfaced while preparing the pair. These contribute to the final summary. */\n  readonly errors: readonly Error[]\n  /** Local file bytes read for hashing while preparing this pair. */\n  readonly bytesHashed: number\n  /** B2 bytes read for untrusted metadata verification while preparing this pair. */\n  readonly bytesVerified: number\n  /** Whether action generation should be skipped for this pair. */\n  readonly skipActionGeneration: boolean\n  /** Whether preparation stopped because the abort signal fired. */\n  readonly aborted: boolean\n}\n\n/** A prepared pair result with the original pair retained for event context. */\nexport interface PreparedComparePair {\n  /** Original pair from {@link zipFolders}. */\n  readonly originalPair: SyncPair\n  /** Preparation result for the original pair. */\n  readonly prepared: ComparePreparationResult\n}\n\n/**\n * Determines whether two files should be considered different based on the compare mode.\n * For `sha1`, callers that use the low-level policy helpers should first prepare the pair so\n * local hashes and comparable B2 hashes are populated.\n *\n * @param source - The source file metadata.\n * @param dest - The destination file metadata.\n * @param compareMode - The comparison strategy: 'modtime', 'size', 'sha1', or 'none'.\n * @param threshold - Tolerance for the comparison (bytes for size, milliseconds for modtime).\n *\n * @returns `true` if the files are considered different.\n *\n * @throws When `compareMode` is not one of the supported compare modes.\n */\nexport function filesAreDifferent(\n  source: SyncPath,\n  dest: SyncPath,\n  compareMode: CompareMode,\n  threshold = 0,\n): boolean {\n  switch (compareMode) {\n    case 'none':\n      return false\n    case 'size':\n      return Math.abs(source.size - dest.size) > threshold\n    case 'sha1':\n      return sha1ValuesAreDifferent(source, dest)\n    case 'modtime':\n      return Math.abs(source.modTimeMillis - dest.modTimeMillis) > threshold\n    default:\n      throw new Error(`Unsupported compare mode: ${String(compareMode)}`)\n  }\n}\n\n/**\n * Throws when a runtime compare mode value is unsupported.\n *\n * @param compareMode - User-supplied compare mode.\n *\n * @throws When `compareMode` is not one of the supported values.\n */\nexport function assertSupportedCompareMode(\n  compareMode: unknown,\n): asserts compareMode is CompareMode {\n  switch (compareMode) {\n    case 'none':\n    case 'size':\n    case 'sha1':\n    case 'modtime':\n      return\n    default:\n      throw new Error(`Unsupported compare mode: ${String(compareMode)}`)\n  }\n}\n\nfunction sha1ValuesAreDifferent(source: SyncPath, dest: SyncPath): boolean {\n  if (source.size !== dest.size) return true\n\n  const sourceSha1 = comparableSha1(source)\n  const destSha1 = comparableSha1(dest)\n  if (sourceSha1.kind === 'untrusted' || destSha1.kind === 'untrusted') return true\n  if (sourceSha1.kind === 'unavailable' || destSha1.kind === 'unavailable') return true\n  return sourceSha1.value !== destSha1.value\n}\n\n/**\n * Prepares a pair for the selected compare mode.\n *\n * For `sha1`, this fills missing B2 hashes from comparable metadata and, when an explicit local\n * reader is supplied, hashes the local side only when size cannot already prove a difference.\n * Reader failures are converted into per-file sync events instead of aborting the whole run.\n *\n * @param pair - Source/destination pair from {@link zipFolders}.\n * @param compareMode - The comparison strategy.\n * @param options - Optional hashing dependencies and cancellation signal.\n *\n * @returns The prepared pair plus any preparation events.\n */\nexport async function preparePairForCompare(\n  pair: SyncPair,\n  compareMode: CompareMode,\n  options: PreparePairForCompareOptions = {},\n): Promise<ComparePreparationResult> {\n  assertSupportedCompareMode(compareMode)\n  if (compareMode !== 'sha1') return readyComparePair(pair)\n\n  const [source, dest] = pair\n  if (source === null || dest === null) return readyComparePair(pair)\n  if (source.size !== dest.size) return readyComparePair(pair)\n\n  const metadataPair: SyncPair = [withB2ContentSha1(source), withB2ContentSha1(dest)]\n  if (hasUnavailableB2Sha1(metadataPair)) {\n    return skipped(metadataPair, unavailableSha1Event(metadataPair))\n  }\n  if (\n    options.readB2Sha1 === undefined &&\n    hasUntrustedSha1(metadataPair) &&\n    !hasVerifiableUntrustedSha1(metadataPair)\n  ) {\n    return readyComparePair(metadataPair)\n  }\n\n  const [metadataSource, metadataDest] = metadataPair\n  if (metadataSource === null || metadataDest === null) return readyComparePair(metadataPair)\n\n  const sourceResult = await prepareLocalPathSha1(metadataSource, options)\n  if (sourceResult.aborted) return aborted(metadataPair)\n  if (sourceResult.event) {\n    return skipped(metadataPair, sourceResult.event, sourceResult.error, sourceResult.bytesHashed)\n  }\n\n  const destResult = await prepareLocalPathSha1(metadataDest, options)\n  if (destResult.aborted) return aborted([sourceResult.path, destResult.path])\n  if (destResult.event) {\n    return skipped(\n      [sourceResult.path, destResult.path],\n      destResult.event,\n      destResult.error,\n      sourceResult.bytesHashed,\n    )\n  }\n\n  const preparedPair: SyncPair = [sourceResult.path, destResult.path]\n  const sourceState = comparableSha1(sourceResult.path)\n  const destState = comparableSha1(destResult.path)\n  const bytesHashed = sourceResult.bytesHashed + destResult.bytesHashed\n\n  if (sourceState.kind === 'unavailable' || destState.kind === 'unavailable') {\n    return skipped(preparedPair, unavailableSha1Event(preparedPair), undefined, bytesHashed)\n  }\n\n  const shouldVerifyB2Bytes = untrustedSha1CouldSuppressTransfer(sourceState, destState)\n  const readB2Sha1 = options.readB2Sha1\n  if (shouldVerifyB2Bytes && hasB2Path(preparedPair) && readB2Sha1 !== undefined) {\n    return verifyB2Sha1Bytes(preparedPair, { ...options, readB2Sha1 }, bytesHashed)\n  }\n\n  return readyComparePair(preparedPair, bytesHashed)\n}\n\n/**\n * Prepares a list of pairs for the selected compare mode with bounded concurrency.\n *\n * @param pairs - Source/destination pairs from {@link zipFolders}.\n * @param compareMode - The comparison strategy.\n * @param options - Optional hashing dependencies, cancellation signal, and concurrency.\n *\n * @returns Prepared results in the same order as the input pairs.\n */\nexport async function preparePairsForCompare(\n  pairs: readonly SyncPair[],\n  compareMode: CompareMode,\n  options: PreparePairsForCompareOptions = {},\n): Promise<PreparedComparePair[]> {\n  assertSupportedCompareMode(compareMode)\n  if (compareMode !== 'sha1') {\n    return pairs.map((pair) => ({ originalPair: pair, prepared: readyComparePair(pair) }))\n  }\n\n  const concurrency = normalizeConcurrency(options.concurrency)\n  return mapConcurrent(pairs, concurrency, async (pair): Promise<PreparedComparePair> => {\n    if (options.signal?.aborted) return { originalPair: pair, prepared: aborted(pair) }\n    return {\n      originalPair: pair,\n      prepared: await preparePairForCompare(pair, compareMode, options),\n    }\n  })\n}\n\ntype Sha1State =\n  | { readonly kind: 'verified'; readonly value: string }\n  | { readonly kind: 'untrusted'; readonly value: string | null }\n  | { readonly kind: 'unavailable' }\n\ninterface PreparedPath {\n  readonly path: SyncPath\n  readonly bytesHashed: number\n  readonly bytesVerified: number\n  readonly event?: SyncEvent\n  readonly error?: Error\n  readonly aborted: boolean\n}\n\nasync function prepareLocalPathSha1(\n  path: SyncPath,\n  options: PreparePairForCompareOptions,\n): Promise<PreparedPath> {\n  if (!isLocalSyncPath(path)) {\n    return { path, bytesHashed: 0, bytesVerified: 0, aborted: false }\n  }\n\n  if (options.signal?.aborted) return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n\n  try {\n    const state = syncSha1StateOf(path)\n    if (state.kind === 'verified') {\n      return {\n        path: { ...path, contentSha1: state.value },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n    if (state.kind === 'unavailable') {\n      return {\n        path: { ...path, contentSha1: null },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n\n    const readLocalSha1 = options.readLocalSha1\n    if (readLocalSha1 === undefined) {\n      return {\n        path: { ...path, contentSha1: path.contentSha1 ?? null },\n        bytesHashed: 0,\n        bytesVerified: 0,\n        aborted: false,\n      }\n    }\n    const contentSha1 = await readLocalSha1(path, options.signal, {\n      ...(options.sha1ReadTimeoutMillis !== undefined\n        ? { timeoutMillis: options.sha1ReadTimeoutMillis }\n        : {}),\n    })\n    return {\n      path: {\n        ...path,\n        contentSha1,\n      },\n      bytesHashed: normalizeVerifiableSha1(contentSha1) === null ? 0 : path.size,\n      bytesVerified: 0,\n      aborted: false,\n    }\n  } catch (err) {\n    if (options.signal?.aborted || isAbortError(err)) {\n      return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n    }\n    const error = toError(err)\n    return {\n      path,\n      bytesHashed: 0,\n      event: {\n        type: 'error',\n        path: path.relativePath,\n        size: 0,\n        message: `failed to hash local file for sha1 comparison: ${formatHashError(error)}`,\n      },\n      error,\n      bytesVerified: 0,\n      aborted: false,\n    }\n  }\n}\n\nasync function verifyB2Sha1Bytes(\n  pair: SyncPair,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n  bytesHashed: number,\n): Promise<ComparePreparationResult> {\n  const [source, dest] = pair\n  /* v8 ignore next -- callers only verify B2 bytes for paired compare results */\n  if (source === null || dest === null) return readyComparePair(pair, bytesHashed)\n\n  const sourceResult = await prepareUntrustedB2PathSha1(source, options)\n  const sourceBytesVerified = sourceResult.bytesVerified\n  if (sourceResult.aborted) return aborted(pair)\n  if (sourceResult.event) {\n    return skipped(\n      [sourceResult.path, dest],\n      sourceResult.event,\n      sourceResult.error,\n      bytesHashed,\n      sourceBytesVerified,\n    )\n  }\n\n  const destResult = await prepareUntrustedB2PathSha1(dest, options)\n  const bytesVerified = sourceBytesVerified + destResult.bytesVerified\n  /* v8 ignore next -- destination abort mirrors the covered source abort path */\n  if (destResult.aborted) return aborted([sourceResult.path, destResult.path])\n  if (destResult.event) {\n    return skipped(\n      [sourceResult.path, destResult.path],\n      destResult.event,\n      destResult.error,\n      bytesHashed,\n      bytesVerified,\n    )\n  }\n\n  return readyComparePair([sourceResult.path, destResult.path], bytesHashed, bytesVerified)\n}\n\nasync function prepareUntrustedB2PathSha1(\n  path: SyncPath,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n): Promise<PreparedPath> {\n  if (!isB2SyncPath(path) || comparableSha1(path).kind !== 'untrusted') {\n    return { path, bytesHashed: 0, bytesVerified: 0, aborted: false }\n  }\n  return prepareB2PathSha1(path, options)\n}\n\nasync function prepareB2PathSha1(\n  path: B2SyncPath,\n  options: PreparePairForCompareOptions & { readonly readB2Sha1: B2Sha1Reader },\n): Promise<PreparedPath> {\n  /* v8 ignore next -- pre-aborted B2 reads are covered at pair level */\n  if (options.signal?.aborted) return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n\n  try {\n    const result = await options.readB2Sha1(path, options.signal)\n    const contentSha1 = typeof result === 'object' && result !== null ? result.contentSha1 : result\n    const bytesVerified =\n      typeof result === 'object' && result !== null ? Math.max(0, result.bytesRead) : 0\n    const preparedPath = {\n      ...path,\n      contentSha1,\n      contentSha1State: syncSha1StateOf({ contentSha1 }),\n    }\n    if (contentSha1 === null) {\n      return {\n        path: preparedPath,\n        bytesHashed: 0,\n        bytesVerified,\n        event: unavailableSha1PathEvent(path),\n        aborted: false,\n      }\n    }\n    return {\n      path: preparedPath,\n      bytesHashed: 0,\n      bytesVerified,\n      aborted: false,\n    }\n  } catch (err) {\n    if (options.signal?.aborted || isAbortError(err)) {\n      return { path, bytesHashed: 0, bytesVerified: 0, aborted: true }\n    }\n    const error = toError(err)\n    return {\n      path,\n      bytesHashed: 0,\n      bytesVerified: 0,\n      event: {\n        type: 'skip',\n        path: path.relativePath,\n        size: 0,\n        message: `sha1 comparison skipped because B2 verification failed: ${formatHashError(error)}`,\n      },\n      aborted: false,\n    }\n  }\n}\n\nfunction comparableSha1(path: SyncPath): Sha1State {\n  const state = syncSha1StateOf(path)\n  if (state.kind === 'verified') return { kind: 'verified', value: state.value }\n  if (state.kind === 'untrusted') return { kind: 'untrusted', value: state.value }\n  return { kind: 'unavailable' }\n}\n\nfunction untrustedSha1CouldSuppressTransfer(source: Sha1State, dest: Sha1State): boolean {\n  if (source.kind === 'untrusted' && dest.kind === 'verified') return source.value === dest.value\n  if (dest.kind === 'untrusted' && source.kind === 'verified') return dest.value === source.value\n  if (source.kind === 'untrusted' && dest.kind === 'untrusted') {\n    return source.value !== null && source.value === dest.value\n  }\n  return false\n}\n\nfunction withB2ContentSha1(path: SyncPath): SyncPath {\n  if (\n    !isB2SyncPath(path) ||\n    path.contentSha1 !== undefined ||\n    path.contentSha1State !== undefined\n  ) {\n    return path\n  }\n  const contentSha1 = selectB2ComparableSha1(path.selectedVersion)\n  return { ...path, contentSha1, contentSha1State: syncSha1StateOf({ contentSha1 }) }\n}\n\nfunction hasUnavailableB2Sha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && isB2SyncPath(source) && comparableSha1(source).kind === 'unavailable') ||\n    (dest !== null && isB2SyncPath(dest) && comparableSha1(dest).kind === 'unavailable')\n  )\n}\n\nfunction hasUntrustedSha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && comparableSha1(source).kind === 'untrusted') ||\n    (dest !== null && comparableSha1(dest).kind === 'untrusted')\n  )\n}\n\nfunction hasVerifiableUntrustedSha1(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (\n    (source !== null && verifiableUntrustedSha1(source)) ||\n    (dest !== null && verifiableUntrustedSha1(dest))\n  )\n}\n\nfunction verifiableUntrustedSha1(path: SyncPath): boolean {\n  const state = comparableSha1(path)\n  return state.kind === 'untrusted' && state.value !== null\n}\n\nfunction hasB2Path(pair: SyncPair): boolean {\n  const [source, dest] = pair\n  return (source !== null && isB2SyncPath(source)) || (dest !== null && isB2SyncPath(dest))\n}\n\nfunction isB2SyncPath(path: SyncPath): path is B2SyncPath {\n  return 'selectedVersion' in path\n}\n\nfunction isLocalSyncPath(path: SyncPath): path is LocalSyncPath {\n  return 'absolutePath' in path\n}\n\n/**\n * Creates a successful no-op compare preparation result for a pair.\n *\n * @param pair - Source/destination pair from {@link zipFolders}.\n * @param bytesHashed - Local file bytes read while preparing the pair.\n * @param bytesVerified - B2 bytes read while verifying untrusted SHA-1 metadata.\n *\n * @returns A ready preparation result that allows action generation.\n */\nexport function readyComparePair(\n  pair: SyncPair,\n  bytesHashed = 0,\n  bytesVerified = 0,\n): ComparePreparationResult {\n  return {\n    pair,\n    events: [],\n    errors: [],\n    bytesHashed,\n    bytesVerified,\n    skipActionGeneration: false,\n    aborted: false,\n  }\n}\n\nfunction skipped(\n  pair: SyncPair,\n  event: SyncEvent,\n  error?: Error,\n  bytesHashed = 0,\n  bytesVerified = 0,\n): ComparePreparationResult {\n  return {\n    pair,\n    events: [event],\n    errors: error !== undefined ? [error] : [],\n    bytesHashed,\n    bytesVerified,\n    skipActionGeneration: true,\n    aborted: false,\n  }\n}\n\nfunction aborted(pair: SyncPair): ComparePreparationResult {\n  return {\n    pair,\n    events: [],\n    errors: [],\n    bytesHashed: 0,\n    bytesVerified: 0,\n    skipActionGeneration: true,\n    aborted: true,\n  }\n}\n\nfunction unavailableSha1Event(pair: SyncPair): SyncSkipEvent {\n  /* v8 ignore next -- unavailable SHA-1 events always have at least one side */\n  const path = (pair[0] ?? pair[1])?.relativePath ?? ''\n  return unavailableSha1PathEvent({ relativePath: path })\n}\n\nfunction unavailableSha1PathEvent(path: Pick<SyncPath, 'relativePath'>): SyncSkipEvent {\n  return {\n    type: 'skip',\n    path: path.relativePath,\n    size: 0,\n    message: 'sha1 comparison skipped because a verifiable SHA-1 is unavailable',\n  }\n}\n\nfunction normalizeConcurrency(value: number | undefined): number {\n  if (value === undefined || !Number.isFinite(value) || value < 1) return 1\n  return Math.max(1, Math.floor(value))\n}\n"],"mappings":"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"}