@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/sync/synchronizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"synchronizer.js","sources":["../../src/sync/synchronizer.ts"],"sourcesContent":["import type { Bucket } from '../bucket.ts'\nimport { BufferSource } from '../streams/source.ts'\nimport { fileId as fileIdOf } from '../types/ids.ts'\nimport { Semaphore } from '../upload/concurrency.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { toError } from '../util/to-error.ts'\nimport type { SyncAction } from './actions/index.ts'\nimport {\n  CopyAction,\n  DeleteLocalAction,\n  DeleteRemoteAction,\n  DownloadAction,\n  HideAction,\n  UploadAction,\n} from './actions/index.ts'\nimport { zipFolders } from './pairing.ts'\nimport type { ActionFactory } from './policies/index.ts'\nimport { generateActions } from './policies/index.ts'\nimport type {\n  B2SyncPath,\n  LocalSyncPath,\n  SyncDirection,\n  SyncEvent,\n  SyncFolder,\n  SyncOptions,\n} from './types.ts'\n\n/** Base configuration for a sync operation. */\nexport interface SynchronizerConfig {\n  /** The folder to read files from. */\n  readonly source: SyncFolder\n  /** The folder to write files to. */\n  readonly dest: SyncFolder\n  /** Options controlling comparison, deletion policy, and concurrency. */\n  readonly options: SyncOptions\n}\n\n/** A sync folder constrained to the local filesystem. */\nexport interface LocalSyncFolder extends SyncFolder {\n  /** Discriminant identifying a local folder. */\n  readonly type: 'local'\n  /** Absolute filesystem path to the local root directory. */\n  readonly root: string\n}\n\n/** A sync folder constrained to a B2 bucket prefix. */\nexport interface B2SyncFolder extends SyncFolder {\n  /** Discriminant identifying a B2 folder. */\n  readonly type: 'b2'\n}\n\n/** Configuration for a local-to-B2 sync (upload direction). */\nexport interface SynchronizerUpConfig extends SynchronizerConfig {\n  /** Local source folder. */\n  readonly source: LocalSyncFolder\n  /** B2 destination folder. */\n  readonly dest: B2SyncFolder\n  /** The target B2 bucket. */\n  readonly bucket: Bucket\n  /** Key prefix for uploaded files in the bucket. */\n  readonly prefix: string\n}\n\n/** Configuration for a B2-to-local sync (download direction). */\nexport interface SynchronizerDownConfig extends SynchronizerConfig {\n  /** B2 source folder. */\n  readonly source: B2SyncFolder\n  /** Local destination folder. */\n  readonly dest: LocalSyncFolder\n  /** The source B2 bucket. */\n  readonly bucket: Bucket\n}\n\n/**\n * Infers the sync direction from the source and destination folder types.\n * @param source - The folder to read files from.\n * @param dest - The folder to write files to.\n *\n * @returns The resolved sync direction based on folder types.\n *\n * @throws When the source and destination folder types form an unsupported combination.\n */\nfunction resolveDirection(source: SyncFolder, dest: SyncFolder): SyncDirection {\n  if (source.type === 'local' && dest.type === 'b2') return 'local-to-b2'\n  if (source.type === 'b2' && dest.type === 'local') return 'b2-to-local'\n  if (source.type === 'b2' && dest.type === 'b2') return 'b2-to-b2'\n  throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`)\n}\n\n/**\n * Runs a full sync operation: scans both folders, pairs files, generates actions,\n * and executes them with bounded concurrency. Yields {@link SyncEvent} entries for\n * each comparison and action result.\n *\n * @param config - The synchronizer configuration (source, dest, options, and optional bucket).\n */\nexport async function* synchronize(config: SynchronizerConfig): AsyncGenerator<SyncEvent> {\n  const { source, dest, options } = config\n  const direction = resolveDirection(source, dest)\n  const dryRun = options.dryRun ?? false\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const keepDays = options.keepDays ?? 0\n  const compareThreshold = options.compareThreshold ?? 0\n  const nowMillis = Date.now()\n\n  const factory = createActionFactory(config)\n\n  const actions: SyncAction[] = []\n\n  for await (const pair of zipFolders(source, dest)) {\n    if (options.signal?.aborted) return\n\n    for (const action of generateActions(\n      pair,\n      direction,\n      options.compareMode,\n      options.keepMode,\n      keepDays,\n      nowMillis,\n      factory,\n      compareThreshold,\n    )) {\n      actions.push(action)\n    }\n\n    yield { type: 'compare', path: (pair[0] ?? pair[1])?.relativePath ?? '', size: 0 }\n  }\n\n  const sem = new Semaphore(concurrency)\n  const results: SyncEvent[] = []\n  const errors: Error[] = []\n\n  const promises = actions.map(async (action) => {\n    await sem.acquire()\n    try {\n      if (options.signal?.aborted) return\n      const event = await action.execute(dryRun)\n      results.push(event)\n    } catch (err) {\n      const errorValue = toError(err)\n      errors.push(errorValue)\n      results.push({\n        type: 'error',\n        path: action.relativePath,\n        size: 0,\n        message: errorValue.message,\n      })\n    } finally {\n      sem.release()\n    }\n  })\n\n  await Promise.all(promises)\n\n  for (const event of results) {\n    yield event\n  }\n\n  if (errors.length > 0) {\n    yield {\n      type: 'error',\n      path: '',\n      size: 0,\n      message: `${errors.length} action(s) failed`,\n    }\n  }\n}\n\n/**\n * Narrowing assertion that a `Bucket` is present for an action that requires\n * it. Throws with a consistent, context-tagged message when the configured\n * direction did not supply one (e.g. `b2-to-local` direction asking for an\n * upload action).\n *\n * Uses TypeScript's `asserts` signature so call-site flow narrows\n * `bucket` from `Bucket | undefined` to `Bucket` after the check, without\n * requiring a separate `if (!bucket) throw ...` line per action factory.\n *\n * @param bucket - The (possibly missing) bucket reference.\n * @param context - Short verb describing the action being constructed\n *   (e.g. `'upload'`, `'download'`). Surfaced in the error message.\n *\n * @throws `Error` when `bucket` is `undefined` or `null`.\n */\nfunction assertBucket(bucket: Bucket | undefined, context: string): asserts bucket is Bucket {\n  if (!bucket) throw new Error(`Bucket required for ${context} actions`)\n}\n\n/**\n * Creates a configured sync engine wired to the bucket and paths in the given config.\n *\n * For sync operations that may need to remove destination-only files (the\n * `keepMode: 'delete'` policy), the factory reads the destination\n * bucket's cached `fileLockConfiguration` once so `removeOrphan` can\n * dispatch to either `hide` (locked buckets) or `deleteFileVersion`\n * (vanilla buckets) without a per-file branch. The cache is whatever\n * `client.listBuckets()` or `client.createBucket()` returned — callers\n * who flipped lock state mid-sync (rare) should refresh before\n * synchronize().\n *\n * @param config - The synchronizer configuration containing source, destination, and options.\n *\n * @returns An action factory bound to the provided configuration.\n */\nfunction createActionFactory(config: SynchronizerConfig): ActionFactory {\n  const upConfig = config as Partial<SynchronizerUpConfig>\n  const downConfig = config as Partial<SynchronizerDownConfig>\n\n  const destBucket = upConfig.bucket ?? downConfig.bucket\n  // Defensive optional chain on `info`: synchronizer tests use Bucket\n  // mocks that don't populate this field. Real `Bucket` instances always\n  // do (constructor parameter).\n  const bucketIsLocked = destBucket?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false\n\n  const factory: ActionFactory = {\n    upload(source: LocalSyncPath): SyncAction {\n      const bucket = upConfig.bucket\n      const prefix = upConfig.prefix ?? ''\n      assertBucket(bucket, 'upload')\n\n      return new UploadAction(\n        source.relativePath,\n        source.absolutePath,\n        source.size,\n        async (absPath, relPath) => {\n          const { readFile } = await import('node:fs/promises')\n          const data = await readFile(absPath)\n          await bucket.upload({\n            fileName: `${prefix}${relPath}`,\n            source: new BufferSource(new Uint8Array(data)),\n          })\n        },\n      )\n    },\n\n    download(source: B2SyncPath): SyncAction {\n      const bucket = downConfig.bucket\n      const root =\n        downConfig.dest?.type === 'local' ? (downConfig.dest as { root: string }).root : ''\n      assertBucket(bucket, 'download')\n\n      return new DownloadAction(source.relativePath, source.size, async (relPath) => {\n        const result = await bucket.download(source.selectedVersion.fileName)\n        const reader = result.body.getReader()\n        let combined: Uint8Array\n        try {\n          const chunks: Uint8Array[] = []\n          while (true) {\n            const { done, value } = await reader.read()\n            if (done) break\n            chunks.push(value)\n          }\n          let total = 0\n          for (const c of chunks) total += c.byteLength\n          combined = new Uint8Array(total)\n          let offset = 0\n          for (const c of chunks) {\n            combined.set(c, offset)\n            offset += c.byteLength\n          }\n        } finally {\n          // Release the body stream's reader lock so a downstream\n          // writeFile failure doesn't strand the response stream half-\n          // open with the upstream HTTP connection still pumping.\n          reader.releaseLock()\n        }\n\n        const { mkdir, writeFile } = await import('node:fs/promises')\n        const { dirname, join } = await import('node:path')\n        const destPath = join(root, relPath)\n        await mkdir(dirname(destPath), { recursive: true })\n        await writeFile(destPath, combined)\n      })\n    },\n\n    copy(source: B2SyncPath, destPath: string): SyncAction {\n      const bucket = upConfig.bucket\n      assertBucket(bucket, 'copy')\n\n      return new CopyAction(source.relativePath, source.size, async () => {\n        await bucket.copyFile({\n          sourceFileId: source.selectedVersion.fileId,\n          fileName: destPath,\n        })\n      })\n    },\n\n    hide(path: string): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'hide')\n\n      return new HideAction(path, async (relPath) => {\n        const prefix = upConfig.prefix ?? ''\n        await bucket.hideFile(`${prefix}${relPath}`)\n      })\n    },\n\n    deleteRemote(path: B2SyncPath): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'delete')\n\n      // Bug fix: `DeleteRemoteAction` invokes the closure with\n      // `relativePath` (the scanner-stripped name relative to the sync\n      // prefix), but B2 stores files under the FULL name including the\n      // prefix. Use the FileVersion's authoritative `fileName` — the\n      // actual B2 key — rather than reconstructing it via prefix\n      // concat. Without this, syncs with a non-empty destination\n      // prefix (e.g. `'site/'`) failed orphan deletion with\n      // `file_not_present`.\n      const b2FileName = path.selectedVersion.fileName\n      return new DeleteRemoteAction(\n        path.relativePath,\n        path.selectedVersion.fileId as string,\n        async (fileId) => {\n          await bucket.deleteFileVersion(b2FileName, fileIdOf(fileId))\n        },\n      )\n    },\n\n    deleteLocal(path: LocalSyncPath): SyncAction {\n      return new DeleteLocalAction(path.relativePath, path.absolutePath, async (absPath) => {\n        const { unlink } = await import('node:fs/promises')\n        await unlink(absPath)\n      })\n    },\n\n    removeOrphan(dest: B2SyncPath): SyncAction {\n      // Locked buckets: `b2_delete_file_version` is blocked or stacks\n      // hide markers under retention; a hide is the safe choice.\n      // Vanilla buckets: plain delete is the right move — hide markers\n      // would just litter the version history.\n      return bucketIsLocked ? factory.hide(dest.relativePath) : factory.deleteRemote(dest)\n    },\n  }\n\n  return factory\n}\n"],"names":["fileId","fileIdOf"],"mappings":"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"}
+{"version":3,"file":"synchronizer.js","names":[],"sources":["../../src/sync/synchronizer.ts"],"sourcesContent":["import type { Bucket } from '../bucket.ts'\nimport type { SseCDownloadKey } from '../raw/index.ts'\nimport { type ContentSource, FileSource } from '../streams/source.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport { fileId as fileIdOf } from '../types/ids.ts'\nimport { DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { sanitizeErrorReason } from '../util/error-reason.ts'\nimport type { SyncAction } from './actions/index.ts'\nimport {\n  CopyAction,\n  DeleteLocalAction,\n  DeleteRemoteAction,\n  DownloadAction,\n  HideAction,\n  SkipAction,\n  UploadAction,\n} from './actions/index.ts'\nimport {\n  hashReadableStreamSha1,\n  normalizeSha1VerificationMaxBytes,\n  withSha1VerificationDeadline,\n} from './b2-sha1-reader.ts'\nimport { localFilesystemErrorReason } from './filesystem-errors.ts'\nimport {\n  deleteLocalFileInsideRoot,\n  validateScannedLocalFile,\n  writeLocalStreamInsideRoot,\n} from './local-file-io.ts'\nimport { isLocalFilesystemRoot } from './local-filesystem-root.ts'\nimport { readLocalSha1File } from './local-sha1.ts'\nimport { type SyncPair, zipFolders } from './pairing.ts'\nimport { safeRelativePathSegments } from './path-safety.ts'\nimport {\n  assertSupportedCompareMode,\n  type B2Sha1Reader,\n  type ComparePreparationResult,\n  preparePairsForCompare,\n  readyComparePair,\n} from './policies/compare.ts'\nimport type { ActionFactory } from './policies/index.ts'\nimport { generateActions } from './policies/index.ts'\nimport { asRawB2KeyPrefix, b2KeyToRelativePathUnderPrefix } from './prefix.ts'\nimport {\n  DEFAULT_SHA1_VERIFICATION_TIMEOUT_MILLIS,\n  normalizeSha1TimeoutMillis,\n} from './sha1-options.ts'\nimport type {\n  B2SyncPath,\n  LocalSyncPath,\n  SyncDirection,\n  SyncEvent,\n  SyncFolder,\n  SyncOptions,\n  SyncPath,\n  SyncScanOptions,\n  SyncSkipEvent,\n} from './types.ts'\n\nconst MAX_BUFFERED_SCAN_EVENTS = 100\nconst MAX_AGGREGATE_FAILED_PATHS = 100\nconst DEFAULT_DOWNLOAD_IDLE_TIMEOUT_MILLIS = 60_000\n\ninterface ScanEventBuffer {\n  readonly events: SyncEvent[]\n  fatalFilesystemErrorMessage?: string\n  sourceInventoryIncompleteMessage?: string\n  dropped: number\n}\n\n/**\n * Test hooks for bounded planning behavior.\n *\n * @internal\n */\nexport const synchronizerTestHooks: {\n  afterNonSha1PlanBatch?: (batchSize: number) => void\n} = {}\n\n/** Base configuration for a sync operation. */\nexport interface SynchronizerConfig {\n  /** The folder to read files from. */\n  readonly source: SyncFolder\n  /** The folder to write files to. */\n  readonly dest: SyncFolder\n  /** Options controlling comparison, deletion policy, and concurrency. */\n  readonly options: SyncOptions\n}\n\n/** A sync folder constrained to the local filesystem. */\nexport interface LocalSyncFolder extends SyncFolder {\n  /** Discriminant identifying a local folder. */\n  readonly type: 'local'\n  /** Absolute filesystem path to the local root directory. */\n  readonly root: string\n}\n\n/** A sync folder constrained to a B2 bucket prefix. */\nexport interface B2SyncFolder extends SyncFolder {\n  /** Discriminant identifying a B2 folder. */\n  readonly type: 'b2'\n  /** Raw B2 key prefix represented by this folder when known. */\n  readonly rawPrefix?: string\n}\n\n/** Configuration for a local-to-B2 sync (upload direction). */\nexport interface SynchronizerUpConfig extends SynchronizerConfig {\n  /** Local source folder. */\n  readonly source: LocalSyncFolder\n  /** B2 destination folder. */\n  readonly dest: B2SyncFolder\n  /** The target B2 bucket. */\n  readonly bucket: Bucket\n  /**\n   * Raw B2 key prefix for uploaded files in the bucket.\n   * Backslashes are preserved as raw B2 key characters.\n   */\n  readonly prefix: string\n}\n\n/** Configuration for a B2-to-local sync (download direction). */\nexport interface SynchronizerDownConfig extends SynchronizerConfig {\n  /** B2 source folder. */\n  readonly source: B2SyncFolder\n  /** Local destination folder. */\n  readonly dest: LocalSyncFolder\n  /** The source B2 bucket. */\n  readonly bucket: Bucket\n}\n\n/** Configuration for a B2-to-B2 sync (copy direction). */\nexport interface SynchronizerB2Config extends SynchronizerConfig {\n  /** B2 source folder. */\n  readonly source: B2SyncFolder\n  /** B2 destination folder. */\n  readonly dest: B2SyncFolder\n  /** The B2 bucket used for copy, hide, and delete operations. */\n  readonly bucket: Bucket\n  /**\n   * Key prefix for destination-side copy, hide, and delete mutations.\n   *\n   * When omitted, the synchronizer uses `dest.rawPrefix` when the destination\n   * folder exposes one. Set this explicitly for custom B2 folders that do not\n   * expose their raw prefix.\n   */\n  readonly prefix?: string\n}\n\n/** Concrete sync configurations supported by {@link synchronize}. */\nexport type SupportedSynchronizerConfig =\n  | SynchronizerUpConfig\n  | SynchronizerDownConfig\n  | SynchronizerB2Config\n\ninterface PreparedActionPlan {\n  readonly event: SyncEvent\n  readonly actions: readonly SyncAction[]\n}\n\ninterface LocalRootIdentity {\n  readonly deviceId: number | bigint\n  readonly inode: number | bigint\n}\n\ninterface LocalRootContext {\n  readonly root: string\n  readonly realPath: string\n  readonly identity?: LocalRootIdentity\n}\n\ninterface LocalRootContexts {\n  readonly source?: LocalRootContext\n  readonly dest?: LocalRootContext\n}\n\n/**\n * Infers the sync direction from the source and destination folder types.\n * @param source - The folder to read files from.\n * @param dest - The folder to write files to.\n *\n * @returns The resolved sync direction based on folder types.\n *\n * @throws When the source and destination folder types form an unsupported combination.\n */\nfunction resolveDirection(source: SyncFolder, dest: SyncFolder): SyncDirection {\n  if (source.type === 'local' && dest.type === 'b2') return 'local-to-b2'\n  if (source.type === 'b2' && dest.type === 'local') return 'b2-to-local'\n  if (source.type === 'b2' && dest.type === 'b2') return 'b2-to-b2'\n  throw new Error(`Unsupported sync direction: ${source.type} to ${dest.type}`)\n}\n\n/**\n * Runs a full sync operation: scans both folders, pairs files, generates actions,\n * and executes them with bounded concurrency. Yields {@link SyncEvent} entries for\n * each comparison and action result.\n *\n * @param config - The synchronizer configuration (source, dest, options, and optional bucket).\n *\n * @returns An async generator that yields comparison and action events.\n */\nexport function synchronize(config: SupportedSynchronizerConfig): AsyncGenerator<SyncEvent>\n/**\n * Legacy overload for broad custom synchronizer configurations.\n *\n * @param config - The synchronizer configuration.\n *\n * @returns An async generator that yields comparison and action events.\n *\n * @deprecated Use {@link SupportedSynchronizerConfig}. This legacy overload\n * accepts broad custom configurations for source compatibility, but the\n * supported union is the public contract for built-in sync directions.\n */\nexport function synchronize(config: SynchronizerConfig): AsyncGenerator<SyncEvent>\nexport async function* synchronize(config: SynchronizerConfig): AsyncGenerator<SyncEvent> {\n  const { source, dest, options } = config\n  assertSupportedCompareMode(options.compareMode)\n  const direction = resolveDirection(source, dest)\n  const dryRun = options.dryRun ?? false\n  const concurrency = normalizeSyncConcurrency(options.concurrency)\n  const keepDays = options.keepDays ?? 0\n  const compareThreshold = options.compareThreshold ?? 0\n  const nowMillis = Date.now()\n  const localRootContexts = await resolveLocalRootContexts(config)\n  const queuedEvents: SyncEvent[] = []\n  const failedPaths: string[] = []\n  const failedPathSet = new Set<string>()\n  let errorCount = 0\n  let failedPathOmittedCount = 0\n  let scanHadError = false\n  const runningActions = new Set<Promise<void>>()\n  const scanEvents: ScanEventBuffer = { events: [], dropped: 0 }\n  const scanOptions: SyncScanOptions = {\n    ...(options.include !== undefined ? { include: options.include } : {}),\n    ...(options.exclude !== undefined ? { exclude: options.exclude } : {}),\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    ...(options.maxScanEntries !== undefined ? { maxScanEntries: options.maxScanEntries } : {}),\n    ...(direction === 'b2-to-local' ? { requireLocalSafePaths: true } : {}),\n    onError: (event) => {\n      scanHadError = true\n      recordSyncError(event)\n      queueEvent(event)\n    },\n  }\n\n  const factory = createActionFactory(config, localRootContexts)\n  const readB2Sha1 = dryRun ? undefined : createB2Sha1Reader(config)\n  const actionAbortController = new AbortController()\n  const removeAbortForwarder = forwardAbortSignal(options.signal, actionAbortController)\n  let completed = false\n\n  async function* finishAfterAbort(): AsyncGenerator<SyncEvent> {\n    await drainActions()\n    yield* emitQueuedEvents()\n  }\n\n  try {\n    let pairs: SyncPair[]\n    try {\n      pairs = await collectPairs()\n    } catch (err) {\n      await drainActions()\n      if (options.signal?.aborted) {\n        yield* finishAfterAbort()\n        return\n      }\n      if (!scanHadError) {\n        yield* emitQueuedEvents()\n        throw err\n      }\n\n      yield* emitQueuedEvents()\n      yield aggregateErrorEvent()\n      completed = true\n      return\n    }\n\n    yield* emitQueuedEvents()\n    const filesystemError = scanFilesystemError(scanEvents)\n    if (filesystemError !== undefined) throw filesystemError\n\n    if (options.signal?.aborted) {\n      yield* finishAfterAbort()\n      return\n    }\n\n    if (scanHadError) {\n      if (errorCount > 0) yield aggregateErrorEvent()\n      completed = true\n      return\n    }\n\n    if (options.compareMode === 'sha1') {\n      const compareBatchSize = concurrency\n      for (let index = 0; index < pairs.length; index += compareBatchSize) {\n        if (yield* emitSha1Batch(pairs.slice(index, index + compareBatchSize))) return\n      }\n    } else {\n      for (let index = 0; index < pairs.length; index += concurrency) {\n        const items = pairs\n          .slice(index, index + concurrency)\n          .map((pair) => planPreparedPair(pair, readyComparePair(pair)))\n        synchronizerTestHooks.afterNonSha1PlanBatch?.(items.length)\n        if (yield* emitPreparedItems(items)) return\n      }\n    }\n\n    await drainActions()\n    yield* emitQueuedEvents()\n\n    if (errorCount > 0) {\n      yield aggregateErrorEvent()\n    }\n    completed = true\n  } finally {\n    if (!completed) {\n      abortActionController(\n        actionAbortController,\n        new DOMException('Sync iterator closed', 'AbortError'),\n      )\n    }\n    removeAbortForwarder()\n    await drainActions()\n  }\n\n  async function collectPairs(): Promise<SyncPair[]> {\n    const pairs: SyncPair[] = []\n    for await (const pair of zipFolders(source, dest, scanOptions, {\n      onSourceSkip(event) {\n        bufferScanEvent(scanEvents, event, direction, 'source')\n      },\n      onDestSkip(event) {\n        bufferScanEvent(scanEvents, event, direction, 'dest')\n      },\n    })) {\n      if (options.signal?.aborted) return pairs\n      validateB2SourcePairPrefix(pair, config)\n      pairs.push(pair)\n    }\n    return pairs\n  }\n\n  async function* emitSha1Batch(batch: readonly SyncPair[]): AsyncGenerator<SyncEvent, boolean> {\n    if (batch.length === 0) return false\n\n    // Keep SHA-1 hashing / B2 verification and transfer actions under one effective\n    // concurrency ceiling. This intentionally creates a batch barrier instead of\n    // overlapping compare reads with prior transfers.\n    await drainActions()\n    yield* emitQueuedEvents()\n\n    const preparedBatch = await processPreparedBatch(batch)\n    if (yield* emitPreparedItems(preparedBatch.items)) return true\n    if (preparedBatch.aborted || options.signal?.aborted) {\n      yield* finishAfterAbort()\n      return true\n    }\n    return false\n  }\n\n  async function* emitPreparedItems(\n    items: readonly PreparedActionPlan[],\n  ): AsyncGenerator<SyncEvent, boolean> {\n    for (const item of items) {\n      yield* emitQueuedEvents()\n      yield item.event\n      yield* emitQueuedEvents()\n      /* v8 ignore next -- abort between compare yield and scheduling is timing-dependent */\n      if (options.signal?.aborted) {\n        yield* finishAfterAbort()\n        return true\n      }\n      for (const action of item.actions) {\n        await scheduleAction(action)\n        yield* emitQueuedEvents()\n      }\n    }\n    return false\n  }\n\n  async function processPreparedBatch(\n    batch: readonly SyncPair[],\n  ): Promise<{ readonly items: readonly PreparedActionPlan[]; readonly aborted: boolean }> {\n    if (batch.length === 0) return { items: [], aborted: false }\n    const preparedPairs = await preparePairsForCompare(batch, 'sha1', {\n      concurrency,\n      ...(options.signal !== undefined ? { signal: options.signal } : {}),\n      ...(options.sha1ReadTimeoutMillis !== undefined\n        ? { sha1ReadTimeoutMillis: options.sha1ReadTimeoutMillis }\n        : {}),\n      readLocalSha1: readLocalSha1File,\n      ...(readB2Sha1 !== undefined ? { readB2Sha1 } : {}),\n    })\n\n    const items: PreparedActionPlan[] = []\n    for (const { originalPair, prepared } of preparedPairs) {\n      if (prepared.aborted || options.signal?.aborted) return { items, aborted: true }\n      items.push(planPreparedPair(originalPair, prepared))\n    }\n    return { items, aborted: false }\n  }\n\n  function planPreparedPair(\n    pair: SyncPair,\n    prepared: ComparePreparationResult,\n  ): PreparedActionPlan {\n    const event: SyncEvent = {\n      type: 'compare',\n      path: (pair[0] ?? pair[1])?.relativePath ?? '',\n      size: 0,\n      bytesHashed: prepared.bytesHashed,\n      ...(prepared.bytesVerified > 0 ? { bytesVerified: prepared.bytesVerified } : {}),\n    }\n\n    let preparedErrorEventCount = 0\n    for (const preparedEvent of prepared.events) {\n      queueEvent(preparedEvent)\n      if (preparedEvent.type === 'error') {\n        preparedErrorEventCount++\n        recordFailurePath(preparedEvent.path)\n      }\n    }\n    errorCount += prepared.errors.length\n    for (let index = preparedErrorEventCount; index < prepared.errors.length; index++) {\n      recordFailurePath(event.path)\n    }\n    if (prepared.skipActionGeneration) return { event, actions: [] }\n    if (\n      (scanHadError || scanHadFilesystemError(scanEvents)) &&\n      prepared.pair[0] === null &&\n      prepared.pair[1] !== null\n    ) {\n      return {\n        event,\n        actions: [\n          new SkipAction(prepared.pair[1].relativePath, 'not removed because scan errors occurred'),\n        ],\n      }\n    }\n    if (\n      sourceInventoryIncomplete(scanEvents) &&\n      prepared.pair[0] === null &&\n      prepared.pair[1] !== null\n    ) {\n      return {\n        event,\n        actions: [\n          new SkipAction(\n            prepared.pair[1].relativePath,\n            scanEvents.sourceInventoryIncompleteMessage ??\n              'not removed because the source scan skipped unsafe B2 names',\n          ),\n        ],\n      }\n    }\n\n    const actions = [\n      ...generateActions(\n        prepared.pair,\n        direction,\n        options.compareMode,\n        options.keepMode,\n        keepDays,\n        nowMillis,\n        factory,\n        compareThreshold,\n      ),\n    ]\n\n    return { event, actions }\n  }\n\n  async function scheduleAction(action: SyncAction): Promise<void> {\n    const task = executeAction(action).finally(() => {\n      runningActions.delete(task)\n    })\n    runningActions.add(task)\n    if (runningActions.size >= concurrency) await Promise.race(runningActions)\n  }\n\n  async function executeAction(action: SyncAction): Promise<void> {\n    try {\n      if (actionAbortController.signal.aborted) return\n      const event = await action.execute(dryRun, actionAbortController.signal)\n      queueEvent(event)\n    } catch (err) {\n      const event: SyncEvent = {\n        type: 'error',\n        path: action.relativePath,\n        size: 0,\n        message: sanitizeErrorReason(err),\n      }\n      recordSyncError(event)\n      queueEvent(event)\n    }\n  }\n\n  function recordSyncError(event: SyncEvent): void {\n    errorCount += 1\n    recordFailurePath(event.path)\n  }\n\n  function recordFailurePath(path: string): void {\n    if (path === '') return\n    if (failedPathSet.has(path)) return\n    failedPathSet.add(path)\n    if (failedPaths.length < MAX_AGGREGATE_FAILED_PATHS) {\n      failedPaths.push(path)\n    } else {\n      failedPathOmittedCount++\n    }\n  }\n\n  function aggregateErrorEvent(): SyncEvent {\n    return {\n      type: 'error',\n      path: '',\n      size: 0,\n      message: `${errorCount} sync error(s) occurred`,\n      failureCount: errorCount,\n      failedPaths: [...failedPaths],\n      ...(failedPathOmittedCount > 0 ? { failedPathOmittedCount } : {}),\n    }\n  }\n\n  function queueEvent(event: SyncEvent): void {\n    queuedEvents.push(event)\n  }\n\n  async function* emitQueuedEvents(): AsyncGenerator<SyncEvent> {\n    yield* drainScanEvents(scanEvents)\n    for (const event of queuedEvents.splice(0)) yield event\n  }\n\n  async function drainActions(): Promise<void> {\n    while (runningActions.size > 0) {\n      await Promise.race(runningActions)\n    }\n  }\n}\n\n/**\n * Normalizes user-provided sync concurrency before it controls compare batches and transfers.\n *\n * @param value - Optional concurrency value from sync options.\n *\n * @returns A positive integer concurrency value.\n *\n * @throws When the configured concurrency is not a positive integer.\n */\nfunction normalizeSyncConcurrency(value: number | undefined): number {\n  const candidate = value ?? DEFAULT_TRANSFER_CONCURRENCY\n  if (!Number.isInteger(candidate) || candidate < 1) {\n    throw new RangeError('Sync concurrency must be a positive integer')\n  }\n  return candidate\n}\n\nfunction normalizeDownloadIdleTimeoutMillis(value: number | undefined): number {\n  if (value === undefined) return DEFAULT_DOWNLOAD_IDLE_TIMEOUT_MILLIS\n  if (value === Number.POSITIVE_INFINITY) return value\n  if (!Number.isFinite(value) || value < 1) {\n    throw new RangeError('downloadIdleTimeoutMillis must be a positive finite number or Infinity')\n  }\n  return Math.floor(value)\n}\n\nfunction assertValidB2ContentLength(contentLength: number): number {\n  if (!Number.isSafeInteger(contentLength) || contentLength < 0) {\n    throw new Error('B2 contentLength must be a non-negative safe integer')\n  }\n  return contentLength\n}\n\nfunction createB2Sha1Reader(config: SynchronizerConfig): B2Sha1Reader | undefined {\n  const upConfig = config as Partial<SynchronizerUpConfig>\n  const downConfig = config as Partial<SynchronizerDownConfig>\n  const bucket = upConfig.bucket ?? downConfig.bucket\n  if (bucket === undefined) return undefined\n  const readablePrefixes = b2ReadableRawPrefixes(config)\n  const idleTimeoutMillis = normalizeSha1TimeoutMillis(config.options.sha1ReadTimeoutMillis)\n  const verificationTimeoutMillis = normalizeSha1TimeoutMillis(\n    config.options.sha1VerificationTimeoutMillis,\n    DEFAULT_SHA1_VERIFICATION_TIMEOUT_MILLIS,\n  )\n\n  return async (path, signal) => {\n    const expectedBytes = assertValidB2ContentLength(path.selectedVersion.contentLength)\n    const maxBytes = normalizeSha1VerificationMaxBytes(\n      expectedBytes,\n      config.options.sha1VerificationMaxBytes,\n    )\n    return withSha1VerificationDeadline(\n      signal,\n      verificationTimeoutMillis,\n      async (deadlineSignal) => {\n        deadlineSignal.throwIfAborted()\n        if (maxBytes < expectedBytes) {\n          throw new Error(\n            `sha1 B2 verification skipped because contentLength ${expectedBytes} exceeds ${maxBytes} byte verification budget`,\n          )\n        }\n        const serverSideEncryption = toSseCDownloadKey(\n          config.options.encryptionProvider?.getSettingForDownload(path.selectedVersion),\n        )\n        const fileName = validateB2SyncPathInAnyPrefix(readablePrefixes, path, 'read')\n        const result = await bucket.file(fileName).downloadById(path.selectedVersion.fileId, {\n          ...(serverSideEncryption !== undefined ? { serverSideEncryption } : {}),\n          signal: deadlineSignal,\n        })\n        const verified = await hashReadableStreamSha1(result.body, deadlineSignal, {\n          idleTimeoutMillis,\n          maxBytes,\n          expectedBytes,\n        })\n        return { contentSha1: verified.contentSha1, bytesRead: verified.bytesRead }\n      },\n    )\n  }\n}\n\nfunction forwardAbortSignal(\n  source: AbortSignal | undefined,\n  controller: AbortController,\n): () => void {\n  if (source === undefined) return () => undefined\n  if (source.aborted) {\n    abortActionController(controller, source.reason)\n    return () => undefined\n  }\n\n  const abort = () => abortActionController(controller, source.reason)\n  source.addEventListener('abort', abort, { once: true })\n  return () => source.removeEventListener('abort', abort)\n}\n\nfunction abortActionController(controller: AbortController, reason: unknown): void {\n  if (!controller.signal.aborted) {\n    controller.abort(reason)\n  }\n}\n\n/**\n * Narrowing assertion that a `Bucket` is present for an action that requires\n * it. Throws with a consistent, context-tagged message when the configured\n * direction did not supply one (e.g. `b2-to-local` direction asking for an\n * upload action).\n *\n * Uses TypeScript's `asserts` signature so call-site flow narrows\n * `bucket` from `Bucket | undefined` to `Bucket` after the check, without\n * requiring a separate `if (!bucket) throw ...` line per action factory.\n *\n * @param bucket - The (possibly missing) bucket reference.\n * @param context - Short verb describing the action being constructed\n *   (e.g. `'upload'`, `'download'`). Surfaced in the error message.\n *\n * @throws `Error` when `bucket` is `undefined` or `null`.\n */\nfunction assertBucket(bucket: Bucket | undefined, context: string): asserts bucket is Bucket {\n  if (!bucket) throw new Error(`Bucket required for ${context} actions`)\n}\n\n/**\n * Returns the root for a local sync folder required by an action.\n *\n * @param folder - The configured folder to validate.\n * @param role - Whether the local folder is the source or destination.\n * @param context - Short verb describing the action being constructed.\n *\n * @returns The local filesystem root.\n *\n * @throws `Error` when the folder is not local or has no root.\n */\nfunction requireLocalRoot(\n  folder: SyncFolder | undefined,\n  role: 'source' | 'destination',\n  context: string,\n): string {\n  const root = folder?.type === 'local' ? (folder as Partial<LocalSyncFolder>).root : undefined\n  if (typeof root !== 'string' || root === '') {\n    throw new Error(`Local ${role} root required for ${context} actions`)\n  }\n  return root\n}\n\nasync function resolveLocalRootContexts(config: SynchronizerConfig): Promise<LocalRootContexts> {\n  const sourceIsLocalFilesystem = isLocalFilesystemFolder(config.source)\n  const destIsLocalFilesystem = isLocalFilesystemFolder(config.dest)\n  if (!sourceIsLocalFilesystem && !destIsLocalFilesystem) return {}\n\n  const sourceContext = config.dest.type === 'b2' ? 'upload' : 'sync'\n  const destContext = config.source.type === 'b2' ? 'download' : 'sync'\n  return {\n    ...(sourceIsLocalFilesystem\n      ? {\n          source: await resolveLocalRootContext(\n            requireLocalRoot(config.source, 'source', sourceContext),\n          ),\n        }\n      : {}),\n    ...(destIsLocalFilesystem\n      ? {\n          dest: await resolveLocalRootContext(\n            requireLocalRoot(config.dest, 'destination', destContext),\n          ),\n        }\n      : {}),\n  }\n}\n\nasync function resolveLocalRootContext(root: string): Promise<LocalRootContext> {\n  const { realpath, stat } = await import('node:fs/promises')\n  const { resolve } = await import('node:path')\n  const safeRoot = resolve(root)\n  const realPath = await realpath(safeRoot).catch((err: unknown) => {\n    if (isNotFoundError(err)) return safeRoot\n    throw err\n  })\n  const stats = await stat(realPath).catch((err: unknown) => {\n    if (isNotFoundError(err)) return undefined\n    throw err\n  })\n  if (stats !== undefined && !stats.isDirectory()) {\n    throw new Error('Local sync root is not a directory')\n  }\n  return {\n    root: safeRoot,\n    realPath,\n    ...(stats === undefined\n      ? {}\n      : { identity: { deviceId: stats.dev, inode: stats.ino } satisfies LocalRootIdentity }),\n  }\n}\n\nfunction isLocalFilesystemFolder(folder: SyncFolder | undefined): folder is LocalSyncFolder {\n  return folder?.type === 'local' && isLocalFilesystemRoot(folder)\n}\n/**\n * Narrows a setting to SSE-C; non-SSE-C source settings need no key on read.\n *\n * @param setting - Provider-supplied encryption setting, or undefined.\n *\n * @returns The SSE-C setting when one is provided; otherwise undefined.\n */\nfunction toSseCEncryptionSetting(\n  setting: EncryptionSetting | undefined,\n): Extract<EncryptionSetting, { readonly mode: 'SSE-C' }> | undefined {\n  if (setting?.mode !== 'SSE-C') return undefined\n  return setting\n}\n\n/**\n * Returns a download key from SSE-C settings; non-SSE-C downloads need no key.\n *\n * @param setting - Provider-supplied encryption setting, or undefined.\n *\n * @returns A download key for SSE-C files; otherwise undefined.\n */\nfunction toSseCDownloadKey(setting: EncryptionSetting | undefined): SseCDownloadKey | undefined {\n  return toSseCEncryptionSetting(setting)\n}\n\n/**\n * Creates a configured sync engine wired to the bucket and paths in the given config.\n *\n * For sync operations that may need to remove destination-only files (the\n * `keepMode: 'delete'` policy), the factory reads the destination\n * bucket's cached `fileLockConfiguration` once so `removeOrphan` can\n * dispatch to either `hide` (locked buckets) or `deleteFileVersion`\n * (vanilla buckets) without a per-file branch. The cache is whatever\n * `client.listBuckets()` or `client.createBucket()` returned — callers\n * who flipped lock state mid-sync (rare) should refresh before\n * synchronize().\n *\n * @param config - Synchronizer configuration containing source, destination, and options.\n * @param localRootContexts - Resolved filesystem roots captured before action creation.\n *\n * @returns An action factory bound to the provided configuration.\n */\nfunction createActionFactory(\n  config: SynchronizerConfig,\n  localRootContexts: LocalRootContexts,\n): ActionFactory {\n  const upConfig = config as Partial<SynchronizerUpConfig>\n  const downConfig = config as Partial<SynchronizerDownConfig>\n  const uploadPrefix = asRawB2KeyPrefix(upConfig.prefix ?? b2FolderRawPrefix(config.dest) ?? '')\n  const sourceB2Prefix = b2FolderRawPrefix(config.source)\n\n  const destBucket = upConfig.bucket ?? downConfig.bucket\n  // Defensive optional chain on `info`: synchronizer tests use Bucket\n  // mocks that don't populate this field. Real `Bucket` instances always\n  // do (constructor parameter).\n  const bucketIsLocked = destBucket?.info?.fileLockConfiguration?.value?.isFileLockEnabled ?? false\n\n  const factory: ActionFactory = {\n    upload(source: LocalSyncPath, dest?: B2SyncPath): SyncAction {\n      const bucket = upConfig.bucket\n      assertBucket(bucket, 'upload')\n\n      return new UploadAction(\n        source.relativePath,\n        source.absolutePath,\n        source.size,\n        async (absPath, relPath, signal) => {\n          const rootContext = localRootContexts.source\n          const root = rootContext?.root ?? (upConfig.source as Partial<LocalSyncFolder>).root ?? ''\n          const fileName =\n            dest !== undefined\n              ? validateB2SyncPathInPrefix(uploadPrefix, dest)\n              : `${uploadPrefix}${relPath}`\n          if (rootContext !== undefined) {\n            await assertLocalRootContextCurrent(rootContext, relPath, { allowSymlinkRoot: true })\n          }\n          const targetPath =\n            rootContext === undefined\n              ? await resolveContainedLocalPath(root, source.relativePath, absPath)\n              : await resolveContainedLocalPath(rootContext.realPath, source.relativePath)\n          throwIfAborted(signal)\n          // FileSource avoids whole-file buffering and rejects path swaps on a\n          // best-effort basis. On Windows, callers that need tamper-resistant\n          // same-size rewrite detection should use compareMode: 'sha1' or an\n          // independent digest because restored modification times can hide\n          // local rewrites.\n          const fileSource = await createValidatedUploadFileSource(source, targetPath)\n          throwIfAborted(signal)\n          const serverSideEncryption = config.options.encryptionProvider?.getSettingForUpload(\n            fileName,\n            fileSource.size,\n          )\n          await bucket.upload({\n            fileName,\n            source: fileSource,\n            ...(serverSideEncryption !== undefined ? { serverSideEncryption } : {}),\n            ...(signal !== undefined ? { signal } : {}),\n          })\n        },\n      )\n    },\n\n    download(source: B2SyncPath, scannedDest?: LocalSyncPath | null): SyncAction {\n      const bucket = downConfig.bucket\n      assertBucket(bucket, 'download')\n\n      return new DownloadAction(source.relativePath, source.size, async (relPath, signal) => {\n        const rootContext = localRootContexts.dest\n        const root = rootContext?.root ?? (downConfig.dest as Partial<LocalSyncFolder>).root ?? ''\n        safeRelativePathSegments(relPath)\n        const b2FileName =\n          sourceB2Prefix === undefined\n            ? source.selectedVersion.fileName\n            : validateB2SyncPathInPrefix(sourceB2Prefix, source, 'read')\n        const idleTimeoutMillis = normalizeDownloadIdleTimeoutMillis(\n          config.options.downloadIdleTimeoutMillis,\n        )\n        const expectedBytes = assertValidB2ContentLength(source.selectedVersion.contentLength)\n        if (rootContext !== undefined) {\n          await assertLocalRootContextCurrent(rootContext, relPath, { allowSymlinkRoot: false })\n        }\n        await ensureLocalSyncRootDirectory(root, relPath)\n        const serverSideEncryption = toSseCDownloadKey(\n          config.options.encryptionProvider?.getSettingForDownload(source.selectedVersion),\n        )\n        const result = await bucket.file(b2FileName).downloadById(source.selectedVersion.fileId, {\n          ...(serverSideEncryption !== undefined ? { serverSideEncryption } : {}),\n          ...(signal !== undefined ? { signal } : {}),\n        })\n        try {\n          await writeLocalStreamInsideRoot(root, relPath, result.body, {\n            expectedBytes,\n            ...(scannedDest !== undefined ? { expectedDestination: scannedDest } : {}),\n            idleTimeoutMillis,\n            ...(signal !== undefined ? { signal } : {}),\n          })\n        } catch (err) {\n          await cancelReadableStreamBody(result.body, err)\n          throw err\n        }\n      })\n    },\n\n    copy(source: B2SyncPath, destRelativePath: string): SyncAction {\n      return copyToB2Key(source, `${uploadPrefix}${destRelativePath}`)\n    },\n\n    copyB2Path(source: B2SyncPath, dest: B2SyncPath): SyncAction {\n      return copyToB2Key(source, validateB2SyncPathInPrefix(uploadPrefix, dest))\n    },\n\n    hide(path: string): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'hide')\n\n      return new HideAction(path, async (_relPath, signal) => {\n        await bucket.hideFile(\n          `${uploadPrefix}${path}`,\n          signal === undefined ? undefined : { signal },\n        )\n      })\n    },\n\n    hideB2Path(path: B2SyncPath): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'hide')\n      const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path)\n\n      return new HideAction(path.relativePath, async (_relPath, signal) => {\n        await bucket.hideFile(b2FileName, signal === undefined ? undefined : { signal })\n      })\n    },\n\n    deleteRemote(path: B2SyncPath): SyncAction {\n      const bucket = upConfig.bucket ?? downConfig.bucket\n      assertBucket(bucket, 'delete')\n\n      // Bug fix: `DeleteRemoteAction` invokes the closure with\n      // `relativePath` (the scanner-stripped name relative to the sync\n      // prefix), but B2 stores files under the FULL name including the\n      // prefix. Use the FileVersion's authoritative `fileName` — the\n      // actual B2 key — rather than reconstructing it via prefix\n      // concat. Without this, syncs with a non-empty destination\n      // prefix (e.g. `'site/'`) failed orphan deletion with\n      // `file_not_present`.\n      const b2FileName = validateB2SyncPathInPrefix(uploadPrefix, path)\n      return new DeleteRemoteAction(\n        path.relativePath,\n        path.selectedVersion.fileId as string,\n        async (fileId, _fileName, signal) => {\n          await bucket.deleteFileVersion(\n            b2FileName,\n            fileIdOf(fileId),\n            signal === undefined ? undefined : { signal },\n          )\n        },\n      )\n    },\n\n    deleteLocal(path: LocalSyncPath): SyncAction {\n      const rootContext = localRootContexts.dest\n      const root = rootContext?.root ?? localSyncRoot(downConfig.dest)\n      return new DeleteLocalAction(\n        path.relativePath,\n        path.absolutePath,\n        async (absPath, signal) => {\n          signal?.throwIfAborted()\n          if (absPath !== path.absolutePath) {\n            throw new Error(`Refusing to delete outside sync root: ${path.relativePath}`)\n          }\n          signal?.throwIfAborted()\n          try {\n            if (rootContext !== undefined) {\n              await assertLocalRootContextCurrent(rootContext, path.relativePath, {\n                allowSymlinkRoot: false,\n              })\n            }\n            await deleteLocalFileInsideRoot(root, path)\n          } catch (err) {\n            if (isLocalDeleteSafetyError(err)) throw err\n            throw new Error(`failed to delete local file: ${localFilesystemErrorReason(err)}`)\n          }\n        },\n      )\n    },\n\n    removeOrphan(dest: B2SyncPath): SyncAction {\n      // Locked buckets: `b2_delete_file_version` is blocked or stacks\n      // hide markers under retention; a hide is the safe choice.\n      // Vanilla buckets: plain delete is the right move — hide markers\n      // would just litter the version history.\n      return bucketIsLocked\n        ? (factory.hideB2Path?.(dest) ?? factory.hide(dest.relativePath))\n        : factory.deleteRemote(dest)\n    },\n  }\n\n  function copyToB2Key(source: B2SyncPath, targetPath: string): SyncAction {\n    const bucket = upConfig.bucket\n    assertBucket(bucket, 'copy')\n\n    return new CopyAction(source.relativePath, source.size, async (_relPath, signal) => {\n      if (sourceB2Prefix !== undefined) validateB2SyncPathInPrefix(sourceB2Prefix, source, 'read')\n      const destinationServerSideEncryption =\n        config.options.encryptionProvider?.getSettingForUpload(targetPath, source.size)\n      const sourceServerSideEncryption = toSseCEncryptionSetting(\n        config.options.encryptionProvider?.getSettingForDownload(source.selectedVersion),\n      )\n      await bucket.copyFile({\n        sourceFileId: source.selectedVersion.fileId,\n        fileName: targetPath,\n        ...(destinationServerSideEncryption !== undefined\n          ? { destinationServerSideEncryption }\n          : {}),\n        ...(sourceServerSideEncryption !== undefined ? { sourceServerSideEncryption } : {}),\n        ...(signal !== undefined ? { signal } : {}),\n      })\n    })\n  }\n\n  return factory\n}\n\nasync function createValidatedUploadFileSource(\n  source: LocalSyncPath,\n  absolutePath: string,\n): Promise<ContentSource> {\n  try {\n    const fileSource = await FileSource.fromPath(absolutePath)\n    await validateScannedLocalFile({ ...source, absolutePath })\n    return fileSource\n  } catch (err) {\n    throw normalizeLocalUploadSourceError(err)\n  }\n}\n\nfunction normalizeLocalUploadSourceError(err: unknown): Error {\n  if (err instanceof Error && err.message.startsWith('local file changed before upload')) {\n    return err\n  }\n  const message = err instanceof Error ? err.message : String(err)\n  if (message.includes('not a regular file')) {\n    return new Error('local file changed before upload: not a regular file')\n  }\n  if (message.includes('changed') || message.includes('modified')) {\n    return new Error('local file changed before upload')\n  }\n  return new Error(`local file changed before upload: ${sanitizeErrorReason(err)}`)\n}\n\nfunction localSyncRoot(folder: LocalSyncFolder | undefined): string {\n  return folder?.type === 'local' ? folder.root : ''\n}\n\nfunction b2FolderRawPrefix(folder: SyncFolder | undefined): string | undefined {\n  if (folder?.type !== 'b2') return undefined\n  const rawPrefix = (folder as B2SyncFolder).rawPrefix\n  return typeof rawPrefix === 'string' ? rawPrefix : undefined\n}\n\nfunction validateB2SourcePairPrefix(pair: SyncPair, config: SynchronizerConfig): void {\n  const [source] = pair\n  if (config.source.type !== 'b2' || source === null || !isB2SyncPath(source)) return\n  const sourcePrefix = b2FolderRawPrefix(config.source)\n  if (sourcePrefix === undefined) return\n  validateB2SyncPathInPrefix(sourcePrefix, source, 'read')\n}\n\nfunction b2ReadableRawPrefixes(config: SynchronizerConfig): readonly string[] {\n  const prefixes: string[] = []\n  const sourcePrefix = b2FolderRawPrefix(config.source)\n  if (config.source.type === 'b2') prefixes.push(sourcePrefix ?? '')\n\n  const upConfig = config as Partial<SynchronizerUpConfig>\n  if (config.dest.type === 'b2') {\n    prefixes.push(upConfig.prefix ?? b2FolderRawPrefix(config.dest) ?? '')\n  }\n\n  return [...new Set(prefixes.map((prefix) => asRawB2KeyPrefix(prefix)))]\n}\n\nfunction validateB2SyncPathInAnyPrefix(\n  prefixes: readonly string[],\n  path: B2SyncPath,\n  operation: string,\n): string {\n  let firstError = new Error(`Refusing to ${operation} B2 key: ${path.relativePath}`)\n  for (const prefix of prefixes) {\n    try {\n      return validateB2SyncPathInPrefix(prefix, path, operation)\n    } catch (err) {\n      if (err instanceof Error) firstError = err\n    }\n  }\n  throw firstError\n}\n\nfunction validateB2SyncPathInPrefix(\n  prefix: string,\n  path: B2SyncPath,\n  operation = 'mutate',\n): string {\n  const fileName = path.selectedVersion.fileName\n  if (!fileName.startsWith(prefix)) {\n    throw new Error(\n      `Refusing to ${operation} B2 key outside configured prefix: ${path.relativePath}`,\n    )\n  }\n\n  const relativePath = b2KeyToRelativePathUnderPrefix(prefix, fileName)\n  if (relativePath !== path.relativePath) {\n    throw new Error(\n      `Refusing to ${operation} mismatched B2 key for sync path: ${path.relativePath}`,\n    )\n  }\n\n  return fileName\n}\n\nfunction isB2SyncPath(path: SyncPath): path is B2SyncPath {\n  return 'selectedVersion' in path\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal?.aborted === true) {\n    throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n}\n\nasync function cancelReadableStreamBody(\n  body: ReadableStream<Uint8Array>,\n  reason: unknown,\n): Promise<void> {\n  if (body.locked) return\n  try {\n    await body.cancel(reason)\n  } catch {\n    // Best-effort response cleanup must not mask the setup or write failure.\n  }\n}\n\nasync function assertLocalRootContextCurrent(\n  context: LocalRootContext,\n  relativePath: string,\n  options: { readonly allowSymlinkRoot: boolean },\n): Promise<void> {\n  if (context.identity === undefined) return\n\n  const { lstat, realpath, stat } = await import('node:fs/promises')\n  let currentRealPath: string\n  try {\n    const rootLinkStats = await lstat(context.root)\n    if (!options.allowSymlinkRoot && rootLinkStats.isSymbolicLink()) {\n      throw new Error(`Refusing to access sync root through symlink: ${relativePath}`)\n    }\n    currentRealPath = await realpath(context.root)\n  } catch (err) {\n    if (err instanceof Error && err.message.startsWith('Refusing to access sync root')) throw err\n    throw new Error(`Local sync root changed before filesystem action: ${relativePath}`)\n  }\n\n  if (currentRealPath !== context.realPath) {\n    throw new Error(`Local sync root changed before filesystem action: ${relativePath}`)\n  }\n\n  let currentStats: Awaited<ReturnType<typeof stat>>\n  try {\n    currentStats = await stat(context.realPath)\n  } catch {\n    throw new Error(`Local sync root changed before filesystem action: ${relativePath}`)\n  }\n\n  if (\n    !currentStats.isDirectory() ||\n    currentStats.dev !== context.identity.deviceId ||\n    currentStats.ino !== context.identity.inode\n  ) {\n    throw new Error(`Local sync root changed before filesystem action: ${relativePath}`)\n  }\n}\n\nasync function ensureLocalSyncRootDirectory(root: string, relativePath: string): Promise<void> {\n  if (root === '') {\n    throw new Error('Local sync root required for filesystem mutation')\n  }\n\n  const { lstat, mkdir } = await import('node:fs/promises')\n  const { resolve } = await import('node:path')\n  const safeRoot = resolve(root)\n\n  try {\n    const stats = await lstat(safeRoot)\n    if (stats.isSymbolicLink()) {\n      throw new Error(`Refusing to access sync root through symlink: ${relativePath}`)\n    }\n    if (!stats.isDirectory()) {\n      throw new Error(`Local sync root is not a directory: ${relativePath}`)\n    }\n    return\n  } catch (error) {\n    if (!isNotFoundError(error)) throw error\n  }\n\n  await mkdir(safeRoot, { recursive: true })\n  await assertLocalRootHasNoSymlink(safeRoot, relativePath)\n}\n\nfunction bufferScanEvent(\n  buffer: ScanEventBuffer,\n  event: SyncEvent,\n  direction: SyncDirection,\n  scanSide: 'source' | 'dest',\n): void {\n  if (event.type === 'skip' && event.reason === 'filesystem-error') {\n    buffer.fatalFilesystemErrorMessage ??= event.message\n  }\n  if (sourceSkipMakesInventoryIncomplete(event, direction, scanSide)) {\n    buffer.sourceInventoryIncompleteMessage ??= sourceInventoryIncompleteMessage(direction)\n  }\n  if (buffer.events.length < MAX_BUFFERED_SCAN_EVENTS) {\n    buffer.events.push(event)\n  } else {\n    buffer.dropped++\n  }\n}\n\nfunction* drainScanEvents(buffer: ScanEventBuffer): Generator<SyncEvent> {\n  while (buffer.events.length > 0) {\n    const event = buffer.events.shift()\n    if (event) yield event\n  }\n\n  if (buffer.dropped > 0) {\n    yield {\n      type: 'skip',\n      path: '',\n      size: 0,\n      reason: 'scan-skip-overflow',\n      message: `${buffer.dropped} scanner skip event(s) were omitted after ${MAX_BUFFERED_SCAN_EVENTS} buffered diagnostics`,\n    }\n    buffer.dropped = 0\n  }\n}\n\nfunction scanHadFilesystemError(scanEvents: ScanEventBuffer): boolean {\n  return scanEvents.fatalFilesystemErrorMessage !== undefined\n}\n\nfunction sourceInventoryIncomplete(scanEvents: ScanEventBuffer): boolean {\n  return scanEvents.sourceInventoryIncompleteMessage !== undefined\n}\n\nfunction scanFilesystemError(scanEvents: ScanEventBuffer): Error | undefined {\n  return scanEvents.fatalFilesystemErrorMessage === undefined\n    ? undefined\n    : new Error(scanEvents.fatalFilesystemErrorMessage)\n}\n\nfunction sourceSkipMakesInventoryIncomplete(\n  event: SyncEvent,\n  direction: SyncDirection,\n  scanSide: 'source' | 'dest',\n): event is SyncSkipEvent {\n  if (scanSide !== 'source' || event.type !== 'skip') return false\n\n  if (direction === 'local-to-b2') {\n    return (\n      event.reason === 'unsafe-name' ||\n      event.reason === 'stale-download-partial' ||\n      event.reason === 'path-too-long-for-regexp'\n    )\n  }\n\n  if (direction === 'b2-to-local' || direction === 'b2-to-b2') {\n    return (\n      event.reason === 'unsafe-name' ||\n      event.reason === 'local-unsafe-name' ||\n      event.reason === 'relative-path-collision' ||\n      event.reason === 'local-path-collision' ||\n      event.reason === 'path-too-long-for-regexp'\n    )\n  }\n\n  return false\n}\n\nfunction sourceInventoryIncompleteMessage(direction: SyncDirection): string {\n  return direction === 'local-to-b2'\n    ? 'not removed because the source scan skipped local paths'\n    : 'not removed because the source scan skipped unsafe B2 names'\n}\n\nfunction isLocalDeleteSafetyError(err: unknown): boolean {\n  if (!(err instanceof Error)) return false\n  return (\n    err.message === 'Local sync root required for filesystem mutation' ||\n    err.message.startsWith('Local sync root changed before filesystem action: ') ||\n    err.message.startsWith('Refusing to ') ||\n    err.message.startsWith('Local sync root is not a directory: ') ||\n    err.message.startsWith('unsafe local delete path: ')\n  )\n}\n\nasync function resolveContainedLocalPath(\n  root: string,\n  relativePath: string,\n  absolutePath?: string,\n): Promise<string> {\n  if (root === '') {\n    throw new Error('Local sync root required for filesystem mutation')\n  }\n\n  const { isAbsolute, relative, resolve, sep } = await import('node:path')\n  const safeRoot = resolve(root)\n  const target =\n    absolutePath === undefined ? resolve(safeRoot, relativePath) : resolve(absolutePath)\n  const pathFromRoot = relative(safeRoot, target)\n  const escapesRoot =\n    pathFromRoot === '..' || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)\n\n  /* v8 ignore next -- defense-in-depth after prior no-follow and symlink checks. */\n  if (escapesRoot) {\n    throw new Error(`Refusing to access path outside sync root: ${relativePath}`)\n  }\n\n  await assertLocalRootHasNoSymlink(safeRoot, relativePath)\n  await assertPathHasNoSymlinkComponents(safeRoot, pathFromRoot, relativePath)\n\n  return target\n}\n\nasync function assertLocalRootHasNoSymlink(safeRoot: string, relativePath: string): Promise<void> {\n  const { lstat } = await import('node:fs/promises')\n  try {\n    const stats = await lstat(safeRoot)\n    if (stats.isSymbolicLink()) {\n      throw new Error(`Refusing to access sync root through symlink: ${relativePath}`)\n    }\n  } catch (error) {\n    if (isNotFoundError(error)) return\n    throw error\n  }\n}\n\nasync function assertPathHasNoSymlinkComponents(\n  safeRoot: string,\n  pathFromRoot: string,\n  relativePath: string,\n): Promise<void> {\n  if (pathFromRoot === '') return\n\n  const { lstat } = await import('node:fs/promises')\n  const { join, sep } = await import('node:path')\n  let current = safeRoot\n\n  for (const segment of pathFromRoot.split(sep)) {\n    current = join(current, segment)\n    let stats: Awaited<ReturnType<typeof lstat>>\n    try {\n      stats = await lstat(current)\n    } catch (error) {\n      if (isNotFoundError(error)) return\n      throw error\n    }\n    if (stats.isSymbolicLink()) {\n      throw new Error(`Refusing to access path through symlink: ${relativePath}`)\n    }\n  }\n}\n\nfunction isNotFoundError(error: unknown): boolean {\n  return (\n    typeof error === 'object' &&\n    error !== null &&\n    'code' in error &&\n    (error as { readonly code?: unknown }).code === 'ENOENT'\n  )\n}\n"],"mappings":"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"}

package/dist/sync/types.d.cts

@@ -1,11 +1,97 @@
 import { EncryptionSetting } from '../types/encryption.js';
 import { FileVersion } from '../types/file.js';
-/** Strategy for comparing source and destination files: by modification time, size, or skip comparison. */
-export type CompareMode = 'modtime' | 'size' | 'none';
+import { SyncSha1State } from './sha1-metadata.js';
+/**
+ * Strategy for comparing source and destination files.
+ *
+ * The `sha1` mode compares 40-character hexadecimal SHA-1 digests as a practical drift
+ * detector. Digest case is normalized before comparison. Missing, null, unavailable, or
+ * non-verifiable metadata cannot prove equality: the high-level synchronizer either transfers
+ * conservatively for untrusted metadata or skips action generation with a surfaced event when a
+ * B2 file has no comparable digest. Untrusted B2 metadata may require downloading the selected
+ * B2 version to hash its bytes before equality can be trusted. This is not a cryptographic
+ * integrity or tamper-proofing guarantee, because SHA-1 collisions are possible.
+ */
+export type CompareMode = 'modtime' | 'size' | 'sha1' | 'none';
 /** Strategy for handling destination files not present in the source. */
 export type KeepMode = 'no-delete' | 'delete' | 'keep-days';
 /** Direction of a sync operation. */
 export type SyncDirection = 'local-to-b2' | 'b2-to-local' | 'b2-to-b2';
+/**
+ * Glob string or regular expression used to include or exclude sync paths.
+ *
+ * Glob strings use a small SDK-defined dialect against folder-relative paths with forward
+ * slashes: `*` and `?` match within one path segment, and a path segment that is exactly `**`
+ * matches across directory boundaries. Character classes, brace expansion, extglobs, and
+ * backslash escaping are not supported. Slash-less globs use basename-style matching at any
+ * directory depth, so `*.tmp` matches `nested/file.tmp` and `readme.md` matches both `readme.md`
+ * and `docs/readme.md`. They also match ancestor directory names, so `node_modules` matches every
+ * file under a `node_modules` directory. Exclude filters win over include filters.
+ *
+ * Regular expressions are matched against the full relative path. Global and sticky flags are
+ * ignored so matching does not mutate `lastIndex`. RegExp acceptance is a best-effort safety
+ * heuristic for synchronous matching, and the exact accepted subset may change as the SDK tightens
+ * protection. Current guards reject overly long sources, backreferences, multiple unbounded
+ * quantifiers, large or excessive bounded quantifiers, and quantified groups whose subtree
+ * contains a quantifier or alternation.
+ * When any RegExp filter is configured, paths longer than the SDK's RegExp input guard are skipped
+ * instead of being fed to the JavaScript RegExp engine. This is fail-closed for deny-lists: an
+ * untestable long path is not allowed through an exclude RegExp filter.
+ */
+export type SyncFilterPattern = string | RegExp;
+/**
+ * Include/exclude filters applied to sync paths relative to each folder root.
+ *
+ * `SyncOptions.include` and `SyncOptions.exclude` are the canonical filters for
+ * {@link synchronize}; they are passed down into folder scans and then enforced again during
+ * pairing as the SDK policy boundary. Calling
+ * {@link SyncFolder.scan} directly can pass the same filter object for standalone scans.
+ */
+export interface SyncFilterOptions {
+    /**
+     * Optional allow-list. When present, only paths matching at least one pattern are scanned.
+     * B2 scans can push down only the safe literal prefix from slash-containing glob includes;
+     * other include filtering is client-side.
+     */
+    readonly include?: readonly SyncFilterPattern[];
+    /**
+     * Optional deny-list. Paths matching any exclude pattern are skipped even when they also match
+     * an include pattern. Excludes are client-side filters; they do not reduce B2 list API calls or
+     * the B2 scanner's version grouping and sort memory.
+     */
+    readonly exclude?: readonly SyncFilterPattern[];
+}
+/**
+ * Options accepted by {@link SyncFolder.scan}. Includes filters plus an optional scan-level
+ * callback for paths the scanner cannot safely represent or test.
+ */
+export interface SyncScanOptions extends SyncFilterOptions {
+    /**
+     * Optional signal checked by built-in scanners while enumerating. Aborting stops local traversal
+     * promptly and stops B2 scans before requesting the next page.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Receives scan diagnostics. Built-in scanners may continue after recoverable per-path
+     * diagnostics, such as unreadable local children, but fatal scan failures still abort.
+     */
+    readonly onError?: (event: SyncErrorEvent) => void;
+    /**
+     * Receives scanner skip diagnostics. Built-in scans isolate callback errors so diagnostics
+     * handlers cannot abort the scan.
+     */
+    readonly onSkip?: (event: SyncSkipEvent) => void;
+    /**
+     * When true, B2 scanners skip names that cannot be written safely to a local filesystem
+     * destination and reject case/Unicode-canonical local path collisions.
+     */
+    readonly requireLocalSafePaths?: boolean;
+    /**
+     * Maximum number of entries a scanner may retain before failing with a defined error instead of
+     * continuing toward unbounded heap growth. Defaults to the SDK scan limit.
+     */
+    readonly maxScanEntries?: number;
+}
 /** Common metadata for a file discovered during a folder scan. */
 export interface SyncPath {
     /** Path relative to the sync folder root, using forward slashes. */
@@ -14,11 +100,51 @@ export interface SyncPath {
     readonly modTimeMillis: number;
     /** File size in bytes. */
     readonly size: number;
+    /**
+     * SHA-1 checksum state for compare modes that need content hashes.
+     *
+     * - `undefined`: not computed yet; the synchronizer may hash local files before comparing.
+     * - `null`: known to be unavailable; `sha1` sync skips the pair with a surfaced event.
+     * - 40-character hex string: known verifiable digest.
+     * - other string: untrusted provider metadata such as B2's `unverified:<hex>` sentinel;
+     *   consumers must not treat it as proof that bytes match. The `sha1` synchronizer must
+     *   verify untrusted B2 bytes before using them for equality, or transfer conservatively.
+     *
+     * Use `parseSyncContentSha1`, `selectB2ComparableSha1`, and `untrustedSha1` from the sync
+     * entrypoint to construct or inspect this field without depending on sentinel strings.
+     */
+    readonly contentSha1?: string | null;
+    /**
+     * Explicit SHA-1 trust and availability state. Prefer this field for custom
+     * scanners that can distinguish verified digests from untrusted provider
+     * metadata without relying on `contentSha1` sentinel strings. When omitted,
+     * the synchronizer derives the state from `contentSha1` for compatibility.
+     */
+    readonly contentSha1State?: SyncSha1State;
+}
+/** Filesystem identity captured while scanning a local file. */
+export interface LocalFileIdentity {
+    /** Device ID from the local filesystem. */
+    readonly deviceId: number;
+    /** Inode number from the local filesystem. */
+    readonly inode: number;
+    /** Size observed during the scan. */
+    readonly size: number;
+    /** Modification time observed during the scan, floored to milliseconds. */
+    readonly modTimeMillis: number;
+    /**
+     * Node `Stats.ctimeMs` observed during the scan, floored to milliseconds.
+     * This is inode-change time on POSIX and may be creation time on Windows.
+     * Built-in local scans populate this; custom scanners may omit it.
+     */
+    readonly changeTimeMillis?: number;
 }
 /** A file on the local filesystem discovered during a scan. */
 export interface LocalSyncPath extends SyncPath {
     /** Absolute filesystem path to the file. */
     readonly absolutePath: string;
+    /** Optional filesystem identity used to reject scan-to-read races. */
+    readonly fileIdentity?: LocalFileIdentity;
 }
 /** A file in a B2 bucket discovered during a scan. */
 export interface B2SyncPath extends SyncPath {
@@ -30,13 +156,15 @@ export interface B2SyncPath extends SyncPath {
 /** Discriminated event types emitted during synchronization. */
 export type SyncEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'skip' | 'error' | 'compare';
 /**
- * Action event types: per-file outcomes (transfer / metadata change /
- * skip) that always carry a `path` and a `size`. These never carry a
- * `message` because the type tag already says what happened.
+ * Action event types: per-file transfer or metadata-change outcomes that
+ * always carry a `path` and a `size`. Skips are reported separately as
+ * {@link SyncSkipEvent} because they carry a diagnostic `message`.
  */
-export type SyncActionEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local' | 'compare';
+export type SyncActionEventType = 'upload-start' | 'upload-done' | 'download-start' | 'download-done' | 'copy-start' | 'copy-done' | 'hide' | 'delete-remote' | 'delete-local';
+/** Machine-readable reasons emitted with scanner and diagnostic skip events. */
+export type SyncSkipReason = 'outside-prefix' | 'unsafe-name' | 'local-unsafe-name' | 'relative-path-collision' | 'local-path-collision' | 'filesystem-error' | 'path-too-long-for-regexp' | 'scan-skip-overflow' | 'stale-download-partial';
 /**
- * Per-action progress event (transfer, metadata change, comparison). All
+ * Per-action progress event (transfer or metadata change). All
  * action-event variants share the same shape; the `type` tag distinguishes
  * them.
  */
@@ -45,9 +173,22 @@ export interface SyncActionEvent {
     readonly type: SyncActionEventType;
     /** Relative path of the file this event concerns. */
     readonly path: string;
-    /** Size in bytes of the file involved, or 0 for metadata-only events. */
+    /** Size in bytes of the file involved, or `0` for metadata-only actions. */
     readonly size: number;
 }
+/** Per-file comparison progress event. */
+export interface SyncCompareEvent {
+    /** Discriminant tag (always the literal string `'compare'`). */
+    readonly type: 'compare';
+    /** Relative path of the compared file. */
+    readonly path: string;
+    /** Reserved for compatibility with earlier metadata-only compare events. */
+    readonly size: 0;
+    /** Local file bytes hashed while preparing this comparison, if any. */
+    readonly bytesHashed?: number;
+    /** B2 bytes downloaded and hashed while verifying untrusted SHA-1 metadata, if any. */
+    readonly bytesVerified?: number;
+}
 /**
  * `skip` event — a destination-only file that policy decided to keep, or
  * a same-on-both file that didn't need transfer. Always carries a
@@ -56,12 +197,16 @@ export interface SyncActionEvent {
 export interface SyncSkipEvent {
     /** Discriminant tag (always the literal string `'skip'`). */
     readonly type: 'skip';
-    /** Relative path of the skipped file. */
+    /** Relative path of the skipped file, or the raw B2 key when no safe relative path exists. */
     readonly path: string;
     /** Size in bytes of the file involved, always 0 for skip events. */
     readonly size: number;
     /** Human-readable reason for skipping this file. */
     readonly message: string;
+    /** Machine-readable skip reason when emitted by a scanner or diagnostic buffer. */
+    readonly reason?: SyncSkipReason;
+    /** Original B2 key when the skip came from a B2 scan. */
+    readonly b2FileName?: string;
 }
 /**
  * `error` event — an action threw or the engine encountered a fatal
@@ -77,6 +222,12 @@ export interface SyncErrorEvent {
     readonly size: number;
     /** Human-readable error message; never empty. */
     readonly message: string;
+    /** Number of failed actions represented by an aggregate run-level error event. */
+    readonly failureCount?: number;
+    /** Bounded distinct relative paths of failed actions represented by an aggregate error event. */
+    readonly failedPaths?: readonly string[];
+    /** Number of failed action paths omitted from a bounded aggregate error event. */
+    readonly failedPathOmittedCount?: number;
 }
 /**
  * An event emitted by the sync engine to report progress, skip
@@ -84,23 +235,45 @@ export interface SyncErrorEvent {
  * `case 'error':` (or `'skip':`) to narrow into a variant with `message`
  * guaranteed non-optional.
  */
-export type SyncEvent = SyncActionEvent | SyncSkipEvent | SyncErrorEvent;
+export type SyncEvent = SyncActionEvent | SyncCompareEvent | SyncSkipEvent | SyncErrorEvent;
 /** Configuration options for a sync operation. */
-export interface SyncOptions {
+export interface SyncOptions extends SyncFilterOptions {
     /** How to decide whether two files differ. */
     readonly compareMode: CompareMode;
     /** What to do with destination files absent from the source. */
     readonly keepMode: KeepMode;
     /** Number of days to retain orphaned destination files when keepMode is 'keep-days'. */
     readonly keepDays?: number;
-    /** Maximum number of concurrent transfer actions. Defaults to 4. */
+    /** Maximum number of concurrent transfer actions. Must be a positive integer. Defaults to 4. */
     readonly concurrency?: number;
     /** When true, actions are generated but not executed. */
     readonly dryRun?: boolean;
     /** Tolerance for comparison (bytes for size, milliseconds for modtime). */
     readonly compareThreshold?: number;
-    /** Signal to abort the sync operation. */
+    /** Signal to abort the sync operation, including scans and in-progress SHA-1 reads. */
     readonly signal?: AbortSignal;
+    /** Optional idle/no-progress timeout in milliseconds for SHA-1 reads in `sha1` mode. */
+    readonly sha1ReadTimeoutMillis?: number;
+    /**
+     * Optional absolute deadline in milliseconds for untrusted B2 SHA-1 verification reads.
+     * Objects that cannot be fully verified before this deadline are skipped for that run.
+     */
+    readonly sha1VerificationTimeoutMillis?: number;
+    /**
+     * Optional per-file byte ceiling for untrusted B2 SHA-1 verification reads.
+     *
+     * By default, verifying untrusted B2 metadata may download the selected version's full
+     * `contentLength` each run. Set this to a lower value to skip objects above the per-file
+     * budget before they can be treated as equal.
+     */
+    readonly sha1VerificationMaxBytes?: number;
+    /**
+     * Idle timeout in milliseconds for B2-to-local download body reads. Must be positive, or
+     * `Infinity` to disable the timeout. Defaults to 60 seconds.
+     */
+    readonly downloadIdleTimeoutMillis?: number;
+    /** Maximum scanner entries retained before failing with a defined scan-limit error. */
+    readonly maxScanEntries?: number;
     /** Optional provider for per-file encryption settings. */
     readonly encryptionProvider?: SyncEncryptionProvider;
 }
@@ -111,11 +284,30 @@ export interface SyncEncryptionProvider {
     /** Returns the encryption setting to use when downloading a file, or undefined for default. */
     getSettingForDownload(fileVersion: FileVersion): EncryptionSetting | undefined;
 }
-/** A scannable folder (local or B2) that yields files in sorted order. */
+/**
+ * A scannable folder (local or B2) that yields files relative to its sync root.
+ *
+ * Built-in scanners currently sort before yielding. Large local trees or B2 prefixes may therefore
+ * require memory proportional to the scanned entries; B2 scans also group listed versions before
+ * yielding. For B2, `maxScanEntries` counts every listed file version before prefix, safety, and
+ * filter checks, and exclude filters or non-literal includes do not bound B2 listing calls.
+ */
 export interface SyncFolder {
     /** Whether this folder is local or in B2. */
     readonly type: 'local' | 'b2';
-    /** Scans the folder and yields files sorted by relative path. */
-    scan(): AsyncIterable<SyncPath>;
+    /**
+     * True when `scan(filters)` already enforces include/exclude filters itself as an optimization.
+     * The synchronizer still reapplies filters after custom scanner output as the SDK policy
+     * boundary. Custom folders that set this should use the exported filter helpers from
+     * `@backblaze-labs/b2-sdk/sync` to stay aligned with the SDK glob and RegExp dialect.
+     */
+    readonly appliesScanFilters?: true;
+    /**
+     * True when `scan(filters)` already yields entries in `compareSyncRelativePaths` order.
+     * Custom folders that omit this are sorted by `synchronize()` before pairing.
+     */
+    readonly appliesScanSorting?: true;
+    /** Scans the folder and yields files relative to the folder root. */
+    scan(options?: SyncScanOptions): AsyncIterable<SyncPath>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.js"],"names":[],"mappings":"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"}