@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

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

@@ -1 +1 @@
-{"version":3,"file":"compare.js","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.js","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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"}

package/dist/sync/policies/index.cjs

@@ -1,74 +1,85 @@
-"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);
+			break;
+	}
 }
 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) / (1440 * 60 * 1e3);
+		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);
+			break;
+	}
 }
 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);
+			break;
+	}
 }
+//#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;GACH,MAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;GAC5D;CACJ;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,kBACN,OAAU,KAAK;EAC5C,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;GACH,MAAM,QAAQ,aAAa,IAAkB;GAC7C;CACJ;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;GAIH,MAFE,QAAQ,aAAa,QAAsB,IAAkB,KAC7D,QAAQ,KAAK,QAAsB,KAAK,YAAY;GAEtD;CAEJ;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,85 @@
 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);
+			break;
+	}
 }
 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) / (1440 * 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;
+	}
 }
 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);
+			break;
+	}
 }
-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;GACH,MAAM,QAAQ,KAAK,QAAsB,OAAO,YAAY;GAC5D;CACJ;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,kBACN,OAAU,KAAK;EAC5C,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;GACH,MAAM,QAAQ,aAAa,IAAkB;GAC7C;CACJ;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;GAIH,MAFE,QAAQ,aAAa,QAAsB,IAAkB,KAC7D,QAAQ,KAAK,QAAsB,KAAK,YAAY;GAEtD;CAEJ;AACF"}