@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/sync/policies/index.cjs

@@ -1,74 +1,79 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const index = require("../actions/index.cjs");
-const compare = require("./compare.cjs");
+const require_index = require("../actions/index.cjs");
+const require_compare = require("./compare.cjs");
+//#region src/sync/policies/index.ts
+/**
+* Converts a paired source/dest tuple into zero or more sync actions based on the
+* sync direction, compare mode, and keep policy.
+* For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local
+* file hashes and comparable B2 hashes are prepared before actions are generated.
+* Low-level callers must pass pairs with local `contentSha1` values already
+* computed and B2 `contentSha1` values containing any comparable metadata fallback.
+*
+* @param pair - The source/dest file pair from {@link zipFolders}.
+* @param direction - The sync direction.
+* @param compareMode - How to compare files for differences.
+* @param keepMode - Policy for destination-only files.
+* @param keepDays - Retention period when keepMode is 'keep-days'.
+* @param nowMillis - Current time in milliseconds, used for keep-days calculation.
+* @param factory - Factory to create the concrete action objects.
+* @param compareThreshold - Tolerance for the comparison.
+*/
 function* generateActions(pair, direction, compareMode, keepMode, keepDays, nowMillis, factory, compareThreshold) {
-  const [source, dest] = pair;
-  if (source !== null && dest === null) {
-    yield* actionsForSourceOnly(source, direction, factory);
-  } else if (source === null && dest !== null) {
-    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory);
-  } else if (source !== null && dest !== null) {
-    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory);
-  }
+	require_compare.assertSupportedCompareMode(compareMode);
+	const [source, dest] = pair;
+	if (source !== null && dest === null) yield* actionsForSourceOnly(source, direction, factory);
+	else if (source === null && dest !== null) yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory);
+	else if (source !== null && dest !== null) yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory);
 }
 function* actionsForSourceOnly(source, direction, factory) {
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.upload(source);
-      break;
-    case "b2-to-local":
-      yield factory.download(source);
-      break;
-    case "b2-to-b2":
-      yield factory.copy(source, source.relativePath);
-      break;
-  }
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.upload(source);
+			break;
+		case "b2-to-local":
+			yield factory.download(source, null);
+			break;
+		case "b2-to-b2": yield factory.copy(source, source.relativePath);
+	}
 }
 function* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory) {
-  if (keepMode === "no-delete") {
-    yield new index.SkipAction(dest.relativePath, "not in source, keep-mode is no-delete");
-    return;
-  }
-  if (keepMode === "keep-days") {
-    const ageMillis = nowMillis - dest.modTimeMillis;
-    const ageDays = ageMillis / (24 * 60 * 60 * 1e3);
-    if (ageDays < keepDays) {
-      yield new index.SkipAction(
-        dest.relativePath,
-        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`
-      );
-      return;
-    }
-  }
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.removeOrphan(dest);
-      break;
-    case "b2-to-local":
-      yield factory.deleteLocal(dest);
-      break;
-    case "b2-to-b2":
-      yield factory.removeOrphan(dest);
-      break;
-  }
+	if (keepMode === "no-delete") {
+		yield new require_index.SkipAction(dest.relativePath, "not in source, keep-mode is no-delete");
+		return;
+	}
+	if (keepMode === "keep-days") {
+		const ageDays = (nowMillis - dest.modTimeMillis) / 864e5;
+		if (ageDays < keepDays) {
+			yield new require_index.SkipAction(dest.relativePath, `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`);
+			return;
+		}
+	}
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.removeOrphan(dest);
+			break;
+		case "b2-to-local":
+			yield factory.deleteLocal(dest);
+			break;
+		case "b2-to-b2": yield factory.removeOrphan(dest);
+	}
 }
 function* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory) {
-  if (!compare.filesAreDifferent(source, dest, compareMode, compareThreshold)) {
-    yield new index.SkipAction(source.relativePath, "files are the same");
-    return;
-  }
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.upload(source);
-      break;
-    case "b2-to-local":
-      yield factory.download(source);
-      break;
-    case "b2-to-b2":
-      yield factory.copy(source, dest.relativePath);
-      break;
-  }
+	if (!require_compare.filesAreDifferent(source, dest, compareMode, compareThreshold)) {
+		yield new require_index.SkipAction(source.relativePath, "files are the same");
+		return;
+	}
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.upload(source, dest);
+			break;
+		case "b2-to-local":
+			yield factory.download(source, dest);
+			break;
+		case "b2-to-b2": yield factory.copyB2Path?.(source, dest) ?? factory.copy(source, dest.relativePath);
+	}
 }
+//#endregion
 exports.generateActions = generateActions;
-//# sourceMappingURL=index.cjs.map
+
+//# sourceMappingURL=index.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../../../src/sync/policies/index.ts"],"sourcesContent":["import type { SyncAction } from '../actions/index.ts'\nimport { SkipAction } from '../actions/index.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  KeepMode,\n  LocalSyncPath,\n  SyncDirection,\n  SyncPath,\n} from '../types.ts'\nimport { filesAreDifferent } from './compare.ts'\n\n/** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */\nexport interface ActionFactory {\n  /** Creates an action to upload a local file to B2. */\n  upload(source: LocalSyncPath): SyncAction\n  /** Creates an action to download a B2 file to the local filesystem. */\n  download(source: B2SyncPath): SyncAction\n  /** Creates an action to server-side copy a B2 file to a new destination path. */\n  copy(source: B2SyncPath, destPath: string): SyncAction\n  /** Creates an action to hide a file in B2 (soft delete). */\n  hide(path: string): SyncAction\n  /** Creates an action to permanently delete a remote B2 file version. */\n  deleteRemote(path: B2SyncPath): SyncAction\n  /** Creates an action to delete a local file. */\n  deleteLocal(path: LocalSyncPath): SyncAction\n  /**\n   * Creates the right \"remove this orphan from B2\" action for the bucket's\n   * configuration: a hide on a file-lock-enabled bucket (where direct\n   * delete may be blocked or stack hide markers), a plain\n   * delete-file-version on a vanilla bucket. Used by `actionsForDestOnly`\n   * to avoid yielding both a hide AND a delete when only one of them is\n   * the correct semantic for the destination bucket.\n   */\n  removeOrphan(dest: B2SyncPath): SyncAction\n}\n\n/**\n * Converts a paired source/dest tuple into zero or more sync actions based on the\n * sync direction, compare mode, and keep policy.\n *\n * @param pair - The source/dest file pair from {@link zipFolders}.\n * @param direction - The sync direction.\n * @param compareMode - How to compare files for differences.\n * @param keepMode - Policy for destination-only files.\n * @param keepDays - Retention period when keepMode is 'keep-days'.\n * @param nowMillis - Current time in milliseconds, used for keep-days calculation.\n * @param factory - Factory to create the concrete action objects.\n * @param compareThreshold - Tolerance for the comparison.\n */\nexport function* generateActions(\n  pair: SyncPair,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n  compareThreshold: number,\n): Generator<SyncAction> {\n  const [source, dest] = pair\n\n  if (source !== null && dest === null) {\n    yield* actionsForSourceOnly(source, direction, factory)\n  } else if (source === null && dest !== null) {\n    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory)\n  } else if (source !== null && dest !== null) {\n    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory)\n  }\n}\n\nfunction* actionsForSourceOnly(\n  source: SyncPath,\n  direction: SyncDirection,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, source.relativePath)\n      break\n  }\n}\n\nfunction* actionsForDestOnly(\n  dest: SyncPath,\n  direction: SyncDirection,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (keepMode === 'no-delete') {\n    yield new SkipAction(dest.relativePath, 'not in source, keep-mode is no-delete')\n    return\n  }\n\n  if (keepMode === 'keep-days') {\n    const ageMillis = nowMillis - dest.modTimeMillis\n    const ageDays = ageMillis / (24 * 60 * 60 * 1000)\n    if (ageDays < keepDays) {\n      yield new SkipAction(\n        dest.relativePath,\n        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`,\n      )\n      return\n    }\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      // Single action — `removeOrphan` picks hide vs delete based on\n      // the destination bucket's `fileLockEnabled` state. The previous\n      // \"yield both\" behaviour stacked hide markers on vanilla buckets\n      // even though the delete that followed made them redundant.\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.deleteLocal(dest as LocalSyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n  }\n}\n\nfunction* actionsForBoth(\n  source: SyncPath,\n  dest: SyncPath,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  compareThreshold: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {\n    yield new SkipAction(source.relativePath, 'files are the same')\n    return\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, dest.relativePath)\n      break\n  }\n}\n"],"names":["SkipAction","filesAreDifferent"],"mappings":";;;;AAmDO,UAAU,gBACf,MACA,WACA,aACA,UACA,UACA,WACA,SACA,kBACuB;AACvB,QAAM,CAAC,QAAQ,IAAI,IAAI;AAEvB,MAAI,WAAW,QAAQ,SAAS,MAAM;AACpC,WAAO,qBAAqB,QAAQ,WAAW,OAAO;AAAA,EACxD,WAAW,WAAW,QAAQ,SAAS,MAAM;AAC3C,WAAO,mBAAmB,MAAM,WAAW,UAAU,UAAU,WAAW,OAAO;AAAA,EACnF,WAAW,WAAW,QAAQ,SAAS,MAAM;AAC3C,WAAO,eAAe,QAAQ,MAAM,WAAW,aAAa,kBAAkB,OAAO;AAAA,EACvF;AACF;AAEA,UAAU,qBACR,QACA,WACA,SACuB;AACvB,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,YAAM,QAAQ,OAAO,MAAuB;AAC5C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,SAAS,MAAoB;AAC3C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;AAC5D;AAAA,EAAA;AAEN;AAEA,UAAU,mBACR,MACA,WACA,UACA,UACA,WACA,SACuB;AACvB,MAAI,aAAa,aAAa;AAC5B,UAAM,IAAIA,MAAAA,WAAW,KAAK,cAAc,uCAAuC;AAC/E;AAAA,EACF;AAEA,MAAI,aAAa,aAAa;AAC5B,UAAM,YAAY,YAAY,KAAK;AACnC,UAAM,UAAU,aAAa,KAAK,KAAK,KAAK;AAC5C,QAAI,UAAU,UAAU;AACtB,YAAM,IAAIA,MAAAA;AAAAA,QACR,KAAK;AAAA,QACL,8BAA8B,KAAK,KAAK,WAAW,OAAO,CAAC;AAAA,MAAA;AAE7D;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,WAAA;AAAA,IACN,KAAK;AAKH,YAAM,QAAQ,aAAa,IAAkB;AAC7C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,YAAY,IAAqB;AAC/C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,aAAa,IAAkB;AAC7C;AAAA,EAAA;AAEN;AAEA,UAAU,eACR,QACA,MACA,WACA,aACA,kBACA,SACuB;AACvB,MAAI,CAACC,QAAAA,kBAAkB,QAAQ,MAAM,aAAa,gBAAgB,GAAG;AACnE,UAAM,IAAID,MAAAA,WAAW,OAAO,cAAc,oBAAoB;AAC9D;AAAA,EACF;AAEA,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,YAAM,QAAQ,OAAO,MAAuB;AAC5C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,SAAS,MAAoB;AAC3C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,KAAK,QAAsB,KAAK,YAAY;AAC1D;AAAA,EAAA;AAEN;;"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/sync/policies/index.ts"],"sourcesContent":["import type { SyncAction } from '../actions/index.ts'\nimport { SkipAction } from '../actions/index.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  KeepMode,\n  LocalSyncPath,\n  SyncDirection,\n  SyncPath,\n} from '../types.ts'\nimport { assertSupportedCompareMode, filesAreDifferent } from './compare.ts'\n\n/** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */\nexport interface ActionFactory {\n  /** Creates an action to upload a local file to B2. */\n  upload(source: LocalSyncPath, dest?: B2SyncPath): SyncAction\n  /**\n   * Creates an action to download a B2 file to the local filesystem.\n   *\n   * `generateActions` passes `null` when the B2 source has no scanned local\n   * destination, a `LocalSyncPath` when the download replaces an existing\n   * scanned destination file, and leaves the value `undefined` only for\n   * callers that invoke a factory without destination scan context.\n   */\n  download(source: B2SyncPath, scannedDest?: LocalSyncPath | null): SyncAction\n  /**\n   * Creates an action to server-side copy a B2 file to a sync-relative destination path.\n   * Kept for compatibility with custom factories that accept a sync-relative string.\n   */\n  copy(source: B2SyncPath, destRelativePath: string): SyncAction\n  /**\n   * Creates an action to server-side copy a B2 file using full destination path metadata.\n   * Implementations can use `dest.selectedVersion.fileName` when a raw B2 prefix or normalized\n   * sync path differs from the stored object key.\n   */\n  copyB2Path?(source: B2SyncPath, dest: B2SyncPath): SyncAction\n  /**\n   * Creates an action to hide a file in B2 (soft delete).\n   * Kept for compatibility with custom factories that accept a sync-relative string.\n   */\n  hide(path: string): SyncAction\n  /**\n   * Creates an action to hide a B2 file using its full scanned path metadata.\n   * Implementations can use `selectedVersion.fileName` when a raw B2 prefix or normalized sync path\n   * differs from the stored object key.\n   */\n  hideB2Path?(path: B2SyncPath): SyncAction\n  /** Creates an action to permanently delete a remote B2 file version. */\n  deleteRemote(path: B2SyncPath): SyncAction\n  /** Creates an action to delete a local file. */\n  deleteLocal(path: LocalSyncPath): SyncAction\n  /**\n   * Creates the right \"remove this orphan from B2\" action for the bucket's\n   * configuration: a hide on a file-lock-enabled bucket (where direct\n   * delete may be blocked or stack hide markers), a plain\n   * delete-file-version on a vanilla bucket. Used by `actionsForDestOnly`\n   * to avoid yielding both a hide AND a delete when only one of them is\n   * the correct semantic for the destination bucket.\n   */\n  removeOrphan(dest: B2SyncPath): SyncAction\n}\n\n/**\n * Converts a paired source/dest tuple into zero or more sync actions based on the\n * sync direction, compare mode, and keep policy.\n * For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local\n * file hashes and comparable B2 hashes are prepared before actions are generated.\n * Low-level callers must pass pairs with local `contentSha1` values already\n * computed and B2 `contentSha1` values containing any comparable metadata fallback.\n *\n * @param pair - The source/dest file pair from {@link zipFolders}.\n * @param direction - The sync direction.\n * @param compareMode - How to compare files for differences.\n * @param keepMode - Policy for destination-only files.\n * @param keepDays - Retention period when keepMode is 'keep-days'.\n * @param nowMillis - Current time in milliseconds, used for keep-days calculation.\n * @param factory - Factory to create the concrete action objects.\n * @param compareThreshold - Tolerance for the comparison.\n */\nexport function* generateActions(\n  pair: SyncPair,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n  compareThreshold: number,\n): Generator<SyncAction> {\n  assertSupportedCompareMode(compareMode)\n\n  const [source, dest] = pair\n\n  if (source !== null && dest === null) {\n    yield* actionsForSourceOnly(source, direction, factory)\n  } else if (source === null && dest !== null) {\n    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory)\n  } else if (source !== null && dest !== null) {\n    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory)\n  }\n}\n\nfunction* actionsForSourceOnly(\n  source: SyncPath,\n  direction: SyncDirection,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath, null)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, source.relativePath)\n      break\n  }\n}\n\nfunction* actionsForDestOnly(\n  dest: SyncPath,\n  direction: SyncDirection,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (keepMode === 'no-delete') {\n    yield new SkipAction(dest.relativePath, 'not in source, keep-mode is no-delete')\n    return\n  }\n\n  if (keepMode === 'keep-days') {\n    const ageMillis = nowMillis - dest.modTimeMillis\n    const ageDays = ageMillis / (24 * 60 * 60 * 1000)\n    if (ageDays < keepDays) {\n      yield new SkipAction(\n        dest.relativePath,\n        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`,\n      )\n      return\n    }\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      // Single action — `removeOrphan` picks hide vs delete based on\n      // the destination bucket's `fileLockEnabled` state. The previous\n      // \"yield both\" behaviour stacked hide markers on vanilla buckets\n      // even though the delete that followed made them redundant.\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.deleteLocal(dest as LocalSyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n  }\n}\n\nfunction* actionsForBoth(\n  source: SyncPath,\n  dest: SyncPath,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  compareThreshold: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {\n    yield new SkipAction(source.relativePath, 'files are the same')\n    return\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath, dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath, dest as LocalSyncPath)\n      break\n    case 'b2-to-b2': {\n      const action =\n        factory.copyB2Path?.(source as B2SyncPath, dest as B2SyncPath) ??\n        factory.copy(source as B2SyncPath, dest.relativePath)\n      yield action\n      break\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgFA,UAAiB,gBACf,MACA,WACA,aACA,UACA,UACA,WACA,SACA,kBACuB;CACvB,gBAAA,2BAA2B,WAAW;CAEtC,MAAM,CAAC,QAAQ,QAAQ;CAEvB,IAAI,WAAW,QAAQ,SAAS,MAC9B,OAAO,qBAAqB,QAAQ,WAAW,OAAO;MACjD,IAAI,WAAW,QAAQ,SAAS,MACrC,OAAO,mBAAmB,MAAM,WAAW,UAAU,UAAU,WAAW,OAAO;MAC5E,IAAI,WAAW,QAAQ,SAAS,MACrC,OAAO,eAAe,QAAQ,MAAM,WAAW,aAAa,kBAAkB,OAAO;AAEzF;AAEA,UAAU,qBACR,QACA,WACA,SACuB;CACvB,QAAQ,WAAR;EACE,KAAK;GACH,MAAM,QAAQ,OAAO,MAAuB;GAC5C;EACF,KAAK;GACH,MAAM,QAAQ,SAAS,QAAsB,IAAI;GACjD;EACF,KAAK,YACH,MAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;CAEhE;AACF;AAEA,UAAU,mBACR,MACA,WACA,UACA,UACA,WACA,SACuB;CACvB,IAAI,aAAa,aAAa;EAC5B,MAAM,IAAI,cAAA,WAAW,KAAK,cAAc,uCAAuC;EAC/E;CACF;CAEA,IAAI,aAAa,aAAa;EAE5B,MAAM,WADY,YAAY,KAAK,iBACN;EAC7B,IAAI,UAAU,UAAU;GACtB,MAAM,IAAI,cAAA,WACR,KAAK,cACL,8BAA8B,KAAK,KAAK,WAAW,OAAO,EAAE,WAC9D;GACA;EACF;CACF;CAEA,QAAQ,WAAR;EACE,KAAK;GAKH,MAAM,QAAQ,aAAa,IAAkB;GAC7C;EACF,KAAK;GACH,MAAM,QAAQ,YAAY,IAAqB;GAC/C;EACF,KAAK,YACH,MAAM,QAAQ,aAAa,IAAkB;CAEjD;AACF;AAEA,UAAU,eACR,QACA,MACA,WACA,aACA,kBACA,SACuB;CACvB,IAAI,CAAC,gBAAA,kBAAkB,QAAQ,MAAM,aAAa,gBAAgB,GAAG;EACnE,MAAM,IAAI,cAAA,WAAW,OAAO,cAAc,oBAAoB;EAC9D;CACF;CAEA,QAAQ,WAAR;EACE,KAAK;GACH,MAAM,QAAQ,OAAO,QAAyB,IAAkB;GAChE;EACF,KAAK;GACH,MAAM,QAAQ,SAAS,QAAsB,IAAqB;GAClE;EACF,KAAK,YAIH,MAFE,QAAQ,aAAa,QAAsB,IAAkB,KAC7D,QAAQ,KAAK,QAAsB,KAAK,YAAY;CAI1D;AACF"}

package/dist/sync/policies/index.d.cts

@@ -4,13 +4,38 @@ import { B2SyncPath, CompareMode, KeepMode, LocalSyncPath, SyncDirection } from
 /** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */
 export interface ActionFactory {
     /** Creates an action to upload a local file to B2. */
-    upload(source: LocalSyncPath): SyncAction;
-    /** Creates an action to download a B2 file to the local filesystem. */
-    download(source: B2SyncPath): SyncAction;
-    /** Creates an action to server-side copy a B2 file to a new destination path. */
-    copy(source: B2SyncPath, destPath: string): SyncAction;
-    /** Creates an action to hide a file in B2 (soft delete). */
+    upload(source: LocalSyncPath, dest?: B2SyncPath): SyncAction;
+    /**
+     * Creates an action to download a B2 file to the local filesystem.
+     *
+     * `generateActions` passes `null` when the B2 source has no scanned local
+     * destination, a `LocalSyncPath` when the download replaces an existing
+     * scanned destination file, and leaves the value `undefined` only for
+     * callers that invoke a factory without destination scan context.
+     */
+    download(source: B2SyncPath, scannedDest?: LocalSyncPath | null): SyncAction;
+    /**
+     * Creates an action to server-side copy a B2 file to a sync-relative destination path.
+     * Kept for compatibility with custom factories that accept a sync-relative string.
+     */
+    copy(source: B2SyncPath, destRelativePath: string): SyncAction;
+    /**
+     * Creates an action to server-side copy a B2 file using full destination path metadata.
+     * Implementations can use `dest.selectedVersion.fileName` when a raw B2 prefix or normalized
+     * sync path differs from the stored object key.
+     */
+    copyB2Path?(source: B2SyncPath, dest: B2SyncPath): SyncAction;
+    /**
+     * Creates an action to hide a file in B2 (soft delete).
+     * Kept for compatibility with custom factories that accept a sync-relative string.
+     */
     hide(path: string): SyncAction;
+    /**
+     * Creates an action to hide a B2 file using its full scanned path metadata.
+     * Implementations can use `selectedVersion.fileName` when a raw B2 prefix or normalized sync path
+     * differs from the stored object key.
+     */
+    hideB2Path?(path: B2SyncPath): SyncAction;
     /** Creates an action to permanently delete a remote B2 file version. */
     deleteRemote(path: B2SyncPath): SyncAction;
     /** Creates an action to delete a local file. */
@@ -28,6 +53,10 @@ export interface ActionFactory {
 /**
  * Converts a paired source/dest tuple into zero or more sync actions based on the
  * sync direction, compare mode, and keep policy.
+ * For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local
+ * file hashes and comparable B2 hashes are prepared before actions are generated.
+ * Low-level callers must pass pairs with local `contentSha1` values already
+ * computed and B2 `contentSha1` values containing any comparable metadata fallback.
  *
  * @param pair - The source/dest file pair from {@link zipFolders}.
  * @param direction - The sync direction.

package/dist/sync/policies/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/index.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EAEd,MAAM,aAAa,CAAA;AAGpB,qHAAqH;AACrH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAAA;IACzC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAA;IACxC,iFAAiF;IACjF,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IACtD,4DAA4D;IAC5D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,wEAAwE;IACxE,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC1C,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;IAC5C;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAiB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GACvB,SAAS,CAAC,UAAU,CAAC,CAUvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/index.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EAEd,MAAM,aAAa,CAAA;AAGpB,qHAAqH;AACrH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAA;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,UAAU,CAAA;IAC5E;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9D;;;;OAIG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC7D;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B;;;;OAIG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IACzC,wEAAwE;IACxE,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC1C,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;IAC5C;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAiB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GACvB,SAAS,CAAC,UAAU,CAAC,CAYvB"}

package/dist/sync/policies/index.d.ts

@@ -4,13 +4,38 @@ import { B2SyncPath, CompareMode, KeepMode, LocalSyncPath, SyncDirection } from
 /** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */
 export interface ActionFactory {
     /** Creates an action to upload a local file to B2. */
-    upload(source: LocalSyncPath): SyncAction;
-    /** Creates an action to download a B2 file to the local filesystem. */
-    download(source: B2SyncPath): SyncAction;
-    /** Creates an action to server-side copy a B2 file to a new destination path. */
-    copy(source: B2SyncPath, destPath: string): SyncAction;
-    /** Creates an action to hide a file in B2 (soft delete). */
+    upload(source: LocalSyncPath, dest?: B2SyncPath): SyncAction;
+    /**
+     * Creates an action to download a B2 file to the local filesystem.
+     *
+     * `generateActions` passes `null` when the B2 source has no scanned local
+     * destination, a `LocalSyncPath` when the download replaces an existing
+     * scanned destination file, and leaves the value `undefined` only for
+     * callers that invoke a factory without destination scan context.
+     */
+    download(source: B2SyncPath, scannedDest?: LocalSyncPath | null): SyncAction;
+    /**
+     * Creates an action to server-side copy a B2 file to a sync-relative destination path.
+     * Kept for compatibility with custom factories that accept a sync-relative string.
+     */
+    copy(source: B2SyncPath, destRelativePath: string): SyncAction;
+    /**
+     * Creates an action to server-side copy a B2 file using full destination path metadata.
+     * Implementations can use `dest.selectedVersion.fileName` when a raw B2 prefix or normalized
+     * sync path differs from the stored object key.
+     */
+    copyB2Path?(source: B2SyncPath, dest: B2SyncPath): SyncAction;
+    /**
+     * Creates an action to hide a file in B2 (soft delete).
+     * Kept for compatibility with custom factories that accept a sync-relative string.
+     */
     hide(path: string): SyncAction;
+    /**
+     * Creates an action to hide a B2 file using its full scanned path metadata.
+     * Implementations can use `selectedVersion.fileName` when a raw B2 prefix or normalized sync path
+     * differs from the stored object key.
+     */
+    hideB2Path?(path: B2SyncPath): SyncAction;
     /** Creates an action to permanently delete a remote B2 file version. */
     deleteRemote(path: B2SyncPath): SyncAction;
     /** Creates an action to delete a local file. */
@@ -28,6 +53,10 @@ export interface ActionFactory {
 /**
  * Converts a paired source/dest tuple into zero or more sync actions based on the
  * sync direction, compare mode, and keep policy.
+ * For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local
+ * file hashes and comparable B2 hashes are prepared before actions are generated.
+ * Low-level callers must pass pairs with local `contentSha1` values already
+ * computed and B2 `contentSha1` values containing any comparable metadata fallback.
  *
  * @param pair - The source/dest file pair from {@link zipFolders}.
  * @param direction - The sync direction.

package/dist/sync/policies/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/index.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EAEd,MAAM,aAAa,CAAA;AAGpB,qHAAqH;AACrH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,CAAA;IACzC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAA;IACxC,iFAAiF;IACjF,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IACtD,4DAA4D;IAC5D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,wEAAwE;IACxE,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC1C,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;IAC5C;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAiB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GACvB,SAAS,CAAC,UAAU,CAAC,CAUvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/policies/index.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EAEd,MAAM,aAAa,CAAA;AAGpB,qHAAqH;AACrH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAAA;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,UAAU,CAAA;IAC5E;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9D;;;;OAIG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC7D;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B;;;;OAIG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IACzC,wEAAwE;IACxE,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;IAC1C,gDAAgD;IAChD,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;IAC5C;;;;;;;OAOG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAiB,eAAe,CAC9B,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,MAAM,GACvB,SAAS,CAAC,UAAU,CAAC,CAYvB"}

package/dist/sync/policies/index.js

@@ -1,74 +1,79 @@
 import { SkipAction } from "../actions/index.js";
-import { filesAreDifferent } from "./compare.js";
+import { assertSupportedCompareMode, filesAreDifferent } from "./compare.js";
+//#region src/sync/policies/index.ts
+/**
+* Converts a paired source/dest tuple into zero or more sync actions based on the
+* sync direction, compare mode, and keep policy.
+* For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local
+* file hashes and comparable B2 hashes are prepared before actions are generated.
+* Low-level callers must pass pairs with local `contentSha1` values already
+* computed and B2 `contentSha1` values containing any comparable metadata fallback.
+*
+* @param pair - The source/dest file pair from {@link zipFolders}.
+* @param direction - The sync direction.
+* @param compareMode - How to compare files for differences.
+* @param keepMode - Policy for destination-only files.
+* @param keepDays - Retention period when keepMode is 'keep-days'.
+* @param nowMillis - Current time in milliseconds, used for keep-days calculation.
+* @param factory - Factory to create the concrete action objects.
+* @param compareThreshold - Tolerance for the comparison.
+*/
 function* generateActions(pair, direction, compareMode, keepMode, keepDays, nowMillis, factory, compareThreshold) {
-  const [source, dest] = pair;
-  if (source !== null && dest === null) {
-    yield* actionsForSourceOnly(source, direction, factory);
-  } else if (source === null && dest !== null) {
-    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory);
-  } else if (source !== null && dest !== null) {
-    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory);
-  }
+	assertSupportedCompareMode(compareMode);
+	const [source, dest] = pair;
+	if (source !== null && dest === null) yield* actionsForSourceOnly(source, direction, factory);
+	else if (source === null && dest !== null) yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory);
+	else if (source !== null && dest !== null) yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory);
 }
 function* actionsForSourceOnly(source, direction, factory) {
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.upload(source);
-      break;
-    case "b2-to-local":
-      yield factory.download(source);
-      break;
-    case "b2-to-b2":
-      yield factory.copy(source, source.relativePath);
-      break;
-  }
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.upload(source);
+			break;
+		case "b2-to-local":
+			yield factory.download(source, null);
+			break;
+		case "b2-to-b2": yield factory.copy(source, source.relativePath);
+	}
 }
 function* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory) {
-  if (keepMode === "no-delete") {
-    yield new SkipAction(dest.relativePath, "not in source, keep-mode is no-delete");
-    return;
-  }
-  if (keepMode === "keep-days") {
-    const ageMillis = nowMillis - dest.modTimeMillis;
-    const ageDays = ageMillis / (24 * 60 * 60 * 1e3);
-    if (ageDays < keepDays) {
-      yield new SkipAction(
-        dest.relativePath,
-        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`
-      );
-      return;
-    }
-  }
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.removeOrphan(dest);
-      break;
-    case "b2-to-local":
-      yield factory.deleteLocal(dest);
-      break;
-    case "b2-to-b2":
-      yield factory.removeOrphan(dest);
-      break;
-  }
+	if (keepMode === "no-delete") {
+		yield new SkipAction(dest.relativePath, "not in source, keep-mode is no-delete");
+		return;
+	}
+	if (keepMode === "keep-days") {
+		const ageDays = (nowMillis - dest.modTimeMillis) / 864e5;
+		if (ageDays < keepDays) {
+			yield new SkipAction(dest.relativePath, `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`);
+			return;
+		}
+	}
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.removeOrphan(dest);
+			break;
+		case "b2-to-local":
+			yield factory.deleteLocal(dest);
+			break;
+		case "b2-to-b2": yield factory.removeOrphan(dest);
+	}
 }
 function* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory) {
-  if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {
-    yield new SkipAction(source.relativePath, "files are the same");
-    return;
-  }
-  switch (direction) {
-    case "local-to-b2":
-      yield factory.upload(source);
-      break;
-    case "b2-to-local":
-      yield factory.download(source);
-      break;
-    case "b2-to-b2":
-      yield factory.copy(source, dest.relativePath);
-      break;
-  }
+	if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {
+		yield new SkipAction(source.relativePath, "files are the same");
+		return;
+	}
+	switch (direction) {
+		case "local-to-b2":
+			yield factory.upload(source, dest);
+			break;
+		case "b2-to-local":
+			yield factory.download(source, dest);
+			break;
+		case "b2-to-b2": yield factory.copyB2Path?.(source, dest) ?? factory.copy(source, dest.relativePath);
+	}
 }
-export {
-  generateActions
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { generateActions };
+
+//# sourceMappingURL=index.js.map

package/dist/sync/policies/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/sync/policies/index.ts"],"sourcesContent":["import type { SyncAction } from '../actions/index.ts'\nimport { SkipAction } from '../actions/index.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  KeepMode,\n  LocalSyncPath,\n  SyncDirection,\n  SyncPath,\n} from '../types.ts'\nimport { filesAreDifferent } from './compare.ts'\n\n/** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */\nexport interface ActionFactory {\n  /** Creates an action to upload a local file to B2. */\n  upload(source: LocalSyncPath): SyncAction\n  /** Creates an action to download a B2 file to the local filesystem. */\n  download(source: B2SyncPath): SyncAction\n  /** Creates an action to server-side copy a B2 file to a new destination path. */\n  copy(source: B2SyncPath, destPath: string): SyncAction\n  /** Creates an action to hide a file in B2 (soft delete). */\n  hide(path: string): SyncAction\n  /** Creates an action to permanently delete a remote B2 file version. */\n  deleteRemote(path: B2SyncPath): SyncAction\n  /** Creates an action to delete a local file. */\n  deleteLocal(path: LocalSyncPath): SyncAction\n  /**\n   * Creates the right \"remove this orphan from B2\" action for the bucket's\n   * configuration: a hide on a file-lock-enabled bucket (where direct\n   * delete may be blocked or stack hide markers), a plain\n   * delete-file-version on a vanilla bucket. Used by `actionsForDestOnly`\n   * to avoid yielding both a hide AND a delete when only one of them is\n   * the correct semantic for the destination bucket.\n   */\n  removeOrphan(dest: B2SyncPath): SyncAction\n}\n\n/**\n * Converts a paired source/dest tuple into zero or more sync actions based on the\n * sync direction, compare mode, and keep policy.\n *\n * @param pair - The source/dest file pair from {@link zipFolders}.\n * @param direction - The sync direction.\n * @param compareMode - How to compare files for differences.\n * @param keepMode - Policy for destination-only files.\n * @param keepDays - Retention period when keepMode is 'keep-days'.\n * @param nowMillis - Current time in milliseconds, used for keep-days calculation.\n * @param factory - Factory to create the concrete action objects.\n * @param compareThreshold - Tolerance for the comparison.\n */\nexport function* generateActions(\n  pair: SyncPair,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n  compareThreshold: number,\n): Generator<SyncAction> {\n  const [source, dest] = pair\n\n  if (source !== null && dest === null) {\n    yield* actionsForSourceOnly(source, direction, factory)\n  } else if (source === null && dest !== null) {\n    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory)\n  } else if (source !== null && dest !== null) {\n    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory)\n  }\n}\n\nfunction* actionsForSourceOnly(\n  source: SyncPath,\n  direction: SyncDirection,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, source.relativePath)\n      break\n  }\n}\n\nfunction* actionsForDestOnly(\n  dest: SyncPath,\n  direction: SyncDirection,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (keepMode === 'no-delete') {\n    yield new SkipAction(dest.relativePath, 'not in source, keep-mode is no-delete')\n    return\n  }\n\n  if (keepMode === 'keep-days') {\n    const ageMillis = nowMillis - dest.modTimeMillis\n    const ageDays = ageMillis / (24 * 60 * 60 * 1000)\n    if (ageDays < keepDays) {\n      yield new SkipAction(\n        dest.relativePath,\n        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`,\n      )\n      return\n    }\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      // Single action — `removeOrphan` picks hide vs delete based on\n      // the destination bucket's `fileLockEnabled` state. The previous\n      // \"yield both\" behaviour stacked hide markers on vanilla buckets\n      // even though the delete that followed made them redundant.\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.deleteLocal(dest as LocalSyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n  }\n}\n\nfunction* actionsForBoth(\n  source: SyncPath,\n  dest: SyncPath,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  compareThreshold: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {\n    yield new SkipAction(source.relativePath, 'files are the same')\n    return\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, dest.relativePath)\n      break\n  }\n}\n"],"names":[],"mappings":";;AAmDO,UAAU,gBACf,MACA,WACA,aACA,UACA,UACA,WACA,SACA,kBACuB;AACvB,QAAM,CAAC,QAAQ,IAAI,IAAI;AAEvB,MAAI,WAAW,QAAQ,SAAS,MAAM;AACpC,WAAO,qBAAqB,QAAQ,WAAW,OAAO;AAAA,EACxD,WAAW,WAAW,QAAQ,SAAS,MAAM;AAC3C,WAAO,mBAAmB,MAAM,WAAW,UAAU,UAAU,WAAW,OAAO;AAAA,EACnF,WAAW,WAAW,QAAQ,SAAS,MAAM;AAC3C,WAAO,eAAe,QAAQ,MAAM,WAAW,aAAa,kBAAkB,OAAO;AAAA,EACvF;AACF;AAEA,UAAU,qBACR,QACA,WACA,SACuB;AACvB,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,YAAM,QAAQ,OAAO,MAAuB;AAC5C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,SAAS,MAAoB;AAC3C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;AAC5D;AAAA,EAAA;AAEN;AAEA,UAAU,mBACR,MACA,WACA,UACA,UACA,WACA,SACuB;AACvB,MAAI,aAAa,aAAa;AAC5B,UAAM,IAAI,WAAW,KAAK,cAAc,uCAAuC;AAC/E;AAAA,EACF;AAEA,MAAI,aAAa,aAAa;AAC5B,UAAM,YAAY,YAAY,KAAK;AACnC,UAAM,UAAU,aAAa,KAAK,KAAK,KAAK;AAC5C,QAAI,UAAU,UAAU;AACtB,YAAM,IAAI;AAAA,QACR,KAAK;AAAA,QACL,8BAA8B,KAAK,KAAK,WAAW,OAAO,CAAC;AAAA,MAAA;AAE7D;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,WAAA;AAAA,IACN,KAAK;AAKH,YAAM,QAAQ,aAAa,IAAkB;AAC7C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,YAAY,IAAqB;AAC/C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,aAAa,IAAkB;AAC7C;AAAA,EAAA;AAEN;AAEA,UAAU,eACR,QACA,MACA,WACA,aACA,kBACA,SACuB;AACvB,MAAI,CAAC,kBAAkB,QAAQ,MAAM,aAAa,gBAAgB,GAAG;AACnE,UAAM,IAAI,WAAW,OAAO,cAAc,oBAAoB;AAC9D;AAAA,EACF;AAEA,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,YAAM,QAAQ,OAAO,MAAuB;AAC5C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,SAAS,MAAoB;AAC3C;AAAA,IACF,KAAK;AACH,YAAM,QAAQ,KAAK,QAAsB,KAAK,YAAY;AAC1D;AAAA,EAAA;AAEN;"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/sync/policies/index.ts"],"sourcesContent":["import type { SyncAction } from '../actions/index.ts'\nimport { SkipAction } from '../actions/index.ts'\nimport type { SyncPair } from '../pairing.ts'\nimport type {\n  B2SyncPath,\n  CompareMode,\n  KeepMode,\n  LocalSyncPath,\n  SyncDirection,\n  SyncPath,\n} from '../types.ts'\nimport { assertSupportedCompareMode, filesAreDifferent } from './compare.ts'\n\n/** Factory for creating concrete sync actions. Used by {@link generateActions} to decouple policy from execution. */\nexport interface ActionFactory {\n  /** Creates an action to upload a local file to B2. */\n  upload(source: LocalSyncPath, dest?: B2SyncPath): SyncAction\n  /**\n   * Creates an action to download a B2 file to the local filesystem.\n   *\n   * `generateActions` passes `null` when the B2 source has no scanned local\n   * destination, a `LocalSyncPath` when the download replaces an existing\n   * scanned destination file, and leaves the value `undefined` only for\n   * callers that invoke a factory without destination scan context.\n   */\n  download(source: B2SyncPath, scannedDest?: LocalSyncPath | null): SyncAction\n  /**\n   * Creates an action to server-side copy a B2 file to a sync-relative destination path.\n   * Kept for compatibility with custom factories that accept a sync-relative string.\n   */\n  copy(source: B2SyncPath, destRelativePath: string): SyncAction\n  /**\n   * Creates an action to server-side copy a B2 file using full destination path metadata.\n   * Implementations can use `dest.selectedVersion.fileName` when a raw B2 prefix or normalized\n   * sync path differs from the stored object key.\n   */\n  copyB2Path?(source: B2SyncPath, dest: B2SyncPath): SyncAction\n  /**\n   * Creates an action to hide a file in B2 (soft delete).\n   * Kept for compatibility with custom factories that accept a sync-relative string.\n   */\n  hide(path: string): SyncAction\n  /**\n   * Creates an action to hide a B2 file using its full scanned path metadata.\n   * Implementations can use `selectedVersion.fileName` when a raw B2 prefix or normalized sync path\n   * differs from the stored object key.\n   */\n  hideB2Path?(path: B2SyncPath): SyncAction\n  /** Creates an action to permanently delete a remote B2 file version. */\n  deleteRemote(path: B2SyncPath): SyncAction\n  /** Creates an action to delete a local file. */\n  deleteLocal(path: LocalSyncPath): SyncAction\n  /**\n   * Creates the right \"remove this orphan from B2\" action for the bucket's\n   * configuration: a hide on a file-lock-enabled bucket (where direct\n   * delete may be blocked or stack hide markers), a plain\n   * delete-file-version on a vanilla bucket. Used by `actionsForDestOnly`\n   * to avoid yielding both a hide AND a delete when only one of them is\n   * the correct semantic for the destination bucket.\n   */\n  removeOrphan(dest: B2SyncPath): SyncAction\n}\n\n/**\n * Converts a paired source/dest tuple into zero or more sync actions based on the\n * sync direction, compare mode, and keep policy.\n * For `compareMode: 'sha1'`, prefer the high-level `synchronize()` API so local\n * file hashes and comparable B2 hashes are prepared before actions are generated.\n * Low-level callers must pass pairs with local `contentSha1` values already\n * computed and B2 `contentSha1` values containing any comparable metadata fallback.\n *\n * @param pair - The source/dest file pair from {@link zipFolders}.\n * @param direction - The sync direction.\n * @param compareMode - How to compare files for differences.\n * @param keepMode - Policy for destination-only files.\n * @param keepDays - Retention period when keepMode is 'keep-days'.\n * @param nowMillis - Current time in milliseconds, used for keep-days calculation.\n * @param factory - Factory to create the concrete action objects.\n * @param compareThreshold - Tolerance for the comparison.\n */\nexport function* generateActions(\n  pair: SyncPair,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n  compareThreshold: number,\n): Generator<SyncAction> {\n  assertSupportedCompareMode(compareMode)\n\n  const [source, dest] = pair\n\n  if (source !== null && dest === null) {\n    yield* actionsForSourceOnly(source, direction, factory)\n  } else if (source === null && dest !== null) {\n    yield* actionsForDestOnly(dest, direction, keepMode, keepDays, nowMillis, factory)\n  } else if (source !== null && dest !== null) {\n    yield* actionsForBoth(source, dest, direction, compareMode, compareThreshold, factory)\n  }\n}\n\nfunction* actionsForSourceOnly(\n  source: SyncPath,\n  direction: SyncDirection,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath, null)\n      break\n    case 'b2-to-b2':\n      yield factory.copy(source as B2SyncPath, source.relativePath)\n      break\n  }\n}\n\nfunction* actionsForDestOnly(\n  dest: SyncPath,\n  direction: SyncDirection,\n  keepMode: KeepMode,\n  keepDays: number,\n  nowMillis: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (keepMode === 'no-delete') {\n    yield new SkipAction(dest.relativePath, 'not in source, keep-mode is no-delete')\n    return\n  }\n\n  if (keepMode === 'keep-days') {\n    const ageMillis = nowMillis - dest.modTimeMillis\n    const ageDays = ageMillis / (24 * 60 * 60 * 1000)\n    if (ageDays < keepDays) {\n      yield new SkipAction(\n        dest.relativePath,\n        `not in source, keeping for ${Math.ceil(keepDays - ageDays)} more days`,\n      )\n      return\n    }\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      // Single action — `removeOrphan` picks hide vs delete based on\n      // the destination bucket's `fileLockEnabled` state. The previous\n      // \"yield both\" behaviour stacked hide markers on vanilla buckets\n      // even though the delete that followed made them redundant.\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.deleteLocal(dest as LocalSyncPath)\n      break\n    case 'b2-to-b2':\n      yield factory.removeOrphan(dest as B2SyncPath)\n      break\n  }\n}\n\nfunction* actionsForBoth(\n  source: SyncPath,\n  dest: SyncPath,\n  direction: SyncDirection,\n  compareMode: CompareMode,\n  compareThreshold: number,\n  factory: ActionFactory,\n): Generator<SyncAction> {\n  if (!filesAreDifferent(source, dest, compareMode, compareThreshold)) {\n    yield new SkipAction(source.relativePath, 'files are the same')\n    return\n  }\n\n  switch (direction) {\n    case 'local-to-b2':\n      yield factory.upload(source as LocalSyncPath, dest as B2SyncPath)\n      break\n    case 'b2-to-local':\n      yield factory.download(source as B2SyncPath, dest as LocalSyncPath)\n      break\n    case 'b2-to-b2': {\n      const action =\n        factory.copyB2Path?.(source as B2SyncPath, dest as B2SyncPath) ??\n        factory.copy(source as B2SyncPath, dest.relativePath)\n      yield action\n      break\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgFA,UAAiB,gBACf,MACA,WACA,aACA,UACA,UACA,WACA,SACA,kBACuB;CACvB,2BAA2B,WAAW;CAEtC,MAAM,CAAC,QAAQ,QAAQ;CAEvB,IAAI,WAAW,QAAQ,SAAS,MAC9B,OAAO,qBAAqB,QAAQ,WAAW,OAAO;MACjD,IAAI,WAAW,QAAQ,SAAS,MACrC,OAAO,mBAAmB,MAAM,WAAW,UAAU,UAAU,WAAW,OAAO;MAC5E,IAAI,WAAW,QAAQ,SAAS,MACrC,OAAO,eAAe,QAAQ,MAAM,WAAW,aAAa,kBAAkB,OAAO;AAEzF;AAEA,UAAU,qBACR,QACA,WACA,SACuB;CACvB,QAAQ,WAAR;EACE,KAAK;GACH,MAAM,QAAQ,OAAO,MAAuB;GAC5C;EACF,KAAK;GACH,MAAM,QAAQ,SAAS,QAAsB,IAAI;GACjD;EACF,KAAK,YACH,MAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;CAEhE;AACF;AAEA,UAAU,mBACR,MACA,WACA,UACA,UACA,WACA,SACuB;CACvB,IAAI,aAAa,aAAa;EAC5B,MAAM,IAAI,WAAW,KAAK,cAAc,uCAAuC;EAC/E;CACF;CAEA,IAAI,aAAa,aAAa;EAE5B,MAAM,WADY,YAAY,KAAK,iBACN;EAC7B,IAAI,UAAU,UAAU;GACtB,MAAM,IAAI,WACR,KAAK,cACL,8BAA8B,KAAK,KAAK,WAAW,OAAO,EAAE,WAC9D;GACA;EACF;CACF;CAEA,QAAQ,WAAR;EACE,KAAK;GAKH,MAAM,QAAQ,aAAa,IAAkB;GAC7C;EACF,KAAK;GACH,MAAM,QAAQ,YAAY,IAAqB;GAC/C;EACF,KAAK,YACH,MAAM,QAAQ,aAAa,IAAkB;CAEjD;AACF;AAEA,UAAU,eACR,QACA,MACA,WACA,aACA,kBACA,SACuB;CACvB,IAAI,CAAC,kBAAkB,QAAQ,MAAM,aAAa,gBAAgB,GAAG;EACnE,MAAM,IAAI,WAAW,OAAO,cAAc,oBAAoB;EAC9D;CACF;CAEA,QAAQ,WAAR;EACE,KAAK;GACH,MAAM,QAAQ,OAAO,QAAyB,IAAkB;GAChE;EACF,KAAK;GACH,MAAM,QAAQ,SAAS,QAAsB,IAAqB;GAClE;EACF,KAAK,YAIH,MAFE,QAAQ,aAAa,QAAsB,IAAkB,KAC7D,QAAQ,KAAK,QAAsB,KAAK,YAAY;CAI1D;AACF"}

package/dist/sync/prefix.cjs

@@ -0,0 +1,96 @@
+const require_download_staging = require("./download-staging.cjs");
+//#region src/sync/prefix.ts
+/**
+* Treats the supplied string as a raw B2 key prefix without adding a folder boundary.
+*
+* B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real
+* key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should
+* pass `/` explicitly.
+*
+* @param prefix - User-supplied raw B2 key prefix.
+*
+* @returns Raw B2 key prefix.
+*/
+function asRawB2KeyPrefix(prefix) {
+	return prefix;
+}
+/**
+* Normalizes a B2 object name into a safe folder-relative sync path.
+*
+* Object names are converted to forward-slash sync paths for local compatibility. Callers that scan
+* B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.
+*
+* @param path - B2 object name or prefix-stripped suffix returned by a listing.
+* @param options - Optional normalization behavior for legacy slashless raw prefixes.
+*
+* @returns Folder-relative sync path.
+*
+* @throws When the object name cannot be represented as a safe relative path.
+*/
+function normalizeB2RelativePath(path, options = {}) {
+	const slashPath = path.split("\\").join("/");
+	const relativePath = options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath;
+	const segments = relativePath.split("/");
+	if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) throw new Error("Unsafe B2 file name cannot be used as a sync relative path");
+	return relativePath;
+}
+/**
+* Converts a B2 object key under a configured raw prefix into a sync relative path.
+*
+* @param prefix - Raw B2 key prefix used for the scan or mutation guard.
+* @param fileName - Full B2 object key.
+*
+* @returns The normalized sync relative path for the key suffix.
+*/
+function b2KeyToRelativePathUnderPrefix(prefix, fileName) {
+	const rawPrefix = asRawB2KeyPrefix(prefix);
+	return normalizeB2RelativePath(rawPrefix === "" ? fileName : fileName.slice(rawPrefix.length), { stripLeadingSlashes: rawPrefix !== "" && !rawPrefix.endsWith("/") });
+}
+/**
+* Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.
+* B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns True when any segment is Windows-dangerous or ambiguous.
+*/
+function localFilesystemSyncPathIsUnsafe(relativePath) {
+	const segments = relativePath.split("/");
+	return require_download_staging.isDownloadStagingDirectorySegment(segments[0]) || segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment));
+}
+/**
+* Produces an approximate Windows/macOS-style canonical key for local collision detection.
+*
+* @param relativePath - Folder-relative sync path.
+*
+* @returns A canonicalized path key for detecting case/Unicode collisions before local writes.
+*/
+function localFilesystemCanonicalSyncPath(relativePath) {
+	return relativePath.split("/").map((segment) => segment.normalize("NFC").toLocaleLowerCase("en-US")).join("/");
+}
+function segmentIsUnsafe(segment) {
+	return segment === "" || segment === "." || segment === ".." || containsControlCharacter(segment);
+}
+function segmentIsLocalFilesystemUnsafe(segment) {
+	if (segment.includes(":") || segment.endsWith(".") || segment.endsWith(" ")) return true;
+	const basename = segment.split(".")[0]?.toUpperCase();
+	return basename !== void 0 && /^(CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename);
+}
+function containsControlCharacter(segment) {
+	for (let index = 0; index < segment.length; index++) {
+		const code = segment.charCodeAt(index);
+		if (code >= 0 && code <= 31) return true;
+	}
+	return false;
+}
+function stripSingleLeadingSlash(path) {
+	return path.startsWith("/") ? path.slice(1) : path;
+}
+//#endregion
+exports.asRawB2KeyPrefix = asRawB2KeyPrefix;
+exports.b2KeyToRelativePathUnderPrefix = b2KeyToRelativePathUnderPrefix;
+exports.localFilesystemCanonicalSyncPath = localFilesystemCanonicalSyncPath;
+exports.localFilesystemSyncPathIsUnsafe = localFilesystemSyncPathIsUnsafe;
+exports.normalizeB2RelativePath = normalizeB2RelativePath;
+
+//# sourceMappingURL=prefix.cjs.map

package/dist/sync/prefix.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix.cjs","names":[],"sources":["../../src/sync/prefix.ts"],"sourcesContent":["import { isDownloadStagingDirectorySegment } from './download-staging.ts'\n\n/**\n * Treats the supplied string as a raw B2 key prefix without adding a folder boundary.\n *\n * B2 keys are byte-oriented names, not local filesystem paths. A backslash in a prefix is a real\n * key character and must not be rewritten to `/`; callers that want slash-delimited prefixes should\n * pass `/` explicitly.\n *\n * @param prefix - User-supplied raw B2 key prefix.\n *\n * @returns Raw B2 key prefix.\n */\nexport function asRawB2KeyPrefix(prefix: string): string {\n  return prefix\n}\n\n/**\n * Normalizes a B2 object name into a safe folder-relative sync path.\n *\n * Object names are converted to forward-slash sync paths for local compatibility. Callers that scan\n * B2 must detect normalized-path collisions between distinct raw B2 keys before yielding entries.\n *\n * @param path - B2 object name or prefix-stripped suffix returned by a listing.\n * @param options - Optional normalization behavior for legacy slashless raw prefixes.\n *\n * @returns Folder-relative sync path.\n *\n * @throws When the object name cannot be represented as a safe relative path.\n */\nexport function normalizeB2RelativePath(\n  path: string,\n  options: { readonly stripLeadingSlashes?: boolean } = {},\n): string {\n  const slashPath = path.split('\\\\').join('/')\n  const relativePath =\n    options.stripLeadingSlashes === true ? stripSingleLeadingSlash(slashPath) : slashPath\n  const segments = relativePath.split('/')\n  if (/^[A-Za-z]:/.test(relativePath) || segments.some((segment) => segmentIsUnsafe(segment))) {\n    throw new Error('Unsafe B2 file name cannot be used as a sync relative path')\n  }\n  return relativePath\n}\n\n/**\n * Converts a B2 object key under a configured raw prefix into a sync relative path.\n *\n * @param prefix - Raw B2 key prefix used for the scan or mutation guard.\n * @param fileName - Full B2 object key.\n *\n * @returns The normalized sync relative path for the key suffix.\n */\nexport function b2KeyToRelativePathUnderPrefix(prefix: string, fileName: string): string {\n  const rawPrefix = asRawB2KeyPrefix(prefix)\n  const suffix = rawPrefix === '' ? fileName : fileName.slice(rawPrefix.length)\n  return normalizeB2RelativePath(suffix, {\n    stripLeadingSlashes: rawPrefix !== '' && !rawPrefix.endsWith('/'),\n  })\n}\n\n/**\n * Returns whether a sync path is unsafe to materialize on Windows-compatible local filesystems.\n * B2-to-B2 syncs can preserve these object names, but B2-to-local syncs skip them before writing.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns True when any segment is Windows-dangerous or ambiguous.\n */\nexport function localFilesystemSyncPathIsUnsafe(relativePath: string): boolean {\n  const segments = relativePath.split('/')\n  return (\n    isDownloadStagingDirectorySegment(segments[0]) ||\n    segments.some((segment) => segmentIsLocalFilesystemUnsafe(segment))\n  )\n}\n\n/**\n * Produces an approximate Windows/macOS-style canonical key for local collision detection.\n *\n * @param relativePath - Folder-relative sync path.\n *\n * @returns A canonicalized path key for detecting case/Unicode collisions before local writes.\n */\nexport function localFilesystemCanonicalSyncPath(relativePath: string): string {\n  return relativePath\n    .split('/')\n    .map((segment) => segment.normalize('NFC').toLocaleLowerCase('en-US'))\n    .join('/')\n}\n\nfunction segmentIsUnsafe(segment: string): boolean {\n  return segment === '' || segment === '.' || segment === '..' || containsControlCharacter(segment)\n}\n\nfunction segmentIsLocalFilesystemUnsafe(segment: string): boolean {\n  if (segment.includes(':') || segment.endsWith('.') || segment.endsWith(' ')) return true\n  const basename = segment.split('.')[0]?.toUpperCase()\n  return (\n    basename !== undefined &&\n    /^(CON|PRN|AUX|NUL|CONIN\\$|CONOUT\\$|COM[0-9¹²³]|LPT[0-9¹²³])$/u.test(basename)\n  )\n}\n\nfunction containsControlCharacter(segment: string): boolean {\n  for (let index = 0; index < segment.length; index++) {\n    const code = segment.charCodeAt(index)\n    if (code >= 0 && code <= 31) return true\n  }\n  return false\n}\n\nfunction stripSingleLeadingSlash(path: string): string {\n  return path.startsWith('/') ? path.slice(1) : path\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,SAAgB,iBAAiB,QAAwB;CACvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,wBACd,MACA,UAAsD,CAAC,GAC/C;CACR,MAAM,YAAY,KAAK,MAAM,IAAI,CAAC,CAAC,KAAK,GAAG;CAC3C,MAAM,eACJ,QAAQ,wBAAwB,OAAO,wBAAwB,SAAS,IAAI;CAC9E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,IAAI,aAAa,KAAK,YAAY,KAAK,SAAS,MAAM,YAAY,gBAAgB,OAAO,CAAC,GACxF,MAAM,IAAI,MAAM,4DAA4D;CAE9E,OAAO;AACT;;;;;;;;;AAUA,SAAgB,+BAA+B,QAAgB,UAA0B;CACvF,MAAM,YAAY,iBAAiB,MAAM;CAEzC,OAAO,wBADQ,cAAc,KAAK,WAAW,SAAS,MAAM,UAAU,MAAM,GACrC,EACrC,qBAAqB,cAAc,MAAM,CAAC,UAAU,SAAS,GAAG,EAClE,CAAC;AACH;;;;;;;;;AAUA,SAAgB,gCAAgC,cAA+B;CAC7E,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OACE,yBAAA,kCAAkC,SAAS,EAAE,KAC7C,SAAS,MAAM,YAAY,+BAA+B,OAAO,CAAC;AAEtE;;;;;;;;AASA,SAAgB,iCAAiC,cAA8B;CAC7E,OAAO,aACJ,MAAM,GAAG,CAAC,CACV,KAAK,YAAY,QAAQ,UAAU,KAAK,CAAC,CAAC,kBAAkB,OAAO,CAAC,CAAC,CACrE,KAAK,GAAG;AACb;AAEA,SAAS,gBAAgB,SAA0B;CACjD,OAAO,YAAY,MAAM,YAAY,OAAO,YAAY,QAAQ,yBAAyB,OAAO;AAClG;AAEA,SAAS,+BAA+B,SAA0B;CAChE,IAAI,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,KAAK,QAAQ,SAAS,GAAG,GAAG,OAAO;CACpF,MAAM,WAAW,QAAQ,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,YAAY;CACpD,OACE,aAAa,KAAA,KACb,gEAAgE,KAAK,QAAQ;AAEjF;AAEA,SAAS,yBAAyB,SAA0B;CAC1D,KAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS;EACnD,MAAM,OAAO,QAAQ,WAAW,KAAK;EACrC,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO;CACtC;CACA,OAAO;AACT;AAEA,SAAS,wBAAwB,MAAsB;CACrD,OAAO,KAAK,WAAW,GAAG,IAAI,KAAK,MAAM,CAAC,IAAI;AAChD"}