pinokiod 8.0.50 → 8.0.53

package/kernel/vault/index.js

@@ -1,26 +1,37 @@
-const fs = require('fs')
-const path = require('path')
-const crypto = require('crypto')
-const { Worker } = require('worker_threads')
-const Registry = require('./registry')
-const Sweeper = require('./sweeper')
-const { walkBatches, statMany } = require('./walker')
-const { fileSnapshot, sameSnapshot, sameContentState } = require('./snapshot')
+const fs = require("fs")
+const path = require("path")
+const crypto = require("crypto")
+const { execFile } = require("child_process")
+const { Worker } = require("worker_threads")
+const Registry = require("./registry")
+const Sweeper = require("./sweeper")
+const { fileSnapshot, sameSnapshot, sameContentState } = require("./snapshot")
 const {
-  SIZE_THRESHOLD, CANDIDATE_SIZE_OPTIONS, TMP_SUFFIX, SHA256_RE,
-  DIR_CONCURRENCY, STAT_CONCURRENCY, HASH_INACTIVITY_MS
-} = require('./constants')
+  SIZE_THRESHOLD,
+  CANDIDATE_SIZE_OPTIONS,
+  TMP_SUFFIX,
+  SHA256_RE,
+  DIR_CONCURRENCY,
+  STAT_CONCURRENCY,
+  HASH_INACTIVITY_MS
+} = require("./constants")
 
-// Shared model store engine (spec/requirements/shared-model-store.md).
-// Store + registry + volume probe + hashing + adopt/convert/verify, plus the
-// user-facing operations behind the vault dashboard (detach, undo, reclaim).
-// Nothing here runs automatically except startup verify; discovery happens
-// only through the user's manual scan.
-
-const NO_LINK_CODES = new Set(["EXDEV", "ENOTSUP", "ENOSYS"])
+const NO_LINK_CODES = new Set([
+  "EXDEV", "ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EPERM", "EACCES"
+])
 const LOCK_CODES = new Set(["EBUSY", "EPERM", "EACCES"])
-const isMissingError = (error) => !!(error && (error.code === "ENOENT" || error.code === "ENOTDIR"))
-const isAccessError = (error) => !!(error && (error.code === "EACCES" || error.code === "EPERM"))
+const STATUS_PAGE_SIZE = 500
+const MAX_BULK_FILE_ACTIONS = 500
+const STATUS_VIEWS = new Set([
+  "all", "duplicates", "shared", "tracked", "reclaimable", "activity"
+])
+const STATUS_FILTERS = new Set([
+  "all", "duplicate", "shared", "tracked"
+])
+
+const isMissingError = (error) => !!(error &&
+  (error.code === "ENOENT" || error.code === "ENOTDIR"))
+
 const lstatIfPresent = async (filePath) => {
   try {
     return await fs.promises.lstat(filePath)
@@ -29,9 +40,11 @@ const lstatIfPresent = async (filePath) => {
     throw error
   }
 }
+
 const sameIdentity = (left, right) => !!(
   left && right && left.dev === right.dev && left.ino === right.ino
 )
+
 const unlinkIfSame = async (filePath, expected) => {
   if (!expected) return false
   const current = await lstatIfPresent(filePath)
@@ -44,41 +57,92 @@ const unlinkIfSame = async (filePath, expected) => {
     throw error
   }
 }
+
 const unsafeStoragePath = (filePath) => {
   const error = new Error(`Storage path is not a real directory: ${filePath}`)
   error.code = "EVAULTPATH"
   return error
 }
 
+const unavailableStorage = (message) => {
+  const error = new Error(message)
+  error.code = "EVAULTUNAVAILABLE"
+  return error
+}
+
 const isPathWithin = (root, target) => {
-  const rel = path.relative(path.resolve(root), path.resolve(target))
-  return rel === "" || (!rel.startsWith(`..${path.sep}`) && rel !== ".." && !path.isAbsolute(rel))
+  const relative = path.relative(path.resolve(root), path.resolve(target))
+  return relative === "" || (
+    !relative.startsWith(`..${path.sep}`) &&
+    relative !== ".." &&
+    !path.isAbsolute(relative)
+  )
 }
 
 const samePath = (left, right) => {
-  const a = path.resolve(left)
-  const b = path.resolve(right)
-  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b
+  const first = path.resolve(left)
+  const second = path.resolve(right)
+  return process.platform === "win32"
+    ? first.toLowerCase() === second.toLowerCase()
+    : first === second
 }
 
 const sameFileMetadata = (left, right) => {
   if (!left || !right) return false
   if ((left.mode & 0o7777) !== (right.mode & 0o7777)) return false
-  if (left.uid !== undefined && right.uid !== undefined && left.uid !== right.uid) return false
-  if (left.gid !== undefined && right.gid !== undefined && left.gid !== right.gid) return false
+  if (left.uid !== undefined && right.uid !== undefined &&
+      left.uid !== right.uid) return false
+  if (left.gid !== undefined && right.gid !== undefined &&
+      left.gid !== right.gid) return false
   return true
 }
 
 const sourceId = (kind, name) => `${kind}:${encodeURIComponent(name)}`
+const boundedInteger = (value, fallback, minimum, maximum) => {
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed)) return fallback
+  return Math.max(minimum, Math.min(maximum, parsed))
+}
+const rowSnapshot = (row) => ({
+  size: row.size,
+  mtime: row.mtime,
+  ctime: row.ctime,
+  dev: row.dev,
+  ino: row.ino
+})
+
+const revealInFileManager = (filePath, platform = process.platform) =>
+  new Promise((resolve, reject) => {
+    const command = platform === "darwin"
+      ? "open"
+      : platform === "win32"
+        ? "explorer.exe"
+        : "xdg-open"
+    const args = platform === "darwin"
+      ? ["-R", filePath]
+      : platform === "win32"
+        ? [`/select,${filePath}`]
+        : [path.dirname(filePath)]
+    execFile(command, args, {
+      timeout: 10000,
+      windowsHide: true
+    }, (error) => error ? reject(error) : resolve())
+  })
 
 class Vault {
   constructor(kernel) {
     this.kernel = kernel
+    this.fileManagerLauncher = (filePath) =>
+      revealInFileManager(
+        filePath,
+        this.kernel.platform || process.platform
+      )
     this.enabled = false
     this.initialized = false
-    this.mode = null          // 'link' | 'copy' for the vault's own volume
-    this.volumeModes = new Map()  // dev -> 'link' | 'copy'
+    this.mode = null
+    this.volumeModes = new Map()
     this.registry = null
+    this.sweeper = null
     this.worker = null
     this.workerJobs = new Map()
     this.workerSeq = 0
@@ -89,597 +153,575 @@ class Vault {
     this.dirConcurrency = DIR_CONCURRENCY
     this.sizeThreshold = SIZE_THRESHOLD
     this._sources = []
+    this._sourcesById = new Map()
     this._sourceBases = new Map()
+    this._anchorStores = []
+    this._anchorStoresById = new Map()
+    this._anchorStoresByDevice = new Map()
+    this._fallbackConfig = null
     this.operationTail = Promise.resolve()
     this.initializationPromise = null
-    this.verificationPending = false
+    this.scanPromise = null
     this.scanError = null
     this.scanScopeId = null
+    this.scanCancelRequested = false
+    this.lastScanCache = new Map()
     this.fileActionProgress = null
+    this.fileActionCancelRequested = false
   }
+
   get root() {
     return path.resolve(this.kernel.homedir, "vault")
   }
+
   get blobRoot() {
-    return path.resolve(this.root, "sha256")
+    const store = this.defaultAnchorStore()
+    return store
+      ? path.resolve(store.root, "sha256")
+      : path.resolve(this.globalConfigRoot(), "vault", "sha256")
   }
-  get sourceRoot() {
-    return path.resolve(this.root, "sources")
-  }
-  storePathFor(hash) {
+
+  storePathFor(hash, storeId = null) {
     if (typeof hash !== "string" || !SHA256_RE.test(hash)) {
       throw new TypeError("Invalid vault content identifier.")
     }
-    return path.resolve(this.blobRoot, hash.slice(0, 2), hash)
+    const store = storeId
+      ? this._anchorStoresById.get(storeId)
+      : this.defaultAnchorStore()
+    if (!store) throw new Error("No anchor store is configured.")
+    return path.resolve(
+      store.root, "sha256", hash.slice(0, 2), hash)
+  }
+
+  globalConfigRoot() {
+    return this.kernel.store && typeof this.kernel.store.root === "string"
+      ? path.resolve(this.kernel.store.root)
+      : path.resolve(this.kernel.homedir, ".pinokio")
+  }
+
+  readConfig() {
+    const stored = this.kernel.store &&
+      typeof this.kernel.store.get === "function"
+      ? this.kernel.store.get("vault")
+      : this._fallbackConfig
+    const config = stored && typeof stored === "object" ? stored : {}
+    return {
+      locations: Array.isArray(config.locations)
+        ? config.locations.filter((item) => typeof item === "string")
+        : [],
+      anchor_stores: Array.isArray(config.anchor_stores)
+        ? config.anchor_stores.filter((item) =>
+          item &&
+          typeof item === "object" &&
+          typeof item.id === "string" &&
+          item.id &&
+          typeof item.root === "string" &&
+          typeof item.probe_path === "string")
+        : []
+    }
+  }
+
+  writeConfig(config) {
+    const value = {
+      locations: [...new Set((config.locations || [])
+        .filter((item) => typeof item === "string")
+        .map((item) => path.resolve(item)))],
+      anchor_stores: (config.anchor_stores || []).map((store) => ({
+        id: store.id,
+        root: path.resolve(store.root),
+        probe_path: path.resolve(store.probe_path)
+      }))
+    }
+    if (this.kernel.store && typeof this.kernel.store.set === "function") {
+      this.kernel.store.set("vault", value)
+    } else {
+      this._fallbackConfig = value
+    }
+    return value
+  }
+
+  configuredLocations() {
+    return this.readConfig().locations
+  }
+
+  defaultAnchorStore() {
+    const home = path.resolve(this.kernel.homedir)
+    return this._anchorStores.find((store) =>
+      store.available && isPathWithin(store.probe_path, home)) ||
+      this._anchorStores[0] ||
+      null
   }
+
   async directoryIfSafe(directory) {
-    const st = await lstatIfPresent(directory)
-    if (st && !st.isDirectory()) throw unsafeStoragePath(directory)
-    return st
+    const stat = await lstatIfPresent(directory)
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
+      throw unsafeStoragePath(directory)
+    }
+    return stat
   }
+
   async ensureDirectory(directory) {
-    let st = await this.directoryIfSafe(directory)
-    if (st) return st
+    let stat = await this.directoryIfSafe(directory)
+    if (stat) return stat
     try {
-      await fs.promises.mkdir(directory)
+      await fs.promises.mkdir(directory, { mode: 0o700 })
     } catch (error) {
       if (!error || error.code !== "EEXIST") throw error
     }
-    st = await this.directoryIfSafe(directory)
-    if (!st) throw unsafeStoragePath(directory)
-    return st
+    stat = await this.directoryIfSafe(directory)
+    if (!stat) throw unsafeStoragePath(directory)
+    return stat
   }
+
   async storeStatIfPresent(storePath, options = {}) {
-    if (!isPathWithin(this.blobRoot, storePath)) throw unsafeStoragePath(storePath)
-    if (!await this.directoryIfSafe(this.root) || !await this.directoryIfSafe(this.blobRoot)) {
-      throw unsafeStoragePath(this.blobRoot)
+    const store = options.store_id
+      ? this._anchorStoresById.get(options.store_id)
+      : this._anchorStores.find((candidate) =>
+        isPathWithin(path.resolve(candidate.root, "sha256"), storePath))
+    if (!store) {
+      throw unsafeStoragePath(storePath)
+    }
+    const blobRoot = path.resolve(store.root, "sha256")
+    if (!isPathWithin(blobRoot, storePath)) {
+      throw unsafeStoragePath(storePath)
+    }
+    if (options.createParent) {
+      await this.ensureAnchorStore(store, options.dev)
+    }
+    if (!await this.directoryIfSafe(store.root) ||
+        !await this.directoryIfSafe(blobRoot)) {
+      return null
     }
     const shard = path.dirname(storePath)
     let shardStat = await this.directoryIfSafe(shard)
-    if (!shardStat && options.createParent) shardStat = await this.ensureDirectory(shard)
+    if (!shardStat && options.createParent) {
+      shardStat = await this.ensureDirectory(shard)
+    }
     if (!shardStat) return null
-    return lstatIfPresent(storePath)
+    const stat = await lstatIfPresent(storePath)
+    if (stat && (!stat.isFile() || stat.isSymbolicLink())) {
+      throw unsafeStoragePath(storePath)
+    }
+    return stat
+  }
+
+  async ensureAnchorStore(store, expectedDev = null) {
+    if (!store) throw new Error("No anchor store is configured.")
+    const managementParent = path.dirname(store.root)
+    const parentStat = await lstatIfPresent(managementParent)
+    if (!parentStat) {
+      await fs.promises.mkdir(managementParent, {
+        recursive: true,
+        mode: 0o700
+      })
+    } else if (!parentStat.isDirectory() || parentStat.isSymbolicLink()) {
+      throw unsafeStoragePath(managementParent)
+    }
+    await this.ensureDirectory(store.root)
+    const markerPath = path.resolve(store.root, "store.json")
+    const markerStat = await lstatIfPresent(markerPath)
+    if (markerStat && (!markerStat.isFile() || markerStat.isSymbolicLink())) {
+      throw unsafeStoragePath(markerPath)
+    }
+    if (markerStat) {
+      let marker
+      try {
+        marker = JSON.parse(await fs.promises.readFile(markerPath, "utf8"))
+      } catch (error) {
+        throw unsafeStoragePath(markerPath)
+      }
+      if (!marker || marker.id !== store.id || marker.version !== 1) {
+        throw unsafeStoragePath(markerPath)
+      }
+    } else {
+      await fs.promises.writeFile(
+        markerPath,
+        `${JSON.stringify({ id: store.id, version: 1 }, null, 2)}\n`,
+        { flag: "wx", mode: 0o600 }
+      )
+    }
+    const rootStat = await fs.promises.stat(store.root)
+    if (expectedDev !== null && rootStat.dev !== expectedDev) {
+      throw unavailableStorage(
+        "The configured anchor store is on a different filesystem.")
+    }
+    const mode = await this.probe(store.root)
+    store.available = true
+    store.dev = rootStat.dev
+    store.mode = mode
+    this._anchorStoresByDevice.set(rootStat.dev, store)
+    if (mode !== "link") {
+      throw unavailableStorage(
+        "This filesystem does not support hardlinks.")
+    }
+    await this.ensureDirectory(path.resolve(store.root, "sha256"))
+    return store
+  }
+
+  async validateAnchorStore(store, expectedDev = null) {
+    if (!store) throw new Error("No anchor store is configured.")
+    const markerPath = path.resolve(store.root, "store.json")
+    const [rootStat, markerStat] = await Promise.all([
+      this.directoryIfSafe(store.root),
+      lstatIfPresent(markerPath)
+    ])
+    if (!rootStat ||
+        !markerStat ||
+        !markerStat.isFile() ||
+        markerStat.isSymbolicLink()) {
+      throw unsafeStoragePath(store.root)
+    }
+    let marker
+    try {
+      marker = JSON.parse(await fs.promises.readFile(markerPath, "utf8"))
+    } catch (error) {
+      throw unsafeStoragePath(markerPath)
+    }
+    if (!marker || marker.id !== store.id || marker.version !== 1) {
+      throw unsafeStoragePath(markerPath)
+    }
+    const current = await fs.promises.stat(store.root)
+    if (expectedDev !== null && current.dev !== expectedDev) {
+      throw unavailableStorage(
+        "The configured anchor store is on a different filesystem.")
+    }
+    store.available = true
+    store.dev = current.dev
+    return current
   }
-  // All dashboard mutations share one queue. Status reads remain concurrent,
-  // while scans, conversions, repair, undo, detach, and reclaim can never
-  // publish interleaved filesystem/registry state.
+
   runExclusive(operation) {
     const pending = this.operationTail.then(operation, operation)
     this.operationTail = pending.catch(() => {})
     return pending
   }
-  // A filesystem mutation is committed before its registry snapshot is
-  // flushed. Keep that distinction in the response: failed persistence is
-  // retried by Registry and must not make an already-completed action look as
-  // though it never happened.
+
   runMutation(operation) {
-    return this.runExclusive(async () => {
-      const result = await operation()
-      try {
-        if (this.registry) await this.registry.flush()
-      } catch (error) {
-        return Object.assign({}, result, { persistence_warning: true })
-      }
-      return result
-    })
+    return this.runExclusive(operation)
   }
+
   async runFileAction(progress, operation) {
+    this.fileActionCancelRequested = false
     this.fileActionProgress = progress
     try {
       return await operation(progress)
     } finally {
-      if (this.fileActionProgress === progress) this.fileActionProgress = null
+      if (this.fileActionProgress === progress) {
+        this.fileActionProgress = null
+      }
+      this.fileActionCancelRequested = false
     }
   }
-  startScan(scopeId = null, sizeThreshold = this.sizeThreshold) {
-    if (!this.enabled || !this.sweeper) return { started: false, disabled: true }
-    if (this.scanPromise) return { started: false, already_running: true }
-    this.sizeThreshold = sizeThreshold
-    this.scanError = null
-    this.scanScopeId = scopeId
-    this.scanPromise = this.runExclusive(() => this.sweeper.scan(scopeId))
-      .catch((error) => {
-        this.scanError = error && error.message ? error.message : String(error)
-        throw error
-      })
-      .finally(() => {
-        this.scanPromise = null
-        this.scanScopeId = null
-      })
-    this.scanPromise.catch(() => {})
-    return { started: true }
+
+  cancelFileAction() {
+    if (!this.fileActionProgress ||
+        !this.fileActionProgress.cancelable) {
+      return { cancel_requested: false }
+    }
+    this.fileActionCancelRequested = true
+    this.fileActionProgress.cancel_requested = true
+    return { cancel_requested: true }
   }
-  async perform(action, payload = {}) {
-    if (!this.enabled) return { error: "Save space is disabled." }
-    await this.ensureInitialized()
-    switch (action) {
-      case "add_source": {
-        const result = await this.runExclusive(() => this.addExternalSource(payload.path))
-        return {
-          created: result.created,
-          source: {
-            id: result.source.id,
-            label: result.source.label,
-            target_path: result.source.root,
-            shareable: !!result.source.shareable
-          }
-        }
-      }
-      case "scan": {
-        if (payload.scope_id && !this.scanSource(payload.scope_id)) {
-          return { error: "That scan location is no longer available." }
-        }
-        let sizeThreshold = this.sizeThreshold
-        if (payload.candidate_size != null) {
-          if (!CANDIDATE_SIZE_OPTIONS.includes(payload.candidate_size)) {
-            return { error: "Choose a valid minimum file size." }
-          }
-          sizeThreshold = payload.candidate_size
+
+  async isEnabled() {
+    let value = process.env.PINOKIO_VAULT
+    if (value === undefined && this.kernel.homedir) {
+      try {
+        const raw = await fs.promises.readFile(
+          path.resolve(this.kernel.homedir, "ENVIRONMENT"), "utf8")
+        for (const line of raw.split("\n")) {
+          const match = line.match(/^\s*PINOKIO_VAULT\s*=\s*(.*)\s*$/)
+          if (match) value = match[1].trim()
         }
-        return this.startScan(payload.scope_id || null, sizeThreshold)
+      } catch (error) {
+        if (!isMissingError(error)) throw error
       }
-      case "deduplicate":
-        if (typeof payload.path === "string" && payload.path) {
-          return this.runMutation(() => this.runFileAction({
-            kind: "deduplicate-file",
-            path: path.resolve(payload.path)
-          }, () => this.deduplicateFile(payload.path, {
-            batch_id: `batch-${crypto.randomUUID()}`
-          })))
-        }
-        const selection = payload.selection || null
-        if (selection && selection !== "duplicates" && selection !== "kept-separate") {
-          return { error: "Choose files to deduplicate." }
-        }
-        if (payload.scope_id != null &&
-            (typeof payload.scope_id !== "string" || !payload.scope_id)) {
-          return { error: "Choose a valid location to deduplicate." }
-        }
-        const scopeId = typeof payload.scope_id === "string" && payload.scope_id
-          ? payload.scope_id
-          : null
-        if (!selection && !scopeId) {
-          return { error: "Choose a location to deduplicate." }
-        }
-        return this.runMutation(() => this.runFileAction({
-          kind: "deduplicate",
-          scope_id: scopeId,
-          selection: selection || "duplicates",
-          files_total: 0,
-          files_completed: 0
-        }, async (progress) => {
-          const options = {
-            batch_id: `batch-${crypto.randomUUID()}`,
-            progress
-          }
-          return selection
-            ? this.deduplicateSelection(selection, scopeId, options)
-            : this.deduplicateScope(scopeId, options)
-        }))
-      case "reclaim":
-        return this.runMutation(() => this.reclaim(payload.hash))
-      case "reclaim_all":
-        return this.runMutation(() => this.reclaimAll())
-      case "repair":
-      case "rebuild":
-        if (this.scanPromise || (this.sweeper && this.sweeper.state.active)) {
-          return { error: "Wait for the current scan to finish before repairing the index." }
-        }
-        return this.runMutation(async () => {
-          await this.rebuild(undefined, { flush: false })
-          return { done: true }
-        })
-      case "undo":
-        return this.runMutation(() => this.undoBatch(payload.batch_id))
-      case "detach":
-        if (typeof payload.path !== "string" || !payload.path) return { status: "not-found" }
-        return this.runMutation(() => {
-          const targetPath = path.resolve(payload.path)
-          const kind = this.registry.duplicates.has(targetPath)
-            ? "keep-separate"
-            : "make-separate"
-          return this.runFileAction({ kind, path: targetPath }, () => this.detach(targetPath))
-        })
-      default:
-        return { error: "unknown action" }
     }
+    return String(value).toLowerCase() !== "false"
   }
-  async refreshSources() {
-    const home = path.resolve(this.kernel.homedir)
-    const apiRoot = path.resolve(home, "api")
-    const sources = [
-      { id: "pinokio", kind: "pinokio", label: "Pinokio", root: home, parent_id: null },
-      { id: "apps", kind: "virtual", label: "Apps", root: apiRoot, parent_id: "pinokio" },
-      { id: "external", kind: "virtual", label: "External folders", root: null, parent_id: null }
-    ]
-    let storeDev = null
+
+  async init(options = {}) {
+    this.enabled = await this.isEnabled()
+    if (!this.enabled) return { enabled: false }
+    if (options.deferStorage) return { enabled: true }
+    return this.initializeStorage()
+  }
+
+  async initializeStorage() {
+    if (this.initialized) return { enabled: true, mode: this.mode }
+    await this.ensureDirectory(this.root)
+    this.registry = new Registry(this.root)
+    await this.registry.load()
+    await this.importLegacyLocationConfig()
+    await this.refreshAnchorStores()
+    await this.migrateLegacyAnchorStore()
+    this.mode = this.defaultAnchorStore() &&
+      this.defaultAnchorStore().mode === "copy"
+      ? "copy"
+      : "link"
+    await this.refreshSources()
+    this.sweeper = new Sweeper(this)
+    this.initialized = true
+    return { enabled: true, mode: this.mode }
+  }
+
+  async ensureInitialized() {
+    if (!this.enabled) return { enabled: false }
+    if (this.initialized) return { enabled: true, mode: this.mode }
+    if (!this.initializationPromise) {
+      this.initializationPromise = this.initializeStorage().finally(() => {
+        this.initializationPromise = null
+      })
+    }
+    return this.initializationPromise
+  }
+
+  async openWorkspace() {
+    if (!this.initialized) return this.ensureInitialized()
+    await this.refreshAnchorStores()
+    await this.refreshSources()
+    return { enabled: true, mode: this.mode }
+  }
+
+  async importLegacyLocationConfig() {
+    const config = this.readConfig()
+    const legacy = await this.registry.externalSources()
+    const locations = [...new Set([
+      ...config.locations.map((item) => path.resolve(item)),
+      ...legacy.map((item) => path.resolve(item))
+    ])]
+    if (locations.length !== config.locations.length ||
+        locations.some((item, index) =>
+          item !== path.resolve(config.locations[index] || ""))) {
+      this.writeConfig(Object.assign({}, config, { locations }))
+    }
+  }
+
+  async migrateLegacyAnchorStore() {
+    const legacyRoot = path.resolve(this.root, "sha256")
+    const legacyStat = await lstatIfPresent(legacyRoot)
+    if (!legacyStat) return false
+    if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) {
+      throw unsafeStoragePath(legacyRoot)
+    }
+    if (!(await fs.promises.readdir(legacyRoot)).length) {
+      await fs.promises.rmdir(legacyRoot)
+      return true
+    }
+    const store = this.anchorStoreForDevice(legacyStat.dev)
+    if (!store) {
+      throw unavailableStorage(
+        "The legacy anchor store has no configured store on its filesystem.")
+    }
+    const targetRoot = path.resolve(store.root, "sha256")
+    if (samePath(legacyRoot, targetRoot)) return false
+
+    await this.ensureAnchorStore(store, legacyStat.dev)
+    const targetEntries = await fs.promises.readdir(targetRoot)
+    if (targetEntries.length) {
+      throw unavailableStorage(
+        "Both the legacy and configured anchor stores contain files.")
+    }
+    await fs.promises.rmdir(targetRoot)
     try {
-      storeDev = (await fs.promises.stat(this.root)).dev
+      await fs.promises.rename(legacyRoot, targetRoot)
     } catch (error) {
-      if (!isMissingError(error)) throw error
+      await this.ensureDirectory(targetRoot).catch(() => {})
+      throw error
     }
-    const decorate = async (source) => {
-      if (!source.root) return source
+    return true
+  }
+
+  async refreshAnchorStores() {
+    let config = this.readConfig()
+    const candidates = [
+      {
+        probe_path: path.resolve(this.kernel.homedir),
+        preferred_root: path.resolve(this.globalConfigRoot(), "vault"),
+        home: true
+      },
+      ...config.locations.map((location) => ({
+        probe_path: path.resolve(location),
+        home: false
+      }))
+    ]
+    const configured = []
+    for (const entry of config.anchor_stores) {
+      if (typeof entry.id !== "string" ||
+          !entry.id ||
+          typeof entry.root !== "string" ||
+          typeof entry.probe_path !== "string") continue
+      configured.push({
+        id: entry.id,
+        root: path.resolve(entry.root),
+        probe_path: path.resolve(entry.probe_path)
+      })
+    }
+
+    const observed = []
+    for (const store of configured) {
       try {
-        const st = await fs.promises.stat(source.root)
-        source.dev = st.dev
-        source.available = st.isDirectory()
-        source.shareable = source.available && storeDev !== null && st.dev === storeDev && this.mode === "link"
+        const stat = await fs.promises.stat(store.probe_path)
+        if (stat.isDirectory()) observed.push({ store, dev: stat.dev })
       } catch (error) {
         if (!isMissingError(error)) throw error
-        source.available = false
-        source.shareable = false
       }
-      return source
+    }
+    let changed = configured.length !== config.anchor_stores.length
+    for (const candidate of candidates) {
+      let stat
+      try {
+        stat = await fs.promises.stat(candidate.probe_path)
+      } catch (error) {
+        if (isMissingError(error)) continue
+        throw error
+      }
+      if (!stat.isDirectory() ||
+          observed.some((item) => item.dev === stat.dev)) continue
+      const filesystemAnchor = candidate.home
+        ? null
+        : await this.filesystemAnchor(candidate.probe_path, stat.dev)
+      const store = {
+        id: crypto.randomUUID(),
+        root: candidate.home
+          ? candidate.preferred_root
+          : path.resolve(filesystemAnchor, ".pinokio", "vault"),
+        probe_path: candidate.probe_path
+      }
+      configured.push(store)
+      observed.push({ store, dev: stat.dev })
+      changed = true
+    }
+    if (changed) {
+      config = this.writeConfig(Object.assign({}, config, {
+        anchor_stores: configured
+      }))
     }
 
-    const seenExternalRoots = new Set()
-    const addExternalEntries = async (importRoot, idPrefix = "") => {
-      let entries = []
+    const stores = []
+    for (const entry of config.anchor_stores) {
+      const store = {
+        id: entry.id,
+        root: path.resolve(entry.root),
+        probe_path: path.resolve(entry.probe_path),
+        available: false,
+        dev: null,
+        mode: null
+      }
       try {
-        entries = await fs.promises.readdir(importRoot, { withFileTypes: true })
+        const probeStat = await fs.promises.stat(store.probe_path)
+        if (!probeStat.isDirectory()) {
+          stores.push(store)
+          continue
+        }
+        const rootStat = await lstatIfPresent(store.root)
+        if (rootStat &&
+            (!rootStat.isDirectory() || rootStat.isSymbolicLink())) {
+          throw unsafeStoragePath(store.root)
+        }
+        store.available = true
+        store.dev = probeStat.dev
+        store.mode = this.volumeModes.get(store.dev) || null
       } catch (error) {
         if (!isMissingError(error)) throw error
       }
-      for (const entry of entries) {
-        if (!entry.isSymbolicLink()) continue
-        const mountPath = path.resolve(importRoot, entry.name)
-        try {
-          const root = await fs.promises.realpath(mountPath)
-          const st = await fs.promises.stat(root)
-          if (!st.isDirectory()) continue
-          const canonical = path.resolve(root)
-          if (seenExternalRoots.has(canonical)) continue
-          seenExternalRoots.add(canonical)
-          sources.push(await decorate({
-            id: sourceId("external", `${idPrefix}${entry.name}`), kind: "external", label: entry.name,
-            root: canonical, mount_path: mountPath, parent_id: "external"
-          }))
-        } catch (error) {
-          if (!isMissingError(error)) throw error
-        }
+      stores.push(store)
+    }
+    this._anchorStores = stores
+    this._anchorStoresById = new Map(
+      stores.map((store) => [store.id, store]))
+    this._anchorStoresByDevice = new Map()
+    for (const store of stores) {
+      if (!store.available || !Number.isFinite(store.dev)) continue
+      if (this._anchorStoresByDevice.has(store.dev)) {
+        store.available = false
+        store.error = "duplicate_device"
+        continue
       }
+      this._anchorStoresByDevice.set(store.dev, store)
     }
+    return stores
+  }
 
-    let apiEntries = []
-    try {
-      apiEntries = await fs.promises.readdir(apiRoot, { withFileTypes: true })
-    } catch (error) {
-      if (!isMissingError(error)) throw error
+  async filesystemAnchor(directory, expectedDev = null) {
+    let current = path.resolve(directory)
+    const first = await fs.promises.stat(current)
+    const dev = expectedDev === null ? first.dev : expectedDev
+    if (!first.isDirectory() || first.dev !== dev) {
+      throw new Error("The configured location is not on the expected filesystem.")
     }
-    for (const entry of apiEntries) {
-      const mountPath = path.resolve(apiRoot, entry.name)
-      if (entry.isDirectory()) {
-        sources.push(await decorate({
-          id: sourceId("app", entry.name), kind: "app", label: entry.name,
-          app: entry.name, root: mountPath, parent_id: "apps"
-        }))
+    while (true) {
+      const parent = path.dirname(current)
+      if (parent === current) return current
+      let parentStat
+      try {
+        parentStat = await fs.promises.stat(parent)
+      } catch (error) {
+        if (isMissingError(error)) return current
+        throw error
       }
+      if (parentStat.dev !== dev) return current
+      current = parent
     }
-    await addExternalEntries(apiRoot)
-    if (await this.directoryIfSafe(this.sourceRoot)) {
-      await addExternalEntries(this.sourceRoot, "vault:")
-    }
+  }
 
-    let homeEntries = []
-    try {
-      homeEntries = await fs.promises.readdir(home, { withFileTypes: true })
-    } catch (error) {
-      if (!isMissingError(error)) throw error
-    }
-    for (const entry of homeEntries) {
-      if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name === "api" || entry.name === "vault") continue
-      sources.push(await decorate({
-        id: sourceId("folder", entry.name), kind: "folder", label: entry.name,
-        root: path.resolve(home, entry.name), parent_id: "pinokio"
-      }))
-    }
-    const homeSource = sources.find((source) => source.id === "pinokio")
-    if (homeSource) await decorate(homeSource)
-    this._sources = sources
-    this._sourceBases = new Map()
-    for (const source of sources) {
-      if (!source.root || source.kind === "virtual") continue
-      for (const base of [source.root, source.mount_path]) {
-        if (!base) continue
-        const resolved = path.resolve(base)
-        const key = process.platform === "win32" ? resolved.toLowerCase() : resolved
-        if (!this._sourceBases.has(key)) this._sourceBases.set(key, [])
-        this._sourceBases.get(key).push(source)
-      }
-    }
-    return sources
+  anchorStoreForDevice(dev) {
+    return this._anchorStoresByDevice.get(dev) || null
   }
-  sources() {
-    return this._sources
+
+  anchorStores() {
+    return this._anchorStores
   }
-  async addExternalSource(folderPath) {
-    if (!this.enabled) throw new Error("Save space is disabled.")
-    if (typeof folderPath !== "string" || !path.isAbsolute(folderPath.trim())) {
-      throw new Error("Choose a valid folder.")
-    }
-    const requested = folderPath.trim()
-    let canonical
-    let stats
-    try {
-      canonical = path.resolve(await fs.promises.realpath(requested))
-      stats = await fs.promises.stat(canonical)
-    } catch (error) {
-      throw new Error("That folder is no longer available.")
-    }
-    if (!stats.isDirectory()) throw new Error("Choose a folder, not a file.")
 
-    const home = path.resolve(this.kernel.homedir)
-    const canonicalHome = path.resolve(await fs.promises.realpath(home))
-    if (isPathWithin(canonicalHome, canonical) || isPathWithin(canonical, canonicalHome)) {
-      throw new Error("That folder is already inside Pinokio and is included in scans.")
-    }
+  anchorStoreForPath(filePath) {
+    return this._anchorStores.find((store) =>
+      isPathWithin(path.resolve(store.root, "sha256"), filePath)) || null
+  }
 
-    await this.refreshSources()
-    const existing = this._sources.find((source) => source.kind === "external" && source.root && samePath(source.root, canonical))
-    if (existing) {
-      return { created: false, source: existing }
-    }
-
-    const importRoot = this.sourceRoot
-    await this.ensureDirectory(importRoot)
-    const baseLabel = path.basename(canonical) || "external-folder"
-    let mountPath = null
-    for (let index = 1; index < 10000; index++) {
-      const label = index === 1 ? baseLabel : `${baseLabel}-${index}`
-      const candidate = path.resolve(importRoot, label)
+  storageRoots() {
+    const roots = [
+      this.root,
+      ...this._anchorStores.map((store) => store.root)
+    ].map((item) => path.resolve(item))
+    for (const root of [...roots]) {
       try {
-        await fs.promises.symlink(canonical, candidate, this.kernel.platform === "win32" ? "junction" : "dir")
-        mountPath = candidate
-        break
+        roots.push(path.resolve(fs.realpathSync(root)))
       } catch (error) {
-        if (error && error.code === "EEXIST") continue
-        if (error && (error.code === "EACCES" || error.code === "EPERM")) {
-          throw new Error("Pinokio does not have permission to add that folder.")
-        }
-        throw new Error("Pinokio could not add that folder.")
+        if (!isMissingError(error)) throw error
       }
     }
-    if (!mountPath) throw new Error("Pinokio could not create a unique name for that folder.")
+    return [...new Set(roots)]
+  }
 
-    try {
-      await this.refreshSources()
-      const source = this._sources.find((item) => item.kind === "external" && item.mount_path && samePath(item.mount_path, mountPath))
-      if (!source) throw new Error("The folder could not be added. Restart Pinokio and try again.")
-      return { created: true, source }
-    } catch (error) {
-      // Adding a source is transactional. Roll back only the exact directory
-      // link created above; preserve any path an external writer replaced.
-      try {
-        const [mounted, target] = await Promise.all([
-          fs.promises.lstat(mountPath),
-          fs.promises.realpath(mountPath)
-        ])
-        if (mounted.isSymbolicLink() && samePath(target, canonical)) {
-          await fs.promises.unlink(mountPath)
-        }
-      } catch {
-        // The original error remains authoritative; an unverified path is
-        // deliberately preserved rather than deleted.
-      }
-      throw error
-    }
-  }
-  sourceForPath(filePath, preferredId) {
-    let cursor = path.resolve(filePath)
-    while (true) {
-      const key = process.platform === "win32" ? cursor.toLowerCase() : cursor
-      const matches = this._sourceBases.get(key)
-      if (matches && matches.length) {
-        return matches.find((source) => source.id === preferredId) || matches[0]
-      }
-      const parent = path.dirname(cursor)
-      if (parent === cursor) return null
-      cursor = parent
-    }
-  }
-  async canonicalPathIsWithinSource(filePath, source, options = {}) {
-    if (!source || !source.root) return false
-    try {
-      const [canonicalRoot, canonicalFile] = await Promise.all([
-        fs.promises.realpath(source.root),
-        fs.promises.realpath(filePath)
-      ])
-      return isPathWithin(canonicalRoot, canonicalFile)
-    } catch (error) {
-      if (options.strictErrors && !isMissingError(error)) throw error
-      return false
-    }
-  }
-  locationForPath(filePath, preferredId) {
-    const source = this.sourceForPath(filePath, preferredId)
-    if (!source) return { source_id: null, relative_path: path.basename(filePath) }
-    const absolute = path.resolve(filePath)
-    let base = source.root
-    if (source.mount_path && isPathWithin(source.mount_path, absolute)) base = source.mount_path
-    const relative = path.relative(base, absolute).split(path.sep).join("/") || path.basename(absolute)
-    return {
-      source_id: source.id,
-      source_kind: source.kind,
-      source_label: source.label,
-      relative_path: relative
-    }
-  }
-  async recordEvent(event) {
-    let entry = event
-    if (event.path) {
-      const location = this.locationForPath(event.path, event.source_id)
-      const context = location.source_id ? location : { relative_path: event.path }
-      entry = Object.assign({}, event, context)
-    }
-    try {
-      await this.registry.appendEvent(entry)
-      return true
-    } catch (error) {
-      return false
-    }
-  }
-  scanSource(scopeId) {
-    if (!scopeId) return null
-    return this._sources.find((source) =>
-      source.id === scopeId && source.kind !== "virtual" && source.available && source.root) || null
-  }
-  scanRoots(scopeId = null) {
-    if (scopeId) {
-      const source = this.scanSource(scopeId)
-      return source ? [{ root: path.resolve(source.root), source_id: source.id }] : []
-    }
-    const home = path.resolve(this.kernel.homedir)
-    const candidates = [{ root: home, source_id: "pinokio" }]
-    for (const source of this._sources) {
-      if (source.kind !== "external" || !source.available || !source.root) continue
-      const canonical = path.resolve(source.root)
-      if (isPathWithin(home, canonical) || isPathWithin(canonical, home)) continue
-      candidates.push({ root: canonical, source_id: source.id })
-    }
-    candidates.sort((left, right) => left.root.length - right.root.length)
-    const roots = []
-    for (const candidate of candidates) {
-      if (roots.some((existing) => isPathWithin(existing.root, candidate.root))) continue
-      roots.push(candidate)
-    }
-    return roots
-  }
-  reconcileConfiguredSources() {
-    if (!this.registry) return
-    const configured = (filePath, sourceId) => !!this.sourceForPath(filePath, sourceId)
-    for (const [filePath, entry] of [...this.registry.links]) {
-      if (!configured(filePath, entry.source_id)) this.registry.untrack(filePath)
-    }
-    for (const [filePath, entry] of [...this.registry.duplicates]) {
-      if (!configured(filePath, entry.source_id)) this.registry.untrack(filePath)
-    }
-    for (const [filePath, entry] of [...this.registry.scanIndex]) {
-      if (!configured(filePath, entry.source_id)) this.registry.untrack(filePath)
-    }
-  }
-  // Kill switch: system ENVIRONMENT variable PINOKIO_VAULT, default unset =
-  // enabled. Read directly (single key) to avoid loading the environment
-  // module chain before the kernel is fully up.
-  async isEnabled() {
-    let value = process.env.PINOKIO_VAULT
-    if (value === undefined && this.kernel.homedir) {
-      try {
-        const raw = await fs.promises.readFile(path.resolve(this.kernel.homedir, "ENVIRONMENT"), "utf8")
-        for (const line of raw.split("\n")) {
-          const m = line.match(/^\s*PINOKIO_VAULT\s*=\s*(.*)\s*$/)
-          if (m) value = m[1].trim()
-        }
-      } catch (error) {
-        if (!isMissingError(error)) throw error
-      }
-    }
-    return String(value).toLowerCase() !== "false"
-  }
-  // Disabled ⇒ do nothing observable: no directory, no registry, no probes.
-  async init(options = {}) {
-    this.enabled = await this.isEnabled()
-    if (!this.enabled) return { enabled: false }
-    if (options.existingOnly) {
-      try {
-        await fs.promises.stat(this.root)
-      } catch (error) {
-        if (error && error.code === "ENOENT") return { enabled: true, fresh: true }
-        throw error
-      }
-    }
-    return this.initializeStorage()
-  }
-  async initializeStorage() {
-    if (this.initialized) return { enabled: true, mode: this.mode }
-    await this.ensureDirectory(this.root)
-    await this.ensureDirectory(this.blobRoot)
-    this.registry = new Registry(this.root)
-    this.mode = await this.probe(this.root)
-    await this.refreshSources()
-    const loaded = await this.registry.load()
-    const missingWithBlobs = !loaded.existed && await this.hasStoredBlobs()
-    if (loaded.corrupt || missingWithBlobs) {
-      await this.rebuild(undefined, { preserveState: false })
-    }
-    this.sweeper = new Sweeper(this)
-    this.initialized = true
-    return {
-      enabled: true,
-      mode: this.mode,
-      corrupt_recovered: !!loaded.corrupt,
-      missing_recovered: missingWithBlobs
-    }
+  isStorageRoot(directory) {
+    const target = path.resolve(directory)
+    return this.storageRoots().some((root) => samePath(root, target))
   }
-  async ensureInitialized() {
-    if (!this.enabled) return { enabled: false }
-    if (this.initialized && !this.verificationPending) return { enabled: true, mode: this.mode }
-    if (!this.initializationPromise) {
-      this.initializationPromise = (async () => {
-        const result = this.initialized
-          ? { enabled: true, mode: this.mode }
-          : await this.initializeStorage()
-        await this.runExclusive(async () => {
-          await this.verify()
-          await this.registry.flush()
-        })
-        this.verificationPending = false
-        return result
-      })().catch((error) => {
-        if (this.initialized) this.verificationPending = true
-        throw error
-      }).finally(() => {
-        this.initializationPromise = null
-      })
-    }
-    return this.initializationPromise
-  }
-  async hasStoredBlobs() {
-    let shards = []
-    try {
-      shards = await fs.promises.readdir(this.blobRoot, { withFileTypes: true })
-    } catch (error) {
-      if (isMissingError(error)) return false
-      throw error
-    }
-    for (const shard of shards) {
-      if (!shard.isDirectory() || !/^[0-9a-f]{2}$/.test(shard.name)) continue
-      const shardPath = path.resolve(this.blobRoot, shard.name)
-      const shardStat = await this.directoryIfSafe(shardPath)
-      if (!shardStat) continue
-      let names = []
-      try {
-        names = await fs.promises.readdir(shardPath)
-      } catch (error) {
-        if (isMissingError(error)) continue
-        throw error
-      }
-      if (names.some((name) => SHA256_RE.test(name) && name.startsWith(shard.name))) return true
-    }
-    return false
-  }
-  // Capability probe: temp file + node:fs.link + nlink check. Once per volume.
-  async probe(dir) {
-    const dev = (await fs.promises.stat(dir)).dev
+
+  async probe(directory) {
+    const dev = (await fs.promises.stat(directory)).dev
     if (this.volumeModes.has(dev)) return this.volumeModes.get(dev)
-    const a = path.resolve(dir, `.pinokio-probe-${crypto.randomBytes(6).toString("hex")}`)
-    const b = a + "-link"
+    const first = path.resolve(
+      directory, `.pinokio-probe-${crypto.randomBytes(6).toString("hex")}`)
+    const second = `${first}-link`
     let mode = "copy"
-    let aStat = null
-    let bStat = null
+    let firstStat = null
+    let secondStat = null
     let failure = null
     try {
-      await fs.promises.writeFile(a, "probe", { flag: "wx" })
-      aStat = await fs.promises.lstat(a)
-      await fs.promises.link(a, b)
-      bStat = await fs.promises.lstat(b)
-      if (sameIdentity(bStat, aStat) && bStat.nlink === 2) mode = "link"
+      await fs.promises.writeFile(first, "probe", { flag: "wx" })
+      firstStat = await fs.promises.lstat(first)
+      await fs.promises.link(first, second)
+      secondStat = await fs.promises.lstat(second)
+      if (sameIdentity(firstStat, secondStat) && secondStat.nlink === 2) {
+        mode = "link"
+      }
     } catch (error) {
       if (!NO_LINK_CODES.has(error && error.code)) failure = error
     } finally {
       try {
-        await unlinkIfSame(b, bStat)
-        await unlinkIfSame(a, aStat)
+        await unlinkIfSame(second, secondStat)
+        await unlinkIfSame(first, firstStat)
       } catch (error) {
         if (!failure) failure = error
       }
@@ -688,6 +730,7 @@ class Vault {
     this.volumeModes.set(dev, mode)
     return mode
   }
+
   failHashWorker(worker, error, terminate = false) {
     if (this.worker === worker) {
       if (this.workerIdleTimer) clearTimeout(this.workerIdleTimer)
@@ -702,6 +745,7 @@ class Vault {
     }
     if (terminate) worker.terminate().catch(() => {})
   }
+
   async hashFile(filePath, options = {}) {
     if (this.workerIdleTimer) {
       clearTimeout(this.workerIdleTimer)
@@ -711,7 +755,9 @@ class Vault {
       const worker = new Worker(path.resolve(__dirname, "hash_worker.js"))
       this.worker = worker
       worker.unref()
-      worker.on("message", ({ id, hash, size, bytes_read: bytesRead, error, code }) => {
+      worker.on("message", ({
+        id, hash, size, bytes_read: bytesRead, error, code
+      }) => {
         const job = this.workerJobs.get(id)
         if (!job || job.worker !== worker) return
         if (Number.isFinite(bytesRead)) {
@@ -729,8 +775,6 @@ class Vault {
           job.reportProgress(size)
           job.resolve({ hash, size })
         }
-        // Keep the worker warm across the scan queue. Starting one worker per
-        // file costs ~30ms and adds up quickly on a first scan.
         if (this.workerJobs.size === 0 && this.worker === worker) {
           this.workerIdleTimer = setTimeout(() => {
             this.workerIdleTimer = null
@@ -744,37 +788,49 @@ class Vault {
       })
       worker.on("error", (error) => {
         if (this.worker !== worker) return
-        this.failHashWorker(worker, error)
+        const failure = new Error(error && error.message
+          ? error.message
+          : "Hash worker failed.")
+        failure.code = "EVAULTHASHWORKER"
+        this.failHashWorker(worker, failure)
       })
       worker.on("exit", (code) => {
-        if (this.worker !== worker) return
-        this.failHashWorker(worker, new Error(`hash worker exited with code ${code}`))
+        if (this.worker === worker) {
+          const failure = new Error(`hash worker exited with code ${code}`)
+          failure.code = "EVAULTHASHWORKER"
+          this.failHashWorker(worker, failure)
+        }
       })
     }
     const worker = this.worker
     const id = ++this.workerSeq
     return new Promise((resolve, reject) => {
-      const onProgress = typeof options.onProgress === "function" ? options.onProgress : null
+      const onProgress = typeof options.onProgress === "function"
+        ? options.onProgress
+        : null
       const job = {
         worker,
         resolve,
         reject,
         reportProgress: (bytes) => {
           if (!onProgress) return
-          // Progress is observational and must never fail a content hash.
-          try { onProgress(bytes) } catch (_) {}
+          try {
+            onProgress(bytes)
+          } catch (error) {}
         },
         inactivityTimer: null,
         resetInactivity: null
       }
       job.resetInactivity = () => {
         clearTimeout(job.inactivityTimer)
-        const inactivityMs = Math.max(1, Number(this.hashInactivityMs) || HASH_INACTIVITY_MS)
+        const timeout = Math.max(
+          1, Number(this.hashInactivityMs) || HASH_INACTIVITY_MS)
         job.inactivityTimer = setTimeout(() => {
-          const failure = new Error(`Timed out while reading ${path.basename(filePath)}`)
+          const failure = new Error(
+            `Timed out while reading ${path.basename(filePath)}`)
           failure.code = "ETIMEDOUT"
           this.failHashWorker(worker, failure, true)
-        }, inactivityMs)
+        }, timeout)
         if (job.inactivityTimer.unref) job.inactivityTimer.unref()
       }
       this.workerJobs.set(id, job)
@@ -782,1315 +838,1893 @@ class Vault {
       try {
         worker.postMessage({ id, filePath })
       } catch (error) {
-        this.failHashWorker(worker, error, true)
+        const failure = new Error(error && error.message
+          ? error.message
+          : "Hash worker could not accept work.")
+        failure.code = "EVAULTHASHWORKER"
+        this.failHashWorker(worker, failure, true)
       }
     })
   }
-  async refreshLinkSnapshots(hash, dev, ino) {
-    if (!this.registry) return
-    const key = this.registry.inoKey(dev, ino)
-    const paths = [...(this.registry.pathsByIno.get(key) || [])]
-    for (const linkPath of paths) {
-      const entry = this.registry.links.get(linkPath)
-      if (!entry || entry.hash !== hash) continue
+
+  async refreshSources() {
+    const home = path.resolve(this.kernel.homedir)
+    const apiRoot = path.resolve(home, "api")
+    const sources = [
+      {
+        id: "pinokio", kind: "pinokio", label: "Pinokio",
+        root: home, parent_id: null
+      },
+      {
+        id: "apps", kind: "virtual", label: "Apps",
+        root: apiRoot, parent_id: "pinokio"
+      },
+      {
+        id: "external", kind: "virtual", label: "External folders",
+        root: null, parent_id: null
+      }
+    ]
+    const decorate = async (source) => {
+      if (!source.root) return source
       try {
-        const source = this.sourceForPath(linkPath, entry.source_id)
-        if (!source || !await this.canonicalPathIsWithinSource(linkPath, source)) continue
-        const st = await fs.promises.lstat(linkPath)
-        if (st.dev !== dev || st.ino !== ino) continue
-        this.registry.setScanEntry(linkPath, Object.assign(fileSnapshot(st), {
-          hash,
-          source_id: entry.source_id || null
-        }))
-      } catch (error) {}
-    }
-    this.registry.schedulePersist()
-  }
-  async verifyStoreContent(hash, storePath, storeStat) {
-    if (!storeStat || !storeStat.isFile()) return { valid: false }
-    const key = this.registry.inoKey(storeStat.dev, storeStat.ino)
-    for (const linkPath of this.registry.pathsByIno.get(key) || []) {
-      const entry = this.registry.links.get(linkPath)
-      if (!entry) continue
-      if (entry.hash !== hash || entry.mode !== "link" ||
-          entry.dev !== storeStat.dev || entry.ino !== storeStat.ino) continue
-      const expected = this.registry.scanIndex.get(linkPath)
-      if (expected && expected.hash === hash && sameSnapshot(expected, storeStat)) {
-        return { valid: true, snapshot: fileSnapshot(storeStat) }
+        const [stat, realRoot] = await Promise.all([
+          fs.promises.lstat(source.root),
+          fs.promises.realpath(source.root)
+        ])
+        source.canonical_root = path.resolve(realRoot)
+        source.dev = stat.dev
+        source.available = stat.isDirectory() &&
+          !stat.isSymbolicLink() &&
+          (source.kind !== "external" || samePath(realRoot, source.root))
+        const store = this.anchorStoreForDevice(stat.dev)
+        source.shareable = source.available &&
+          !!store &&
+          store.mode !== "copy"
+        source.store_id = store ? store.id : null
+      } catch (error) {
+        if (!isMissingError(error)) throw error
+        source.available = false
+        source.shareable = false
       }
+      return source
     }
 
-    const before = fileSnapshot(storeStat)
-    let hashed
+    let apps = []
     try {
-      hashed = await this.hashFile(storePath)
+      apps = await fs.promises.readdir(apiRoot, { withFileTypes: true })
     } catch (error) {
-      return { valid: false }
+      if (!isMissingError(error)) throw error
+    }
+    for (const entry of apps) {
+      if (!entry.isDirectory() || entry.isSymbolicLink()) continue
+      sources.push(await decorate({
+        id: sourceId("app", entry.name),
+        kind: "app",
+        label: entry.name,
+        app: entry.name,
+        root: path.resolve(apiRoot, entry.name),
+        parent_id: "apps"
+      }))
+    }
+
+    for (const configuredPath of this.configuredLocations()) {
+      sources.push(await decorate({
+        id: sourceId("external", configuredPath),
+        kind: "external",
+        label: path.basename(configuredPath) || configuredPath,
+        root: configuredPath,
+        parent_id: "external",
+        configured: true
+      }))
     }
-    let after
+
+    let homeEntries = []
     try {
-      after = await this.storeStatIfPresent(storePath)
+      homeEntries = await fs.promises.readdir(home, { withFileTypes: true })
     } catch (error) {
-      return { valid: false }
+      if (!isMissingError(error)) throw error
     }
-    if (!sameSnapshot(before, after) || hashed.hash !== hash || hashed.size !== after.size) {
-      return { valid: false }
+    for (const entry of homeEntries) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() ||
+          entry.name === "api" || entry.name === "vault") continue
+      sources.push(await decorate({
+        id: sourceId("folder", entry.name),
+        kind: "folder",
+        label: entry.name,
+        root: path.resolve(home, entry.name),
+        parent_id: "pinokio"
+      }))
     }
-    await this.refreshLinkSnapshots(hash, after.dev, after.ino)
-    return { valid: true, snapshot: fileSnapshot(after) }
-  }
-  // adopt: give an existing file a store name. Metadata-only, never copies.
-  async adopt(filePath, hash, meta = {}) {
-    if (!this.enabled) return { status: "disabled" }
-    const storePath = this.storePathFor(hash)
-    const st = await fs.promises.lstat(filePath)
-    if (!st.isFile()) return { status: "stale" }
-    if (meta.expected && !sameSnapshot(meta.expected, st)) return { status: "stale" }
-    const before = fileSnapshot(st)
-    const linkEntry = {
-      hash,
-      app: meta.app || null,
-      source_id: meta.source_id || null,
-      dev: st.dev,
-      ino: st.ino,
-      mode: "link"
-    }
-    const storeStat = await this.storeStatIfPresent(storePath, {
-      createParent: this.mode === "link"
-    })
-    if (storeStat) {
-      if (storeStat.dev === st.dev && storeStat.ino === st.ino) {
-        const current = await lstatIfPresent(filePath)
-        if (!sameSnapshot(before, current)) return { status: "stale" }
-        this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
-        this.registry.addLink(filePath, linkEntry)
-        await this.refreshLinkSnapshots(hash, st.dev, st.ino)
-        return { status: "already" }
-      }
-      const current = await lstatIfPresent(filePath)
-      if (!sameSnapshot(before, current)) return { status: "stale" }
-      return { status: "duplicate", storePath }
-    }
-    const registerCopy = async () => {
-      const current = await lstatIfPresent(filePath)
-      if (!sameSnapshot(before, current)) return { status: "stale" }
-      linkEntry.mode = "copy"
-      this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
-      this.registry.addLink(filePath, linkEntry)
-      await this.refreshLinkSnapshots(hash, st.dev, st.ino)
-      await this.recordEvent({
-        kind: "adopt", hash, path: filePath, app: meta.app || null,
-        source_id: meta.source_id || null, bytes_saved: 0, mode: "copy"
-      })
-      return { status: "copy-mode" }
+
+    const pinokio = sources.find((source) => source.id === "pinokio")
+    if (pinokio) await decorate(pinokio)
+    this._sources = sources
+    this._sourcesById = new Map(
+      sources.map((source) => [source.id, source])
+    )
+    this._sourceBases = new Map()
+    for (const source of sources) {
+      if (!source.root || source.kind === "virtual") continue
+      const bases = new Set([
+        path.resolve(source.root),
+        source.canonical_root && path.resolve(source.canonical_root)
+      ].filter(Boolean))
+      for (const resolved of bases) {
+        const key = process.platform === "win32"
+          ? resolved.toLowerCase()
+          : resolved
+        if (!this._sourceBases.has(key)) this._sourceBases.set(key, [])
+        this._sourceBases.get(key).push(source)
+      }
     }
-    if (this.mode === "copy") return registerCopy()
-    try {
-      await fs.promises.link(filePath, storePath)
-    } catch (e) {
-      if (NO_LINK_CODES.has(e.code)) {
-        return registerCopy()
+    return sources
+  }
+
+  sources() {
+    return this._sources
+  }
+
+  sourceForPath(filePath, preferredId = null) {
+    let cursor = path.resolve(filePath)
+    while (true) {
+      const key = process.platform === "win32"
+        ? cursor.toLowerCase()
+        : cursor
+      const matches = this._sourceBases.get(key)
+      if (matches && matches.length) {
+        return matches.find((source) => source.id === preferredId) || matches[0]
       }
-      throw e
+      const parent = path.dirname(cursor)
+      if (parent === cursor) return null
+      cursor = parent
     }
-    const [current, currentStore] = await Promise.all([
-      lstatIfPresent(filePath),
-      this.storeStatIfPresent(storePath)
-    ])
-    if (!sameContentState(before, current) || !currentStore ||
-        currentStore.dev !== st.dev || currentStore.ino !== st.ino) {
-      // Remove only a store name that still points either to the inode we
-      // intended to link or to the current source inode that won the race.
-      // An unrelated replacement at the reserved store path is preserved.
-      const ownsStoreName = currentStore && (
-        (currentStore.dev === st.dev && currentStore.ino === st.ino) ||
-        (current && currentStore.dev === current.dev && currentStore.ino === current.ino)
-      )
-      if (ownsStoreName) {
-        try {
-          await fs.promises.unlink(storePath)
-        } catch (error) {
-          if (!isMissingError(error)) throw error
+  }
+
+  sourceIsWithinScope(source, scopeId) {
+    if (!scopeId) return true
+    const seen = new Set()
+    let current = source
+    while (current && !seen.has(current.id)) {
+      if (current.id === scopeId) return true
+      seen.add(current.id)
+      current = this._sourcesById.get(current.parent_id)
+    }
+    return false
+  }
+
+  scanSource(scopeId) {
+    if (!scopeId) return null
+    const source = this._sourcesById.get(scopeId)
+    return source &&
+      source.kind !== "virtual" &&
+      source.available &&
+      source.root
+      ? source
+      : null
+  }
+
+  scanRoots(scopeId = null) {
+    if (scopeId) {
+      const source = this.scanSource(scopeId)
+      return source
+        ? [{ root: path.resolve(source.root), source_id: source.id }]
+        : []
+    }
+    const pinokio = this._sourcesById.get("pinokio")
+    const candidates = [
+      {
+        root: path.resolve(pinokio && pinokio.root || this.kernel.homedir),
+        canonical_root: path.resolve(
+          pinokio && pinokio.canonical_root ||
+          pinokio && pinokio.root ||
+          this.kernel.homedir
+        ),
+        source_id: "pinokio"
+      },
+      ...this._sources
+      .filter((source) =>
+        source.kind === "external" && source.available && source.root)
+      .map((source) => ({
+        root: path.resolve(source.root),
+        canonical_root: path.resolve(source.canonical_root || source.root),
+        source_id: source.id
+      }))
+    ].sort((left, right) =>
+      left.canonical_root.length - right.canonical_root.length ||
+      left.canonical_root.localeCompare(right.canonical_root))
+    const roots = []
+    for (const candidate of candidates) {
+      const canonical = candidate.canonical_root
+      if (roots.some((root) =>
+        isPathWithin(root.canonical_root, canonical))) continue
+      for (let index = roots.length - 1; index >= 0; index--) {
+        if (isPathWithin(canonical, roots[index].canonical_root)) {
+          roots.splice(index, 1)
         }
       }
-      return { status: "stale" }
+      roots.push(candidate)
     }
-    this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
-    this.registry.addLink(filePath, linkEntry)
-    await this.refreshLinkSnapshots(hash, st.dev, st.ino)
-    await this.recordEvent({ kind: "adopt", hash, path: filePath, app: meta.app || null, source_id: meta.source_id || null, bytes_saved: 0 })
-    return { status: "adopted" }
-  }
-  // convert: replace a byte-identical duplicate with a link to an existing
-  // blob. Atomic link+rename; target is never missing at any instant.
-  async convert(targetPath, hash, meta = {}) {
-    if (!this.enabled) return { status: "disabled" }
-    const storePath = this.storePathFor(hash)
-    let storeStat
+    return roots.map(({ root, source_id: sourceIdValue }) => ({
+      root,
+      source_id: sourceIdValue
+    }))
+  }
+
+  scopeSourceIds(scopeId = null, locationId = null) {
+    return this._sources
+      .filter((source) => source.kind !== "virtual")
+      .filter((source) => !scopeId || this.sourceIsWithinScope(source, scopeId))
+      .filter((source) =>
+        !locationId || this.sourceIsWithinScope(source, locationId))
+      .map((source) => source.id)
+  }
+
+  async canonicalPathIsWithinSource(filePath, source) {
+    if (!source || !source.root) return false
     try {
-      storeStat = await this.storeStatIfPresent(storePath)
-    } catch (e) {
-      return { status: "no-blob" }
-    }
-    if (!storeStat) return { status: "no-blob" }
-    let targetStat = await fs.promises.lstat(targetPath)
-    if (!storeStat.isFile() || !targetStat.isFile()) return { status: "stale" }
-    if (meta.expected && !sameSnapshot(meta.expected, targetStat)) {
-      // Windows metadata operations can change ctime without changing the
-      // file's identity or bytes. Recover only that isolated mismatch by
-      // hashing the target again, then retain the exact pre-rename check below.
-      if (!sameContentState(meta.expected, targetStat)) return { status: "stale" }
-      const before = fileSnapshot(targetStat)
-      let verifiedTarget
-      try {
-        verifiedTarget = await this.hashFile(targetPath)
-      } catch (error) {
-        return { status: "stale" }
-      }
-      const after = await lstatIfPresent(targetPath)
-      if (!sameSnapshot(before, after) ||
-          verifiedTarget.hash !== hash || verifiedTarget.size !== after.size) {
-        return { status: "stale" }
+      const rootStat = await fs.promises.lstat(source.root)
+      if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return false
+      const [root, target] = await Promise.all([
+        fs.promises.realpath(source.root),
+        fs.promises.realpath(filePath)
+      ])
+      if (source.kind === "external" && !samePath(root, source.root)) {
+        return false
       }
-      targetStat = after
+      return isPathWithin(root, target)
+    } catch (error) {
+      if (!isMissingError(error)) throw error
+      return false
     }
-    if (storeStat.dev !== targetStat.dev) {
-      return { status: "unavailable", code: "EXDEV" }
+  }
+
+  async revealFile(scopeId, filePath) {
+    if (typeof filePath !== "string" ||
+        !path.isAbsolute(filePath)) {
+      return { error: "Choose a valid file." }
     }
-    if (storeStat.dev === targetStat.dev && storeStat.ino === targetStat.ino) {
-      this.registry.addLink(targetPath, { hash, app: meta.app || null, source_id: meta.source_id || null, dev: storeStat.dev, ino: storeStat.ino, mode: "link" })
-      await this.refreshLinkSnapshots(hash, storeStat.dev, storeStat.ino)
-      return { status: "already" }
+    if (scopeId && !this._sourcesById.has(scopeId)) {
+      return { error: "That location is no longer available." }
     }
-    if (storeStat.size !== targetStat.size) {
-      return { status: "size-mismatch" }
+    const entry = await this.registry.getFile(path.resolve(filePath))
+    if (!entry || entry.unavailable_reason === "stale") {
+      return { error: "This file is no longer tracked. Scan again to refresh this view." }
     }
-    if (!sameFileMetadata(storeStat, targetStat)) {
-      return { status: "metadata-mismatch" }
+    const source = this.sourceForPath(entry.path, entry.source_id)
+    if (!source || !this.sourceIsWithinScope(source, scopeId)) {
+      return { error: "This file is outside the current location." }
+    }
+    if (!await this.canonicalPathIsWithinSource(entry.path, source)) {
+      return { error: "This file is no longer available at the scanned location." }
+    }
+    const current = await lstatIfPresent(entry.path)
+    if (!current || !current.isFile()) {
+      return { error: "This file is no longer available at the scanned location." }
     }
-    const verifiedStore = await this.verifyStoreContent(hash, storePath, storeStat)
-    if (!verifiedStore.valid) return { status: "stale-blob" }
-    if (meta.source && this.sourceAppIsRunning(meta.source)) return { status: "locked" }
-    const tmp = targetPath + TMP_SUFFIX
-    let ownsTmp = false
     try {
-      try {
-        await fs.promises.link(storePath, tmp)
-        ownsTmp = true
-      } catch (e) {
-        if (e.code === "EEXIST") {
-          let tmpStat = null
-          try { tmpStat = await fs.promises.lstat(tmp) } catch (error) {}
-          if (!tmpStat || tmpStat.dev !== storeStat.dev || tmpStat.ino !== storeStat.ino) {
-            return { status: "conflict" }
-          }
-        } else {
-          throw e
+      await this.fileManagerLauncher(entry.path)
+    } catch (error) {
+      return { error: "The file manager could not open this file." }
+    }
+    return { revealed: true }
+  }
+
+  locationForPath(filePath, preferredId = null) {
+    const source = this.sourceForPath(filePath, preferredId)
+    if (!source) {
+      return {
+        source_id: null,
+        relative_path: path.basename(filePath)
+      }
+    }
+    const resolvedPath = path.resolve(filePath)
+    const sourceBase = source.canonical_root &&
+      isPathWithin(source.canonical_root, resolvedPath)
+      ? source.canonical_root
+      : source.root
+    const relative = path.relative(sourceBase, resolvedPath)
+      .split(path.sep).join("/") || path.basename(filePath)
+    return {
+      source_id: source.id,
+      source_kind: source.kind,
+      source_label: source.label,
+      relative_path: relative
+    }
+  }
+
+  async addExternalSource(folderPath) {
+    if (typeof folderPath !== "string" ||
+        !path.isAbsolute(folderPath.trim())) {
+      throw new Error("Choose a valid folder.")
+    }
+    const canonical = path.resolve(
+      await fs.promises.realpath(folderPath.trim()))
+    const stat = await fs.promises.stat(canonical)
+    if (!stat.isDirectory()) throw new Error("Choose a folder, not a file.")
+
+    const home = path.resolve(await fs.promises.realpath(this.kernel.homedir))
+    if (isPathWithin(home, canonical)) {
+      throw new Error(
+        "That folder is already inside Pinokio and is included in scans.")
+    }
+    await this.refreshSources()
+    const existing = this._sources.find((source) =>
+      source.kind === "external" &&
+      source.root &&
+      samePath(source.root, canonical))
+    if (existing) return { created: false, source: existing }
+
+    const config = this.readConfig()
+    this.writeConfig(Object.assign({}, config, {
+      locations: [...config.locations, canonical]
+    }))
+    await this.refreshAnchorStores()
+    await this.refreshSources()
+    const source = this._sources.find((candidate) =>
+      candidate.kind === "external" &&
+      samePath(candidate.root, canonical))
+    return { created: true, source }
+  }
+
+  async removeExternalSource(sourceIdToRemove) {
+    await this.refreshSources()
+    const source = this._sources.find((candidate) =>
+      candidate.id === sourceIdToRemove &&
+      candidate.kind === "external" &&
+      candidate.configured)
+    if (!source) {
+      return { error: "That external folder is no longer configured." }
+    }
+    const config = this.readConfig()
+    this.writeConfig(Object.assign({}, config, {
+      locations: config.locations.filter((item) =>
+        !samePath(item, source.root))
+    }))
+    await this.registry.removeExternalSourceState(source.root, source.id)
+    await this.refreshAnchorStores()
+    await this.refreshSources()
+    return {
+      removed: true,
+      source_id: source.id,
+      label: source.label
+    }
+  }
+
+  async recordEvent(event) {
+    try {
+      await this.registry.addEvent(event)
+      return true
+    } catch (error) {
+      return false
+    }
+  }
+
+  startScan(scopeId = null, sizeThreshold = this.sizeThreshold) {
+    if (!this.enabled || !this.sweeper) {
+      return { started: false, disabled: true }
+    }
+    if (this.scanPromise) return { started: false, already_running: true }
+    this.sizeThreshold = sizeThreshold
+    this.scanError = null
+    this.scanScopeId = scopeId
+    this.scanCancelRequested = false
+    this.scanPromise = this.runExclusive(() => {
+      if (this.scanCancelRequested) {
+        this.sweeper.state = Object.assign(this.sweeper.idleState(), {
+          phase: "cancelled",
+          scope_id: scopeId
+        })
+        return { cancelled: true }
+      }
+      return this.sweeper.scan(scopeId)
+    }).catch((error) => {
+      this.scanError = error && error.message
+        ? error.message
+        : String(error)
+    }).finally(() => {
+      this.scanPromise = null
+      this.scanScopeId = null
+      this.scanCancelRequested = false
+    })
+    return { started: true }
+  }
+
+  cancelScan() {
+    if (!this.scanPromise || !this.sweeper) {
+      return { cancel_requested: false }
+    }
+    this.scanCancelRequested = true
+    if (this.sweeper.state.active && this.sweeper.currentHash &&
+        this.worker) {
+      const error = new Error("Scan cancelled.")
+      error.code = "EVAULTCANCELLED"
+      this.failHashWorker(this.worker, error, true)
+    }
+    return {
+      cancel_requested: this.sweeper.state.active
+        ? this.sweeper.cancel()
+        : true
+    }
+  }
+
+  async perform(action, payload = {}) {
+    if (!this.enabled) return { error: "Save space is disabled." }
+    await this.ensureInitialized()
+    switch (action) {
+      case "add_source": {
+        const result = await this.runExclusive(() =>
+          this.addExternalSource(payload.path))
+        return {
+          created: result.created,
+          source: {
+            id: result.source.id,
+            label: result.source.label,
+            target_path: result.source.root,
+            shareable: !!result.source.shareable
+          }
         }
       }
-      // Narrow the portable stat/rename race as far as Node permits. The app
-      // guard prevents known Pinokio writers; arbitrary external writers in the
-      // final syscall-sized interval are the documented residual limitation.
-      if (meta.source && this.sourceAppIsRunning(meta.source)) {
-        if (ownsTmp) await unlinkIfSame(tmp, storeStat).catch(() => {})
-        return { status: "locked" }
+      case "remove_source":
+        if (typeof payload.source_id !== "string" || !payload.source_id) {
+          return { error: "Choose an external folder to remove." }
+        }
+        return this.runMutation(() =>
+          this.removeExternalSource(payload.source_id))
+      case "scan": {
+        if (payload.scope_id && !this.scanSource(payload.scope_id)) {
+          return { error: "That scan location is no longer available." }
+        }
+        let threshold = this.sizeThreshold
+        if (payload.candidate_size != null) {
+          if (!CANDIDATE_SIZE_OPTIONS.includes(payload.candidate_size)) {
+            return { error: "Choose a valid minimum file size." }
+          }
+          threshold = payload.candidate_size
+        }
+        return this.startScan(payload.scope_id || null, threshold)
+      }
+      case "cancel_scan":
+        return this.cancelScan()
+      case "cancel_file_action":
+        return this.cancelFileAction()
+      case "reveal":
+        return this.revealFile(
+          typeof payload.scope_id === "string" && payload.scope_id
+            ? payload.scope_id
+            : null,
+          payload.path
+        )
+      case "deduplicate": {
+        const scopeId = typeof payload.scope_id === "string" &&
+          payload.scope_id
+          ? payload.scope_id
+          : null
+        if (scopeId && !this._sources.some((source) =>
+          source.id === scopeId)) {
+          return { error: "That location is no longer available." }
+        }
+        if (typeof payload.path === "string" && payload.path) {
+          return this.runMutation(() => this.runFileAction({
+            kind: "deduplicate-file",
+            path: path.resolve(payload.path)
+          }, () => this.deduplicateFile(payload.path)))
+        }
+        const filesTotal = await this.countActionFiles("duplicate", scopeId)
+        return this.runMutation(() => this.runFileAction({
+          kind: "deduplicate",
+          scope_id: scopeId,
+          files_total: filesTotal,
+          files_completed: 0
+        }, (progress) => this.deduplicateScope(scopeId, { progress })))
+      }
+      case "deduplicate_files": {
+        if (!Array.isArray(payload.paths) ||
+            payload.paths.length === 0 ||
+            payload.paths.length > MAX_BULK_FILE_ACTIONS ||
+            payload.paths.some((item) =>
+              typeof item !== "string" || !item)) {
+          return { error: "Choose valid duplicate files to deduplicate." }
+        }
+        const paths = [...new Set(payload.paths.map((item) =>
+          path.resolve(item)))]
+        return this.runMutation(() => this.runFileAction({
+          kind: "deduplicate-files",
+          files_total: paths.length,
+          files_completed: 0
+        }, (progress) => this.deduplicateFiles(paths, progress)))
       }
-      const currentTmpStat = await lstatIfPresent(tmp)
-      if (!currentTmpStat || currentTmpStat.dev !== storeStat.dev || currentTmpStat.ino !== storeStat.ino) {
-        if (ownsTmp) await unlinkIfSame(tmp, storeStat).catch(() => {})
-        return { status: "conflict" }
+      case "detach":
+        if (typeof payload.path !== "string" || !payload.path) {
+          return { status: "not-found" }
+        }
+        return this.runMutation(() => this.runFileAction({
+          kind: "make-separate",
+          path: path.resolve(payload.path)
+        }, () => this.separate(payload.path)))
+      case "separate_files": {
+        if (!Array.isArray(payload.paths) ||
+            payload.paths.length === 0 ||
+            payload.paths.length > MAX_BULK_FILE_ACTIONS ||
+            payload.paths.some((item) =>
+              typeof item !== "string" || !item)) {
+          return { error: "Choose valid deduplicated files to separate." }
+        }
+        return this.runMutation(() => this.runFileAction({
+          kind: "separate-files",
+          files_total: new Set(payload.paths.map((item) =>
+            path.resolve(item))).size,
+          files_completed: 0
+        }, (progress) => this.separateFiles(payload.paths, progress)))
+      }
+      case "separate_all": {
+        const selection = this.separateSelection(payload)
+        if (selection.error) return { error: selection.error }
+        const total = await this.registry.matchingFileSummary(
+          "linked", selection.sourceIds, selection.query)
+        if (!total.count) {
+          return { error: "No matching deduplicated files remain." }
+        }
+        return this.runMutation(() => this.runFileAction({
+          kind: "separate-files",
+          files_total: total.count,
+          files_completed: 0,
+          all_matching: true,
+          cancelable: true,
+          cancel_requested: false
+        }, (progress) =>
+          this.separateMatchingFiles(selection, progress)))
       }
-      const currentTargetStat = await fs.promises.lstat(targetPath)
-      if (!sameSnapshot(fileSnapshot(targetStat), currentTargetStat)) {
-        if (ownsTmp) await unlinkIfSame(tmp, storeStat).catch(() => {})
-        return { status: "stale" }
+      case "reclaim":
+        return this.runMutation(() =>
+          this.reclaim(payload.hash, payload.store_id))
+      case "reclaim_all":
+        return this.runMutation(() => this.reclaimAll())
+      default:
+        return { error: "unknown action" }
+    }
+  }
+
+  sourceAppIsRunning(source) {
+    if (!source || source.kind !== "app") return false
+    const appRoot = path.resolve(this.kernel.homedir, "api", source.app)
+    const api = this.kernel.api || {}
+    const running = api.running || {}
+    const runningPaths = api.running_paths || {}
+    return Object.keys(running).some((id) => {
+      if (!running[id]) return false
+      const runningPath = runningPaths[id] ||
+        (path.isAbsolute(id) ? id.split("?")[0] : null)
+      return !!(runningPath && isPathWithin(appRoot, runningPath))
+    })
+  }
+
+  async refreshInodeSnapshots(hash, dev, ino, storeId = null) {
+    const store = storeId
+      ? this._anchorStoresById.get(storeId)
+      : this.anchorStoreForDevice(dev)
+    const storePath = store ? this.storePathFor(hash, store.id) : null
+    const storeStat = storePath
+      ? await this.storeStatIfPresent(storePath, { store_id: store.id })
+      : null
+    let inodeStat = storeStat &&
+      storeStat.dev === dev &&
+      storeStat.ino === ino
+      ? storeStat
+      : null
+    if (!inodeStat) {
+      const row = await this.registry.firstFileForInode(hash, dev, ino)
+      if (row) {
+        try {
+          const stat = await fs.promises.lstat(row.path)
+          if (stat.isFile() && stat.dev === dev && stat.ino === ino) {
+            inodeStat = stat
+          }
+        } catch (error) {}
       }
-      const currentStoreStat = await this.storeStatIfPresent(storePath)
-      // Creating our temporary hardlink changes ctime on the shared inode.
-      // Identity, size, and mtime still detect replacement or content writes.
-      if (!currentStoreStat || !sameContentState(verifiedStore.snapshot, currentStoreStat) ||
-          !sameFileMetadata(currentStoreStat, currentTargetStat)) {
-        if (ownsTmp) await unlinkIfSame(tmp, storeStat).catch(() => {})
-        return { status: "stale-blob" }
-      }
-      await fs.promises.rename(tmp, targetPath)
-      ownsTmp = false
-    } catch (e) {
-      if (ownsTmp) await unlinkIfSame(tmp, storeStat).catch(() => {})
-      if (LOCK_CODES.has(e.code)) {
-        return { status: "locked" }
+    }
+    if (inodeStat) {
+      await this.registry.updateInodeSnapshots(
+        dev, ino, fileSnapshot(inodeStat))
+    }
+    const content = await this.registry.getContent(hash)
+    if (content) {
+      await this.registry.upsertContent(Object.assign({}, content, {
+        hash,
+        size: storeStat ? storeStat.size : content.size
+      }))
+    }
+    if (store && storeStat) {
+      await this.registry.upsertAnchor({
+        store_id: store.id,
+        hash,
+        path: storePath,
+        verified_at: Date.now(),
+        dev: storeStat.dev,
+        ino: storeStat.ino,
+        size: storeStat.size,
+        mtime: storeStat.mtimeMs,
+        ctime: storeStat.ctimeMs,
+        nlink: storeStat.nlink,
+        mode: storeStat.mode,
+        uid: storeStat.uid,
+        gid: storeStat.gid
+      })
+    } else if (store) {
+      await this.registry.removeAnchor(store.id, hash)
+    }
+  }
+
+  async reclassifyHashes(hashes) {
+    const stores = this.anchorStores()
+      .filter((store) =>
+        store.available && Number.isFinite(store.dev))
+      .map((store) => ({
+        store_id: store.id,
+        dev: store.dev,
+        can_link: store.mode !== "copy"
+      }))
+    for (const hash of new Set(hashes)) {
+      const anchorSnapshots = []
+      for (const store of this.anchorStores()) {
+        const storePath = this.storePathFor(hash, store.id)
+        const stat = await this.storeStatIfPresent(storePath, {
+          store_id: store.id
+        })
+        if (stat) anchorSnapshots.push(fileSnapshot(stat))
       }
-      if (NO_LINK_CODES.has(e.code)) {
-        return { status: "unavailable", code: e.code }
+      await this.registry.reclassifyHash(
+        hash,
+        stores,
+        anchorSnapshots
+      )
+    }
+  }
+
+  async verifyStoreContent(hash, storePath, storeStat, storeId = null) {
+    if (!storeStat || !storeStat.isFile()) return { valid: false }
+    const store = storeId
+      ? this._anchorStoresById.get(storeId)
+      : this.anchorStoreForPath(storePath)
+    if (!store) return { valid: false }
+    const content = await this.registry.getContent(hash)
+    const anchor = await this.registry.getAnchor(store.id, hash)
+    if (anchor &&
+        anchor.verified_at &&
+        anchor.dev === storeStat.dev &&
+        anchor.ino === storeStat.ino &&
+        anchor.size === storeStat.size &&
+        anchor.mtime === storeStat.mtimeMs &&
+        anchor.ctime === storeStat.ctimeMs) {
+      return { valid: true, snapshot: fileSnapshot(storeStat) }
+    }
+    const before = fileSnapshot(storeStat)
+    let hashed
+    try {
+      hashed = await this.hashFile(storePath)
+    } catch (error) {
+      return { valid: false }
+    }
+    const after = await this.storeStatIfPresent(storePath)
+    if (!after ||
+        !sameSnapshot(before, after) ||
+        hashed.hash !== hash ||
+        hashed.size !== after.size) {
+      return { valid: false }
+    }
+    await this.registry.upsertContent({
+      hash,
+      size: after.size,
+      first_seen: content && content.first_seen,
+      verified_at: Date.now()
+    })
+    await this.registry.upsertAnchor({
+      store_id: store.id,
+      hash,
+      path: storePath,
+      verified_at: Date.now(),
+      dev: after.dev,
+      ino: after.ino,
+      size: after.size,
+      mtime: after.mtimeMs,
+      ctime: after.ctimeMs,
+      nlink: after.nlink,
+      mode: after.mode,
+      uid: after.uid,
+      gid: after.gid
+    })
+    return { valid: true, snapshot: fileSnapshot(after) }
+  }
+
+  async adopt(filePath, hash, expected, selectedStore = null) {
+    const current = await lstatIfPresent(filePath)
+    if (!current ||
+        !current.isFile() ||
+        !sameSnapshot(expected, current)) {
+      return { status: "stale" }
+    }
+    const store = selectedStore || this.anchorStoreForDevice(current.dev)
+    if (!store) return { status: "unavailable" }
+    const storePath = this.storePathFor(hash, store.id)
+    let storeStat
+    try {
+      storeStat = await this.storeStatIfPresent(storePath, {
+        createParent: true,
+        dev: current.dev,
+        store_id: store.id
+      })
+    } catch (error) {
+      if (error && (
+        error.code === "EVAULTUNAVAILABLE" ||
+        NO_LINK_CODES.has(error.code) ||
+        LOCK_CODES.has(error.code)
+      )) {
+        return { status: "unavailable" }
       }
-      throw e
+      throw error
+    }
+    if (storeStat) {
+      if (sameIdentity(storeStat, current)) return { status: "ready" }
+      return { status: "exists" }
     }
-    let st
     try {
-      st = await fs.promises.lstat(targetPath)
+      await fs.promises.link(filePath, storePath)
     } catch (error) {
-      if (isMissingError(error)) return { status: "stale" }
-      // rename() is the commit point: it succeeded with a temporary name
-      // whose identity was already verified. A later metadata read failure
-      // must not report the completed replacement as failed.
-      st = storeStat
+      if (NO_LINK_CODES.has(error && error.code)) {
+        return { status: "unavailable" }
+      }
+      throw error
     }
-    if (st.dev !== storeStat.dev || st.ino !== storeStat.ino) {
+    storeStat = await this.storeStatIfPresent(storePath, {
+      store_id: store.id
+    })
+    const after = await lstatIfPresent(filePath)
+    if (!storeStat ||
+        !after ||
+        !sameIdentity(storeStat, after) ||
+        !sameContentState(expected, after)) {
+      if (storeStat) await unlinkIfSame(storePath, storeStat)
       return { status: "stale" }
     }
-    this.registry.addLink(targetPath, {
-      hash, app: meta.app || null, source_id: meta.source_id || null,
-      dev: st.dev, ino: st.ino, mode: "link", batch_id: meta.batch_id || null
+    const existing = await this.registry.getFile(filePath)
+    await this.registry.upsertContent({
+      hash,
+      size: storeStat.size,
+      verified_at: Date.now(),
+      first_seen: Date.now()
     })
-    await this.refreshLinkSnapshots(hash, st.dev, st.ino)
-    this.registry.addSaved(storeStat.size)
-    await this.recordEvent({
-      kind: "convert", hash, path: targetPath, app: meta.app || null, source_id: meta.source_id || null,
-      bytes_saved: storeStat.size, batch_id: meta.batch_id || null
+    await this.registry.upsertAnchor({
+      store_id: store.id,
+      hash,
+      path: storePath,
+      verified_at: Date.now(),
+      dev: storeStat.dev,
+      ino: storeStat.ino,
+      size: storeStat.size,
+      mtime: storeStat.mtimeMs,
+      ctime: storeStat.ctimeMs,
+      nlink: storeStat.nlink,
+      mode: storeStat.mode,
+      uid: storeStat.uid,
+      gid: storeStat.gid
     })
-    return { status: "converted", bytes_saved: storeStat.size }
+    await this.registry.upsertFile(Object.assign({}, existing, {
+      path: filePath,
+      hash,
+      size: after.size,
+      mtime: after.mtimeMs,
+      ctime: after.ctimeMs,
+      dev: after.dev,
+      ino: after.ino,
+      source_id: existing && existing.source_id,
+      app: existing && existing.app,
+      status: "linked"
+    }))
+    await this.refreshInodeSnapshots(hash, after.dev, after.ino, store.id)
+    return { status: "ready", store_id: store.id }
   }
-  sourceAppIsRunning(source) {
-    if (!source || source.kind !== "app") return false
-    const appRoot = path.resolve(this.kernel.homedir, "api", source.app)
-    const api = this.kernel.api || {}
-    const running = api.running || {}
-    const runningPaths = api.running_paths || {}
-    return Object.keys(running).some((runningId) => {
-      if (!running[runningId]) return false
-      const runningPath = runningPaths[runningId] || (path.isAbsolute(runningId) ? runningId.split("?")[0] : null)
-      return !!(runningPath && isPathWithin(appRoot, runningPath))
-    })
+
+  async ensureAnchorForHash(hash, targetStat) {
+    const dev = targetStat.dev
+    const store = this.anchorStoreForDevice(dev)
+    if (!store) return { status: "unavailable" }
+    const storePath = this.storePathFor(hash, store.id)
+    let existingStore
+    try {
+      existingStore = await this.storeStatIfPresent(storePath, {
+        store_id: store.id
+      })
+      if (existingStore) await this.validateAnchorStore(store, dev)
+    } catch (error) {
+      if (error && (
+        error.code === "EVAULTPATH" ||
+        error.code === "EVAULTUNAVAILABLE" ||
+        NO_LINK_CODES.has(error.code) ||
+        LOCK_CODES.has(error.code)
+      )) {
+        return { status: "unavailable" }
+      }
+      throw error
+    }
+    if (existingStore) {
+      if (existingStore.dev !== dev) return { status: "unavailable" }
+      const verified = await this.verifyStoreContent(
+        hash, storePath, existingStore, store.id)
+      return verified.valid
+        ? { status: "ready", stat: existingStore, store_id: store.id }
+        : { status: "stale" }
+    }
+
+    const candidate = await this.registry.anchorCandidate(
+      hash,
+      dev,
+      targetStat.mode & 0o7777,
+      targetStat.uid,
+      targetStat.gid
+    )
+    if (!candidate) return { status: "no-source" }
+    const source = this.sourceForPath(candidate.path, candidate.source_id)
+    if (!source ||
+        !await this.canonicalPathIsWithinSource(candidate.path, source)) {
+      return { status: "stale" }
+    }
+    if (this.sourceAppIsRunning(source)) return { status: "locked" }
+    const before = await lstatIfPresent(candidate.path)
+    if (!before ||
+        !before.isFile() ||
+        !sameSnapshot(rowSnapshot(candidate), before)) {
+      return { status: "stale" }
+    }
+    const hashed = await this.hashFile(candidate.path)
+    const after = await lstatIfPresent(candidate.path)
+    if (!after ||
+        !sameSnapshot(fileSnapshot(before), after) ||
+        hashed.hash !== hash) {
+      return { status: "stale" }
+    }
+    const adopted = await this.adopt(
+      candidate.path, hash, fileSnapshot(after), store)
+    if (adopted.status !== "ready") return adopted
+    return {
+      status: "ready",
+      store_id: store.id,
+      stat: await this.storeStatIfPresent(storePath, {
+        store_id: store.id
+      })
+    }
   }
-  async deduplicateFile(filePath, options = {}) {
-    if (!this.enabled || typeof filePath !== "string" || !filePath) {
-      return { status: this.enabled ? "not-found" : "disabled" }
+
+  async convert(targetPath) {
+    const target = await this.registry.getFile(targetPath)
+    if (!target ||
+        target.unavailable_reason === "stale" ||
+        target.status !== "duplicate" ||
+        !target.hash) {
+      return { status: "not-found" }
+    }
+    const source = this.sourceForPath(target.path, target.source_id)
+    if (!source ||
+        !await this.canonicalPathIsWithinSource(target.path, source)) {
+      return { status: "stale" }
     }
-    await this.refreshSources()
-    return this.deduplicateExcludedFile(filePath, options)
-  }
-  async deduplicateExcludedFile(filePath, options = {}) {
-    const targetPath = path.resolve(filePath)
-    const excluded = this.registry.excluded.get(targetPath)
-    if (!excluded) return { status: "not-found" }
-    const source = this.sourceForPath(targetPath, excluded.source_id)
-    if (!source || !await this.canonicalPathIsWithinSource(targetPath, source)) {
+    if (this.sourceAppIsRunning(source)) return { status: "locked" }
+
+    let targetStat = await lstatIfPresent(target.path)
+    if (!targetStat ||
+        !targetStat.isFile() ||
+        !sameSnapshot(rowSnapshot(target), targetStat)) {
       return { status: "stale" }
     }
-    if (!source.shareable) return { status: "unavailable" }
-    if (this.sourceAppIsRunning(source)) return { status: "locked" }
+    const prepared = await this.ensureAnchorForHash(target.hash, targetStat)
+    if (prepared.status !== "ready") {
+      if (prepared.status === "unavailable") {
+        await this.reclassifyHashes([target.hash])
+      }
+      return prepared
+    }
+    const storePath = this.storePathFor(target.hash, prepared.store_id)
+    let storeStat = await this.storeStatIfPresent(
+      storePath, { store_id: prepared.store_id })
+    if (!storeStat) return { status: "stale" }
+    if (storeStat.dev !== targetStat.dev) {
+      return { status: "unavailable" }
+    }
+    if (sameIdentity(storeStat, targetStat)) {
+      await this.registry.upsertFile(Object.assign({}, target, {
+        status: "linked"
+      }))
+      return { status: "already", bytes_saved: 0 }
+    }
+    if (storeStat.size !== targetStat.size) {
+      return { status: "size-mismatch" }
+    }
+    if (!sameFileMetadata(storeStat, targetStat)) {
+      return { status: "metadata-mismatch" }
+    }
+    const verified = await this.verifyStoreContent(
+      target.hash, storePath, storeStat, prepared.store_id)
+    if (!verified.valid) return { status: "stale" }
+
+    const temporary = `${target.path}${TMP_SUFFIX}`
+    let temporaryStat = null
+    let committedStat = null
+    try {
+      await fs.promises.link(storePath, temporary)
+      temporaryStat = await fs.promises.lstat(temporary)
+      if (this.sourceAppIsRunning(source)) {
+        await unlinkIfSame(temporary, temporaryStat)
+        return { status: "locked" }
+      }
+      const [currentTarget, currentStore, currentTemporary] =
+        await Promise.all([
+          lstatIfPresent(target.path),
+          this.storeStatIfPresent(storePath, {
+            store_id: prepared.store_id
+          }),
+          lstatIfPresent(temporary)
+        ])
+      if (!currentTarget ||
+          !sameSnapshot(fileSnapshot(targetStat), currentTarget) ||
+          !currentStore ||
+          !currentTemporary ||
+          !sameIdentity(currentStore, currentTemporary) ||
+          !sameContentState(verified.snapshot, currentStore)) {
+        await unlinkIfSame(temporary, temporaryStat)
+        return { status: "stale" }
+      }
+      committedStat = temporaryStat
+      await fs.promises.rename(temporary, target.path)
+      temporaryStat = null
+    } catch (error) {
+      if (temporaryStat) {
+        await unlinkIfSame(temporary, temporaryStat).catch(() => {})
+      }
+      if (LOCK_CODES.has(error && error.code)) return { status: "locked" }
+      if (NO_LINK_CODES.has(error && error.code)) {
+        return { status: "unavailable" }
+      }
+      if (error && error.code === "EEXIST") return { status: "conflict" }
+      throw error
+    }
+
+    let finalStat
+    try {
+      finalStat = await fs.promises.lstat(target.path)
+    } catch (error) {
+      if (!committedStat) throw error
+      finalStat = committedStat
+    }
+    storeStat = await this.storeStatIfPresent(storePath, {
+      store_id: prepared.store_id
+    })
+    if (!storeStat || !sameIdentity(finalStat, storeStat)) {
+      return { status: "stale" }
+    }
+    await this.registry.upsertFile(Object.assign({}, target, {
+      size: finalStat.size,
+      mtime: finalStat.mtimeMs,
+      ctime: finalStat.ctimeMs,
+      dev: finalStat.dev,
+      ino: finalStat.ino,
+      status: "linked"
+    }))
+    await this.refreshInodeSnapshots(
+      target.hash, finalStat.dev, finalStat.ino, prepared.store_id)
+    return {
+      status: "converted",
+      bytes_saved: finalStat.size,
+      hash: target.hash,
+      path: target.path,
+      app: target.app,
+      source_id: target.source_id
+    }
+  }
+
+  async countActionFiles(status, scopeId = null) {
+    const sourceIds = this.scopeSourceIds(scopeId)
+    if (scopeId && !sourceIds.length) return 0
+    return this.registry.countActionFiles(status, sourceIds)
+  }
+
+  separateSelection(payload = {}) {
+    const scopeId = typeof payload.scope_id === "string" &&
+      payload.scope_id
+      ? payload.scope_id
+      : null
+    const locationId = typeof payload.location_id === "string" &&
+      payload.location_id
+      ? payload.location_id
+      : null
+    if (scopeId && !this._sourcesById.has(scopeId)) {
+      return { error: "That location is no longer available." }
+    }
+    if (locationId && !this._sourcesById.has(locationId)) {
+      return { error: "That location is no longer available." }
+    }
+    const view = STATUS_VIEWS.has(payload.view) ? payload.view : "all"
+    const statusFilter = STATUS_FILTERS.has(payload.status_filter)
+      ? payload.status_filter
+      : "all"
+    if (view !== "shared" &&
+        !(view === "all" &&
+          (statusFilter === "all" || statusFilter === "shared"))) {
+      return {
+        error: "The current view has no deduplicated files to separate."
+      }
+    }
+    const sourceIds = this.scopeSourceIds(scopeId, locationId)
+    if (!sourceIds.length) {
+      return { error: "That location is no longer available." }
+    }
+    return {
+      sourceIds,
+      query: String(payload.query || "").slice(0, 500).trim()
+    }
+  }
+
+  async deduplicateFile(filePath) {
+    const result = await this.convert(path.resolve(filePath))
+    if (result.status === "converted") {
+      if (!await this.recordEvent({
+        kind: "convert",
+        hash: result.hash,
+        app: result.app,
+        source_id: result.source_id,
+        bytes: result.bytes_saved,
+        files: 1
+      })) {
+        result.activity_warning = true
+      }
+    }
+    return result
+  }
+
+  deduplicationSummary() {
+    return {
+      converted: 0,
+      bytes_saved: 0,
+      locked: 0,
+      stale: 0,
+      incompatible: 0,
+      unavailable: 0,
+      failed: 0
+    }
+  }
+
+  addDeduplicationResult(summary, result) {
+    if (result.status === "converted") {
+      summary.converted += 1
+      summary.bytes_saved += result.bytes_saved || 0
+    } else if (result.status === "already") {
+      // Another selected path already caused this inode to be shared.
+    } else if (result.status === "locked") {
+      summary.locked += 1
+    } else if (result.status === "metadata-mismatch") {
+      summary.incompatible += 1
+    } else if (result.status === "unavailable") {
+      summary.unavailable += 1
+    } else {
+      summary.stale += 1
+    }
+  }
+
+  async recordDeduplicationSummary(
+    summary,
+    representative = null,
+    sourceId = null
+  ) {
+    if (!summary.converted) return
+    const event = {
+      kind: "convert",
+      bytes: summary.bytes_saved,
+      files: summary.converted
+    }
+    if (summary.converted === 1 && representative) {
+      event.hash = representative.hash
+      event.path = representative.path
+      event.app = representative.app
+      event.source_id = representative.source_id
+    } else if (sourceId) {
+      event.source_id = sourceId
+    }
+    if (!await this.recordEvent(event)) summary.activity_warning = true
+  }
+
+  async deduplicateFiles(filePaths, progress = null) {
+    const summary = Object.assign(this.deduplicationSummary(), {
+      results: []
+    })
+    let representative = null
+    let commonSourceId
+    for (const filePath of new Set(filePaths.map((item) =>
+      path.resolve(item)))) {
+      try {
+        const result = await this.convert(filePath)
+        this.addDeduplicationResult(summary, result)
+        if (result.status === "converted") {
+          if (!representative) representative = result
+          const sourceId = result.source_id || null
+          commonSourceId = commonSourceId === undefined
+            ? sourceId
+            : commonSourceId === sourceId ? commonSourceId : null
+        }
+        summary.results.push({ path: filePath, status: result.status })
+      } catch (error) {
+        summary.failed += 1
+        summary.results.push({ path: filePath, status: "failed" })
+      } finally {
+        if (progress) progress.files_completed += 1
+      }
+    }
+    await this.recordDeduplicationSummary(
+      summary,
+      representative,
+      commonSourceId
+    )
+    return summary
+  }
+
+  async deduplicateScope(scopeId = null, options = {}) {
+    const sourceIds = this.scopeSourceIds(scopeId)
+    const summary = this.deduplicationSummary()
+    if (scopeId && !sourceIds.length) return summary
+    let cursor = ""
+    while (true) {
+      const rows = await this.registry.fileBatch(
+        "duplicate", sourceIds, cursor, 100)
+      if (!rows.length) break
+      for (const row of rows) {
+        cursor = row.path
+        try {
+          const result = await this.convert(row.path)
+          this.addDeduplicationResult(summary, result)
+        } catch (error) {
+          summary.failed += 1
+        }
+        if (options.progress) options.progress.files_completed += 1
+      }
+    }
+    if (summary.converted) {
+      const scopedSource = scopeId
+        ? this._sources.find((source) => source.id === scopeId)
+        : null
+      await this.recordDeduplicationSummary(
+        summary,
+        null,
+        scopedSource && scopedSource.kind !== "virtual"
+          ? scopeId
+          : null
+      )
+    }
+    return summary
+  }
+
+  async copyOut(filePath, expected, source) {
+    const temporary = `${filePath}${TMP_SUFFIX}`
+    let temporaryStat = null
+    try {
+      await fs.promises.copyFile(
+        filePath, temporary, fs.constants.COPYFILE_EXCL)
+      if (Number.isFinite(expected.atimeMs) &&
+          Number.isFinite(expected.mtimeMs)) {
+        await fs.promises.utimes(
+          temporary,
+          new Date(expected.atimeMs),
+          new Date(expected.mtimeMs)
+        )
+      }
+      temporaryStat = await fs.promises.lstat(temporary)
+      if (this.sourceAppIsRunning(source)) {
+        await unlinkIfSame(temporary, temporaryStat)
+        return { status: "locked" }
+      }
+      const [current, currentTemporary] = await Promise.all([
+        lstatIfPresent(filePath),
+        lstatIfPresent(temporary)
+      ])
+      if (!current ||
+          !sameSnapshot(expected, current) ||
+          !sameIdentity(temporaryStat, currentTemporary)) {
+        await unlinkIfSame(temporary, temporaryStat)
+        return { status: "stale" }
+      }
+      await fs.promises.rename(temporary, filePath)
+      let finalStat
+      try {
+        finalStat = await fs.promises.lstat(filePath)
+      } catch (error) {
+        // rename() already committed the separate copy. Preserve that
+        // successful action if only the post-commit metadata read failed.
+        finalStat = temporaryStat
+      }
+      if (!sameIdentity(finalStat, temporaryStat)) {
+        return { status: "stale" }
+      }
+      temporaryStat = null
+      return {
+        status: "copied",
+        stat: finalStat
+      }
+    } catch (error) {
+      if (temporaryStat) {
+        await unlinkIfSame(temporary, temporaryStat).catch(() => {})
+      }
+      if (error && error.code === "EEXIST") return { status: "conflict" }
+      if (isMissingError(error)) return { status: "stale" }
+      if (LOCK_CODES.has(error && error.code)) return { status: "locked" }
+      throw error
+    }
+  }
 
-    const before = await lstatIfPresent(targetPath)
-    if (!before || !before.isFile()) return { status: "stale" }
-    let hashed
-    try {
-      hashed = await this.hashFile(targetPath)
-    } catch (error) {
+  async separate(filePath, options = {}) {
+    const entry = await this.registry.getFile(filePath)
+    if (!entry || entry.unavailable_reason === "stale") {
+      return { status: "not-found" }
+    }
+    const source = this.sourceForPath(entry.path, entry.source_id)
+    if (!source ||
+        !await this.canonicalPathIsWithinSource(entry.path, source)) {
       return { status: "stale" }
     }
-    const after = await lstatIfPresent(targetPath)
-    if (!sameSnapshot(fileSnapshot(before), after) || hashed.size !== after.size) {
+    const current = await lstatIfPresent(entry.path)
+    if (!current ||
+        !current.isFile() ||
+        !sameSnapshot(rowSnapshot(entry), current)) {
       return { status: "stale" }
     }
-    if (!this.registry.blobs.has(hashed.hash)) return { status: "no-match" }
-    if (!await this.canonicalPathIsWithinSource(targetPath, source)) return { status: "stale" }
-    const current = await lstatIfPresent(targetPath)
-    if (!sameSnapshot(fileSnapshot(after), current)) return { status: "stale" }
-
-    const result = await this.convert(targetPath, hashed.hash, {
-      app: source.kind === "app" ? source.app : null,
-      source_id: source.id,
-      batch_id: options.batch_id || `batch-${crypto.randomUUID()}`,
-      source,
-      expected: fileSnapshot(current)
-    })
-    if (result.status === "converted" || result.status === "already") {
-      this.registry.allowSharing(targetPath)
+    if (entry.status !== "linked") return { status: "not-found" }
+    if (this.sourceAppIsRunning(source)) return { status: "locked" }
+    const copied = await this.copyOut(
+      entry.path, current, source)
+    if (copied.status !== "copied") return copied
+    await this.registry.upsertFile(Object.assign(
+      {},
+      entry,
+      fileSnapshot(copied.stat),
+      {
+        status: "linked",
+        unavailable_reason: null
+      }
+    ))
+    await this.refreshInodeSnapshots(entry.hash, entry.dev, entry.ino)
+    if (options.reclassify !== false) {
+      await this.reclassifyHashes([entry.hash])
     }
+    const result = {
+      status: "detached",
+      bytes: entry.size,
+      hash: entry.hash
+    }
+    if (options.recordActivity !== false && !await this.recordEvent({
+      kind: "detach",
+      hash: entry.hash,
+      path: entry.path,
+      app: entry.app,
+      source_id: entry.source_id,
+      bytes: entry.size
+    })) result.activity_warning = true
     return result
   }
-  sourceIsWithinScope(source, scopeId) {
-    if (!scopeId) return true
-    const seen = new Set()
-    let current = source
-    while (current && !seen.has(current.id)) {
-      if (current.id === scopeId) return true
-      seen.add(current.id)
-      current = this._sources.find((item) => item.id === current.parent_id)
-    }
-    return false
-  }
-  async deduplicateSelection(selection, scopeId, options = {}) {
-    if (selection === "duplicates") {
-      return this.deduplicateScope(scopeId, Object.assign({}, options, { includeDescendants: true }))
-    }
-    await this.refreshSources()
-    if (scopeId && !this._sources.some((source) => source.id === scopeId)) {
-      return { error: "That location is no longer available. Scan again to refresh it." }
-    }
-    const paths = [...this.registry.excluded].filter(([filePath, entry]) => {
-      const source = this.sourceForPath(filePath, entry.source_id)
-      return source ? this.sourceIsWithinScope(source, scopeId) : !scopeId
-    }).map(([filePath]) => filePath)
-    if (options.progress) options.progress.files_total = paths.length
+
+  async separateFiles(filePaths, progress = null) {
     const summary = {
-      converted: 0, bytes_saved: 0, locked: 0, stale: 0, unmatched: 0,
-      incompatible: 0, unavailable: 0, failed: 0
-    }
-    const batch = options.batch_id || `batch-${crypto.randomUUID()}`
-    for (const filePath of paths) {
+      separated: 0,
+      bytes: 0,
+      failed: 0,
+      results: []
+    }
+    let separatedEntry = null
+    let commonSourceId
+    const affectedHashes = new Set()
+    for (const filePath of new Set(filePaths.map((item) =>
+      path.resolve(item)))) {
       try {
-        const result = await this.deduplicateExcludedFile(filePath, { batch_id: batch })
-        if (result.status === "converted" || result.status === "already") {
-          summary.converted += 1
-          summary.bytes_saved += result.bytes_saved || 0
-        } else if (result.status === "locked") {
-          summary.locked += 1
-        } else if (result.status === "stale") {
-          summary.stale += 1
-        } else if (result.status === "no-match" || result.status === "no-blob" ||
-            result.status === "size-mismatch") {
-          summary.unmatched += 1
-        } else if (result.status === "metadata-mismatch") {
-          summary.incompatible += 1
-        } else if (result.status === "unavailable" || result.status === "copy-mode") {
-          summary.unavailable += 1
+        const entry = await this.registry.getFile(filePath)
+        const result = entry && entry.status === "linked"
+          ? await this.separate(filePath, {
+              recordActivity: false,
+              reclassify: false
+            })
+          : { status: "ineligible" }
+        if (result.status === "detached") {
+          summary.separated += 1
+          summary.bytes += result.bytes || 0
+          separatedEntry = entry
+          affectedHashes.add(result.hash)
+          const entrySourceId = entry.source_id || null
+          commonSourceId = summary.separated === 1
+            ? entrySourceId
+            : commonSourceId === entrySourceId ? commonSourceId : null
         } else {
           summary.failed += 1
         }
+        summary.results.push({ path: filePath, status: result.status })
       } catch (error) {
         summary.failed += 1
+        summary.results.push({ path: filePath, status: "failed" })
+      } finally {
+        if (progress) progress.files_completed += 1
       }
-      if (options.progress) options.progress.files_completed += 1
     }
-    return summary
-  }
-  async deduplicateScope(scopeId, options = {}) {
-    await this.refreshSources()
-    const includeDescendants = options.includeDescendants === true
-    const source = scopeId
-      ? this._sources.find((item) => item.id === scopeId && (includeDescendants || item.kind !== "virtual"))
-      : null
-    if ((!includeDescendants || scopeId) && !source) {
-      return { error: "That location is no longer available. Scan again to refresh it." }
+    if (affectedHashes.size) {
+      await this.reclassifyHashes(affectedHashes)
     }
-    if (!includeDescendants) {
-      if (!source.shareable) return { error: "This location is on a disk that cannot share space with this vault." }
-      if (this.sourceAppIsRunning(source)) {
-        return { error: "This app has a running script. Stop it first, then deduplicate." }
-      }
-    }
-
-    const registry = this.registry
-    const batch = options.batch_id || `batch-${crypto.randomUUID()}`
-    const summary = { converted: 0, bytes_saved: 0, locked: 0, stale: 0, incompatible: 0, unavailable: 0, failed: 0 }
-    const staleHashes = new Set()
-    const entries = [...registry.duplicates]
-    const matchesScope = (currentSource) => currentSource && currentSource.shareable &&
-      (includeDescendants ? this.sourceIsWithinScope(currentSource, scopeId) : currentSource.id === scopeId)
-    if (options.progress) {
-      options.progress.files_total = entries.reduce((total, [filePath, entry]) => {
-        const currentSource = this.sourceForPath(filePath, entry.source_id)
-        return total + (matchesScope(currentSource) ? 1 : 0)
-      }, 0)
-    }
-    const completeProgress = () => {
-      if (options.progress) options.progress.files_completed += 1
-    }
-    for (const [filePath, entry] of entries) {
-      const currentSource = this.sourceForPath(filePath, entry.source_id)
-      if (!matchesScope(currentSource)) continue
-      if (!await this.canonicalPathIsWithinSource(filePath, currentSource)) {
-        summary.stale += 1
-        completeProgress()
-        continue
-      }
-      const indexed = registry.scanIndex.get(filePath)
-      const expected = indexed && indexed.hash === entry.hash
-        ? indexed
-        : (entry.dev !== undefined && entry.ino !== undefined &&
-            entry.mtime !== undefined && entry.ctime !== undefined ? entry : null)
-      if (!expected) {
-        summary.stale += 1
-        completeProgress()
-        continue
-      }
-      if (staleHashes.has(entry.hash)) {
-        summary.stale += 1
-        completeProgress()
-        continue
-      }
-      try {
-        const result = await this.convert(filePath, entry.hash, {
-          app: currentSource.kind === "app" ? currentSource.app : (entry.app || null),
-          source_id: currentSource.id,
-          batch_id: batch,
-          source: currentSource,
-          expected
-        })
-        if (result.status === "converted" || result.status === "already") {
-          summary.converted += 1
-          summary.bytes_saved += result.bytes_saved || 0
-        } else if (result.status === "locked") {
-          summary.locked += 1
-        } else if (result.status === "stale") {
-          summary.stale += 1
-        } else if (result.status === "stale-blob") {
-          staleHashes.add(entry.hash)
-          summary.stale += 1
-        } else if (result.status === "metadata-mismatch") {
-          entry.unavailable_reason = "metadata"
-          summary.incompatible += 1
-        } else if (result.status === "unavailable" || result.status === "copy-mode") {
-          summary.unavailable += 1
-        } else {
-          summary.failed += 1
-        }
-      } catch (error) {
-        summary.failed += 1
-      }
-      completeProgress()
+    const event = {
+      kind: "detach",
+      bytes: summary.bytes,
+      files: summary.separated
+    }
+    if (summary.separated === 1 && separatedEntry) {
+      event.hash = separatedEntry.hash
+      event.path = separatedEntry.path
+      event.app = separatedEntry.app
+      event.source_id = separatedEntry.source_id
+    } else if (commonSourceId) {
+      event.source_id = commonSourceId
+    }
+    if (summary.separated && !await this.recordEvent(event)) {
+      summary.activity_warning = true
     }
-    registry.schedulePersist()
     return summary
   }
-  // reclaim: delete an orphan's store name. Refuses when any app name remains.
-  async reclaim(hash, options = {}) {
-    if (!this.enabled) return { status: "disabled" }
-    const storePath = this.storePathFor(hash)
-    if (!this.registry.blobs.has(hash)) return { status: "not-found" }
-    const st = await this.storeStatIfPresent(storePath)
-    if (!st) {
-      const hasCopyNames = options.hasCopyNames === undefined
-        ? [...this.registry.links.values()].some((entry) => entry.hash === hash && entry.mode === "copy")
-        : options.hasCopyNames
-      if (hasCopyNames) return { status: "unavailable" }
-      if (!options.deferRegistry) this.registry.removeBlob(hash)
-      return options.deferRegistry ? { status: "gone", remove_hash: true } : { status: "gone" }
-    }
-    if (!st.isFile()) {
-      if (!options.deferRegistry) this.registry.removeBlob(hash)
-      return options.deferRegistry
-        ? { status: "invalid", remove_hash: true }
-        : { status: "invalid" }
-    }
-    if (st.nlink > 1) return { status: "in-use" }
-    await fs.promises.unlink(storePath)
-    if (!options.deferRegistry) this.registry.removeBlob(hash)
-    await this.recordEvent({ kind: "reclaim", hash, bytes_saved: st.size })
-    return options.deferRegistry
-      ? { status: "reclaimed", bytes_freed: st.size, remove_hash: true }
-      : { status: "reclaimed", bytes_freed: st.size }
-  }
-  // Startup registry verification (trigger 5): bounded by registry size,
-  // never a discovery walk. Prunes dead links, flags orphans, removes stray
-  // conversion tmp files, re-adopts blobs whose store name was deleted.
-  async verify(options = {}) {
-    if (!this.enabled || !this.registry) return
-    const preservePath = options.preservePath || (() => false)
-    const includePath = options.includePath || (() => true)
-    const handleAccessError = (error, filePath) => !!(
-      isAccessError(error) && options.onAccessError && options.onAccessError(error, filePath)
-    )
-    if (options.reconcile !== false) this.reconcileConfiguredSources()
-    for (const [linkPath, entry] of [...this.registry.links]) {
-      if (!includePath(linkPath)) continue
-      if (preservePath(linkPath)) continue
-      try {
-        const source = this.sourceForPath(linkPath, entry.source_id)
-        const managedPath = source && await this.canonicalPathIsWithinSource(linkPath, source, { strictErrors: true })
-        if (!managedPath) {
-          this.registry.untrack(linkPath)
-          continue
-        }
-        const st = await lstatIfPresent(linkPath)
-        if (!st || !st.isFile() || st.ino !== entry.ino || st.dev !== entry.dev) {
-          this.registry.untrack(linkPath)
-        }
-      } catch (error) {
-        if (!handleAccessError(error, linkPath)) throw error
-      }
-    }
-    for (const [dupPath, entry] of [...this.registry.duplicates]) {
-      if (!includePath(dupPath)) continue
-      if (preservePath(dupPath)) continue
-      let valid = false
-      try {
-        const source = this.sourceForPath(dupPath, entry.source_id)
-        const st = await lstatIfPresent(dupPath)
-        valid = !!(source && st && st.isFile() &&
-          await this.canonicalPathIsWithinSource(dupPath, source, { strictErrors: true }))
-      } catch (error) {
-        if (handleAccessError(error, dupPath)) continue
-        throw error
-      }
-      if (!valid) {
-        this.registry.untrack(dupPath)
-        continue
+
+  async separateMatchingFiles(selection, progress = null) {
+    const summary = {
+      separated: 0,
+      bytes: 0,
+      failed: 0,
+      cancelled: false
+    }
+    let separatedEntry = null
+    let commonSourceId
+    let cursor = ""
+    while (true) {
+      if (this.fileActionCancelRequested) {
+        summary.cancelled = true
+        break
       }
-      const storeStat = await this.storeStatIfPresent(this.storePathFor(entry.hash))
-      if (storeStat && storeStat.isFile()) {
-        await unlinkIfSame(dupPath + TMP_SUFFIX, storeStat)
-      }
-    }
-    if (options.verifyBlobs === false) {
-      this.registry.schedulePersist()
-      return
-    }
-    const linksByHash = new Map()
-    for (const [linkPath, entry] of this.registry.links) {
-      if (!linksByHash.has(entry.hash)) linksByHash.set(entry.hash, [])
-      linksByHash.get(entry.hash).push([linkPath, entry])
-    }
-    const invalidBlobs = new Set()
-    for (const [hash, blob] of [...this.registry.blobs]) {
-      const storePath = this.storePathFor(hash)
-      const st = await this.storeStatIfPresent(storePath)
-      if (!st) {
-        const names = linksByHash.get(hash) || []
-        const copyNames = names.filter(([, entry]) => entry.mode === "copy")
-        // Deleting a name changes ctime, so trusted re-adoption compares the
-        // preserved identity, size, and mtime. Changed or legacy-unsnapshotted
-        // content waits for the next explicit scan instead of being assigned a
-        // stale hash filename during startup.
-        let readopted = false
-        let inaccessibleName = false
-        for (const [linkPath, entry] of names) {
-          if (entry.mode !== "link") continue
-          if (preservePath(linkPath)) {
-            inaccessibleName = true
-            continue
-          }
-          let source
-          let linkStat
-          try {
-            source = this.sourceForPath(linkPath, entry.source_id)
-            if (!source || !await this.canonicalPathIsWithinSource(linkPath, source, { strictErrors: true })) continue
-            linkStat = await lstatIfPresent(linkPath)
-          } catch (error) {
-            if (!handleAccessError(error, linkPath)) throw error
-            inaccessibleName = true
-            continue
-          }
-          const expected = this.registry.scanIndex.get(linkPath)
-          if (!linkStat || !expected || expected.hash !== hash ||
-              entry.dev !== linkStat.dev || entry.ino !== linkStat.ino ||
-              !sameContentState(expected, linkStat)) continue
-          const before = fileSnapshot(linkStat)
-          let created = false
-          try {
-            await this.storeStatIfPresent(storePath, { createParent: true })
-            await fs.promises.link(linkPath, storePath)
-            created = true
-          } catch (error) {
-            if (!error || error.code !== "EEXIST") throw error
-            const currentStore = await this.storeStatIfPresent(storePath)
-            const currentLink = await lstatIfPresent(linkPath)
-            if (!currentStore || !sameContentState(before, currentLink) ||
-                currentStore.dev !== linkStat.dev || currentStore.ino !== linkStat.ino) continue
-          }
-          const [currentLink, currentStore] = await Promise.all([
-            lstatIfPresent(linkPath),
-            this.storeStatIfPresent(storePath)
-          ])
-          if (!sameContentState(before, currentLink) || !currentStore ||
-              currentStore.dev !== linkStat.dev || currentStore.ino !== linkStat.ino) {
-            const ownsStoreName = created && currentStore && (
-              (currentStore.dev === linkStat.dev && currentStore.ino === linkStat.ino) ||
-              (currentLink && currentStore.dev === currentLink.dev && currentStore.ino === currentLink.ino)
-            )
-            if (ownsStoreName) await fs.promises.unlink(storePath)
-            continue
-          }
-          await this.refreshLinkSnapshots(hash, linkStat.dev, linkStat.ino)
-          readopted = true
+      const rows = await this.registry.fileBatch(
+        "linked",
+        selection.sourceIds,
+        cursor,
+        100,
+        selection.query
+      )
+      if (!rows.length) break
+      const affectedHashes = new Set()
+      for (const row of rows) {
+        if (this.fileActionCancelRequested) {
+          summary.cancelled = true
           break
         }
-        // On a volume without file sharing support, copy-mode names are the
-        // durable content group. They remain useful for duplicate discovery
-        // even though there is no canonical file in the vault tree.
-        if (readopted || copyNames.length || inaccessibleName) {
-          blob.orphan = false
-          blob.verified_at = inaccessibleName && !readopted ? null : Date.now()
-        } else {
-          invalidBlobs.add(hash)
+        cursor = row.path
+        try {
+          const entry = await this.registry.getFile(row.path)
+          const result = entry && entry.status === "linked"
+            ? await this.separate(row.path, {
+                recordActivity: false,
+                reclassify: false
+              })
+            : { status: "ineligible" }
+          if (result.status === "detached") {
+            summary.separated += 1
+            summary.bytes += result.bytes || 0
+            separatedEntry = entry
+            affectedHashes.add(result.hash)
+            const entrySourceId = entry.source_id || null
+            commonSourceId = summary.separated === 1
+              ? entrySourceId
+              : commonSourceId === entrySourceId ? commonSourceId : null
+          } else {
+            summary.failed += 1
+          }
+        } catch (error) {
+          summary.failed += 1
+        } finally {
+          if (progress) progress.files_completed += 1
         }
-        continue
       }
-      if (!st.isFile()) {
-        invalidBlobs.add(hash)
-        continue
+      if (affectedHashes.size) {
+        await this.reclassifyHashes(affectedHashes)
       }
-      blob.orphan = st.nlink === 1
-      blob.verified_at = Date.now()
-    }
-    this.registry.removeBlobs(invalidBlobs)
-    this.registry.schedulePersist()
-  }
-  // Rebuild derived state from disk: store filenames are hashes, stat gives
-  // nlink, and (dev, ino) matching re-associates app paths. The replacement
-  // maps are assembled off to the side and swapped in only after the walk so
-  // a long repair never persists a half-reset registry.
-  async rebuild(roots, options = {}) {
-    if (!this.enabled) return
-    const registry = this.registry
-    const preserveState = options.preserveState !== false
-    const preserved = preserveState ? {
-      blobs: new Map(registry.blobs),
-      links: new Map(registry.links),
-      excluded: new Map(registry.excluded),
-      totals: Object.assign({}, registry.totals),
-      lastScan: registry.lastScan ? Object.assign({}, registry.lastScan) : null,
-      sourceScans: new Map([...registry.sourceScans].map(([id, scan]) => [id, Object.assign({}, scan)])),
-      duplicates: new Map(registry.duplicates),
-      scanIndex: new Map(registry.scanIndex)
-    } : null
-    const rebuiltBlobs = new Map()
-    const rebuiltLinks = new Map()
-    const storeInoToHash = new Map()
-    let shards = []
+      if (summary.cancelled) break
+    }
+    const event = {
+      kind: "detach",
+      bytes: summary.bytes,
+      files: summary.separated
+    }
+    if (summary.separated === 1 && separatedEntry) {
+      event.hash = separatedEntry.hash
+      event.path = separatedEntry.path
+      event.app = separatedEntry.app
+      event.source_id = separatedEntry.source_id
+    } else if (commonSourceId) {
+      event.source_id = commonSourceId
+    }
+    if (summary.separated && !await this.recordEvent(event)) {
+      summary.activity_warning = true
+    }
+    return summary
+  }
+
+  async reclaim(hash, storeId = null) {
+    if (typeof hash !== "string" || !SHA256_RE.test(hash)) {
+      return { status: "not-found" }
+    }
+    const anchors = await this.registry.anchorsForHash(hash)
+    const anchor = storeId
+      ? anchors.find((item) => item.store_id === storeId)
+      : anchors.length === 1 ? anchors[0] : null
+    if (!anchor) return { status: "not-found" }
+    const store = this._anchorStoresById.get(anchor.store_id)
+    if (!store) return { status: "unavailable" }
+    const storePath = this.storePathFor(hash, store.id)
+    if (!samePath(storePath, anchor.path)) return { status: "stale" }
     try {
-      shards = await fs.promises.readdir(this.blobRoot, { withFileTypes: true })
+      await this.validateAnchorStore(store, anchor.dev)
     } catch (error) {
-      if (!isMissingError(error)) throw error
+      return { status: "stale" }
     }
-    for (const shardEntry of shards) {
-      if (!shardEntry.isDirectory() || shardEntry.isSymbolicLink() ||
-          !/^[0-9a-f]{2}$/.test(shardEntry.name)) continue
-      const shard = shardEntry.name
-      const shardPath = path.resolve(this.blobRoot, shard)
-      if (!await this.directoryIfSafe(shardPath)) continue
-      let names = []
-      try {
-        names = await fs.promises.readdir(shardPath)
-      } catch (error) {
-        if (isMissingError(error)) continue
-        throw error
-      }
-      for (const name of names) {
-        if (!SHA256_RE.test(name) || !name.startsWith(shard)) continue
+    const stat = await this.storeStatIfPresent(storePath, {
+      store_id: store.id
+    })
+    if (!stat) {
+      await this.registry.removeAnchor(store.id, hash)
+      return { status: "gone" }
+    }
+    const expected = {
+      size: anchor.size,
+      mtime: anchor.mtime,
+      ctime: anchor.ctime,
+      dev: anchor.dev,
+      ino: anchor.ino
+    }
+    if (!sameSnapshot(expected, stat)) return { status: "stale" }
+    if (stat.nlink !== 1) return { status: "in-use" }
+    await fs.promises.unlink(storePath)
+    await this.registry.removeAnchor(store.id, hash)
+    const hasFiles = await this.registry.hasFilesForHash(hash)
+    const remainingAnchors = await this.registry.anchorsForHash(hash)
+    if (!hasFiles && !remainingAnchors.length) {
+      await this.registry.removeContent(hash)
+    }
+    const result = { status: "reclaimed", bytes_freed: stat.size }
+    if (!await this.recordEvent({
+      kind: "reclaim",
+      hash,
+      bytes: stat.size
+    })) result.activity_warning = true
+    return result
+  }
+
+  async reclaimAll() {
+    const summary = { reclaimed: 0, bytes_freed: 0, failed: 0 }
+    let cursor = { store_id: "", hash: "" }
+    while (true) {
+      const anchors = await this.registry.reclaimableBatch(cursor, 100)
+      if (!anchors.length) break
+      for (const row of anchors) {
+        cursor = { store_id: row.store_id, hash: row.hash }
         try {
-          const st = await fs.promises.lstat(path.resolve(this.blobRoot, shard, name))
-          if (!st.isFile()) continue
-          const previous = registry.blobs.get(name)
-          rebuiltBlobs.set(name, {
-            size: st.size,
-            first_seen: previous && previous.first_seen ? previous.first_seen : Date.now(),
-            source_urls: previous && Array.isArray(previous.source_urls) ? [...previous.source_urls] : [],
-            verified_at: Date.now(),
-            orphan: st.nlink === 1
-          })
-          storeInoToHash.set(`${st.dev}:${st.ino}`, name)
+          const result = await this.reclaim(row.hash, row.store_id)
+          if (result.status === "reclaimed") {
+            summary.reclaimed += 1
+            summary.bytes_freed += result.bytes_freed || 0
+            if (result.activity_warning) summary.activity_warning = true
+          } else if (!["gone", "in-use"].includes(result.status)) {
+            summary.failed += 1
+          }
         } catch (error) {
-          if (!isMissingError(error)) throw error
+          summary.failed += 1
         }
       }
     }
-    await this.refreshSources()
-    const walkRoots = roots
-      ? roots.map((root) => typeof root === "string" ? { root, source_id: null } : root)
-      : this.scanRoots()
-    for (const entry of walkRoots) {
-      await this.walkForInoMatch(
-        entry.root,
-        storeInoToHash,
-        entry.source_id === "pinokio" ? null : entry.source_id,
-        rebuiltLinks
-      )
-    }
-    const rebuiltDuplicates = new Map()
-    const rebuiltScanIndex = new Map()
-    const trustedHashes = new Set()
-    if (preserved) {
-      // Copy-mode content has no store inode to rediscover. Preserve only names
-      // whose exact scan snapshot still proves the recorded content group.
-      for (const [linkPath, link] of preserved.links) {
-        if (link.mode !== "copy" || preserved.excluded.has(linkPath)) continue
-        const blob = preserved.blobs.get(link.hash)
-        const expected = preserved.scanIndex.get(linkPath)
-        const source = this.sourceForPath(linkPath, link.source_id)
-        if (!blob || !expected || expected.hash !== link.hash || !source ||
-            !await this.canonicalPathIsWithinSource(linkPath, source, { strictErrors: true })) continue
-        try {
-          const st = await fs.promises.lstat(linkPath)
-          if (!st.isFile() || st.size < this.sizeThreshold ||
-              link.dev !== st.dev || link.ino !== st.ino ||
-              !sameSnapshot(expected, st)) continue
-          if (!rebuiltBlobs.has(link.hash)) {
-            rebuiltBlobs.set(link.hash, Object.assign({}, blob, {
-              size: st.size,
-              verified_at: Date.now(),
-              orphan: false
-            }))
-          }
-          rebuiltLinks.set(linkPath, Object.assign({}, link, {
-            app: source.kind === "app" ? source.app : (link.app || null),
-            source_id: source.id,
-            dev: st.dev,
-            ino: st.ino,
-            mode: "copy"
-          }))
-        } catch (error) {
-          if (!isMissingError(error)) throw error
-        }
+    return summary
+  }
+
+  async scanForScope(scopeId) {
+    const direct = await this.registry.scanFor(scopeId)
+    const key = scopeId || ""
+    if (direct || !scopeId) {
+      if (direct) this.lastScanCache.set(key, direct)
+      else this.lastScanCache.delete(key)
+      return direct
+    }
+    const global = await this.registry.scanFor()
+    if (global) this.lastScanCache.set("", global)
+    else this.lastScanCache.delete("")
+    if (!global ||
+        !global.source_files ||
+        !Object.prototype.hasOwnProperty.call(
+          global.source_files, scopeId)) {
+      this.lastScanCache.delete(key)
+      return null
+    }
+    const scoped = Object.assign({}, global, {
+      files: global.source_files[scopeId] || 0,
+      bytes_total: global.source_bytes[scopeId] || 0,
+      hash_failures: global.source_hash_failures
+        ? global.source_hash_failures[scopeId] || 0
+        : 0
+    })
+    const sourceIds = new Set(this.scopeSourceIds(scopeId))
+    scoped.exclusions = Array.isArray(global.exclusions)
+      ? global.exclusions.filter((entry) =>
+        entry && sourceIds.has(entry.source_id))
+      : []
+    scoped.partial = scoped.exclusions.length > 0
+    scoped.outcome = scoped.partial
+      ? "completed_with_exclusions"
+      : "complete"
+    this.lastScanCache.set(key, scoped)
+    return scoped
+  }
+
+  sourceCountMaps(summaryRows) {
+    const counts = {
+      all: {},
+      duplicates: {},
+      shareable: {}
+    }
+    const add = (target, sourceIdValue, amount) => {
+      let current = this._sourcesById.get(sourceIdValue)
+      const seen = new Set()
+      while (current && !seen.has(current.id)) {
+        target[current.id] = (target[current.id] || 0) + amount
+        seen.add(current.id)
+        current = current.parent_id
+          ? this._sourcesById.get(current.parent_id)
+          : null
       }
-      // A store filename is only a trustworthy content hash when at least one
-      // surviving name still matches the snapshot captured when that content
-      // was hashed. Repair itself never hashes, so unverified names are left
-      // without a scan-index entry and the next manual scan hashes them once.
-      for (const [linkPath, link] of rebuiltLinks) {
-        const expected = preserved.scanIndex.get(linkPath)
-        if (!expected || expected.hash !== link.hash) continue
-        try {
-          const st = await fs.promises.lstat(linkPath)
-          if (sameSnapshot(expected, st)) trustedHashes.add(link.hash)
-        } catch (error) {
-          if (!isMissingError(error)) throw error
-        }
+    }
+    for (const row of summaryRows) {
+      const amount = Number(row.file_count) || 0
+      if (!["reference", "duplicate", "linked", "unavailable"]
+        .includes(row.status)) continue
+      add(counts.all, row.source_id, amount)
+      if (row.status === "duplicate" || row.status === "unavailable") {
+        add(counts.duplicates, row.source_id, amount)
       }
-      for (const [linkPath, link] of rebuiltLinks) {
-        if (!trustedHashes.has(link.hash)) continue
-        try {
-          const st = await fs.promises.lstat(linkPath)
-          rebuiltScanIndex.set(linkPath, {
-            hash: link.hash, size: st.size, dev: st.dev, ino: st.ino,
-            mtime: st.mtimeMs, ctime: st.ctimeMs,
-            source_id: link.source_id || null
-          })
-        } catch (error) {
-          if (!isMissingError(error)) throw error
-        }
+      if (row.status === "duplicate") {
+        add(counts.shareable, row.source_id, amount)
       }
-      for (const [duplicatePath, duplicate] of preserved.duplicates) {
-        if (preserved.excluded.has(duplicatePath) || rebuiltLinks.has(duplicatePath) ||
-            !rebuiltBlobs.has(duplicate.hash) || !trustedHashes.has(duplicate.hash) ||
-            !this.sourceForPath(duplicatePath, duplicate.source_id)) continue
-        try {
-          const source = this.sourceForPath(duplicatePath, duplicate.source_id)
-          if (!await this.canonicalPathIsWithinSource(duplicatePath, source, { strictErrors: true })) continue
-          const st = await fs.promises.lstat(duplicatePath)
-          const indexed = preserved.scanIndex.get(duplicatePath)
-          const expected = indexed && indexed.hash === duplicate.hash ? indexed : duplicate
-          if (st.isFile() && sameSnapshot(expected, st)) {
-            rebuiltDuplicates.set(duplicatePath, Object.assign({}, duplicate, {
-              size: st.size, dev: st.dev, ino: st.ino, mtime: st.mtimeMs, ctime: st.ctimeMs
-            }))
-            rebuiltScanIndex.set(duplicatePath, {
-              hash: duplicate.hash, size: st.size, dev: st.dev, ino: st.ino,
-              mtime: st.mtimeMs, ctime: st.ctimeMs,
-              source_id: duplicate.source_id || expected.source_id || null
-            })
-          }
-        } catch (error) {
-          if (!isMissingError(error)) throw error
-        }
+    }
+    return counts
+  }
+
+  publicFileItems(page) {
+    const hashSiblings = new Map()
+    for (const sibling of page.hashSiblings || []) {
+      if (!hashSiblings.has(sibling.hash)) {
+        hashSiblings.set(sibling.hash, [])
+      }
+      hashSiblings.get(sibling.hash).push(sibling)
+    }
+    const inodeSiblings = new Map()
+    for (const sibling of page.inodeSiblings || []) {
+      const key = `${sibling.dev}:${sibling.ino}`
+      if (!inodeSiblings.has(key)) inodeSiblings.set(key, [])
+      inodeSiblings.get(key).push(sibling)
+    }
+    return (page.rows || []).map((row) => {
+      const sampledMatches = row.status === "linked"
+        ? inodeSiblings.get(`${row.dev}:${row.ino}`) || []
+        : hashSiblings.get(row.hash) || []
+      const allMatches = [
+        row,
+        ...sampledMatches.filter((match) => match.path !== row.path)
+      ]
+      const locations = allMatches.map((match) =>
+        Object.assign({
+          path: match.path,
+          app: match.app,
+          dev: match.dev,
+          ino: match.ino
+        }, this.locationForPath(match.path, match.source_id)))
+      const publicStatus = {
+        reference: "tracked",
+        duplicate: "duplicate",
+        unavailable: "duplicate",
+        linked: "shared"
+      }[row.status]
+      const result = Object.assign({
+        path: row.path,
+        hash: row.hash,
+        size: row.size,
+        app: row.app,
+        status: publicStatus,
+        shareable: row.status === "duplicate",
+        unavailable_reason: row.status === "unavailable"
+          ? row.unavailable_reason || "different_disk"
+          : null,
+        location_count: sampledMatches.length
+          ? Number(sampledMatches[0].location_count) || 1
+          : 1,
+        locations
+      }, this.locationForPath(row.path, row.source_id))
+      if (row.status === "duplicate" || row.status === "unavailable") {
+        const match = allMatches.find((candidate) =>
+          candidate.path !== row.path)
+        result.match = match
+          ? Object.assign({
+            path: match.path,
+            app: match.app
+          }, this.locationForPath(match.path, match.source_id))
+          : null
       }
-      for (const excludedPath of preserved.excluded.keys()) {
-        rebuiltLinks.delete(excludedPath)
-        rebuiltScanIndex.delete(excludedPath)
-      }
-    }
-    const rebuiltByIno = new Map()
-    const rebuiltPathsByIno = new Map()
-    for (const [linkPath, entry] of rebuiltLinks) {
-      const key = registry.inoKey(entry.dev, entry.ino)
-      rebuiltByIno.set(key, entry.hash)
-      if (!rebuiltPathsByIno.has(key)) rebuiltPathsByIno.set(key, new Set())
-      rebuiltPathsByIno.get(key).add(linkPath)
-    }
-    registry.replaceState({
-      blobs: rebuiltBlobs,
-      links: rebuiltLinks,
-      scanIndex: rebuiltScanIndex,
-      duplicates: rebuiltDuplicates,
-      excluded: preserved ? preserved.excluded : new Map(),
-      lastScan: preserved ? preserved.lastScan : null,
-      sourceScans: preserved ? preserved.sourceScans : new Map(),
-      totals: preserved ? preserved.totals : { lifetime_bytes_saved: 0 },
-      byIno: rebuiltByIno,
-      pathsByIno: rebuiltPathsByIno
+      return result
     })
-    if (options.flush !== false) await registry.flush()
-  }
-  async walkForInoMatch(root, storeInoToHash, preferredSourceId = null, outputLinks = null) {
-    const vaultRoot = path.resolve(this.root)
-    for await (const batch of walkBatches(root, {
-      concurrency: this.dirConcurrency,
-      skipDirectory: (full) => full === vaultRoot,
-      strictErrors: true
-    })) {
-      const files = batch.flatMap((group) => group.files.map((file) => file.path))
-      const stats = await statMany(files, this.statConcurrency, null, {
-        strictErrors: true,
-        followSymlinks: false
-      })
-      for (let index = 0; index < files.length; index++) {
-        const st = stats[index]
-        if (!st || !st.isFile() || st.size < this.sizeThreshold) continue
-        const hash = storeInoToHash.get(`${st.dev}:${st.ino}`)
-        if (hash) {
-          const source = this.sourceForPath(files[index], preferredSourceId)
-          const previous = this.registry.links.get(files[index])
-          const batchId = previous && previous.hash === hash && previous.mode === "link" &&
-            previous.dev === st.dev && previous.ino === st.ino
-            ? previous.batch_id || null
-            : null
-          const link = {
-            hash, app: source && source.kind === "app" ? source.app : null,
-            source_id: source ? source.id : null, dev: st.dev, ino: st.ino,
-            mode: "link", created: Date.now(),
-            batch_id: batchId
-          }
-          if (outputLinks) outputLinks.set(files[index], link)
-          else this.registry.addLink(files[index], link)
-        }
-      }
+  }
+
+  publicDuplicateGroupItems(page) {
+    return (page.rows || []).map((row) => Object.assign({
+      kind: "duplicate_group",
+      hash: row.hash,
+      path: row.representative_path,
+      size: Number(row.size) || 0,
+      total_count: Number(row.total_count) || 0,
+      eligible_count: Number(row.eligible_count) || 0,
+      can_save: Number(row.can_save) || 0,
+      app: row.representative_app || null
+    }, this.locationForPath(
+      row.representative_path,
+      row.representative_source_id
+    )))
+  }
+
+  publicDuplicateChildItems(rows) {
+    const publicStatus = {
+      reference: "tracked",
+      duplicate: "duplicate",
+      unavailable: "duplicate",
+      linked: "shared"
+    }
+    return (rows || []).map((row) => Object.assign({
+      kind: "duplicate_path",
+      path: row.path,
+      hash: row.hash,
+      size: Number(row.size) || 0,
+      app: row.app || null,
+      status: publicStatus[row.status],
+      registry_status: row.status,
+      shareable: row.status === "duplicate",
+      selectable: !!row.selectable,
+      unavailable_reason: row.status === "unavailable"
+        ? row.unavailable_reason || "different_disk"
+        : null
+    }, this.locationForPath(row.path, row.source_id)))
+  }
+
+  async duplicateGroupChildren(scopeId, hash, options = {}) {
+    if (typeof hash !== "string" || !SHA256_RE.test(hash)) {
+      throw new TypeError("Invalid vault content identifier.")
+    }
+    const locationId = typeof options.location_id === "string" &&
+      options.location_id
+      ? options.location_id
+      : null
+    const query = String(options.query || "").slice(0, 500).trim()
+    const cursor = typeof options.cursor === "string"
+      ? options.cursor.slice(0, 2048)
+      : ""
+    const pageSize = boundedInteger(
+      options.page_size, 100, 1, STATUS_PAGE_SIZE)
+    const result = await this.registry.duplicateGroupChildren({
+      hash,
+      sourceIds: this.scopeSourceIds(scopeId),
+      activeSourceIds: this.scopeSourceIds(scopeId, locationId),
+      query,
+      cursor,
+      pageSize,
+      unrestricted: !scopeId,
+      activeUnrestricted: !scopeId && !locationId
+    })
+    return {
+      hash,
+      items: this.publicDuplicateChildItems(result.rows),
+      total: Number(result.total) || 0,
+      next_cursor: result.nextCursor || null
     }
   }
-  cloudSyncProvider() {
-    const home = path.resolve(this.kernel.homedir || "").replace(/\\/g, "/").toLowerCase()
-    if (home.includes("/onedrive") || home.includes("/one drive")) return "OneDrive"
-    if (home.includes("/dropbox")) return "Dropbox"
-    if (home.includes("/library/mobile documents/") || home.includes("/icloud drive/")) return "iCloud Drive"
-    return null
+
+  async duplicateGroupSelection(scopeId, hash, options = {}) {
+    if (typeof hash !== "string" || !SHA256_RE.test(hash)) {
+      throw new TypeError("Invalid vault content identifier.")
+    }
+    const locationId = typeof options.location_id === "string" &&
+      options.location_id
+      ? options.location_id
+      : null
+    const result = await this.registry.duplicateGroupSelection({
+      hash,
+      sourceIds: this.scopeSourceIds(scopeId, locationId),
+      query: String(options.query || "").slice(0, 500).trim(),
+      unrestricted: !scopeId && !locationId
+    })
+    return {
+      hash,
+      paths: result.paths || [],
+      exceeded: !!result.exceeded
+    }
   }
-  // Global state for the vault page and the health endpoint. Answered from
-  // memory + one stat per blob and occupied shard; never a walk.
-  async status(scopeId = null) {
+
+  async status(scopeId = null, options = {}) {
     if (!this.enabled || !this.registry) return { enabled: false }
-    const registry = this.registry
-    const scope = scopeId ? this.scanSource(scopeId) : null
-    if (scopeId && !scope) throw new Error("That location is no longer available.")
-    const scopeHashes = scopeId ? new Set() : null
-    if (scopeHashes) {
-      for (const entry of registry.links.values()) {
-        if (entry.source_id === scopeId) scopeHashes.add(entry.hash)
-      }
-      for (const entry of registry.duplicates.values()) {
-        if (entry.source_id === scopeId) scopeHashes.add(entry.hash)
-      }
-    }
-    const blobs = []
-    const blobByHash = new Map()
-    const storeStats = new Map()
-    const namesByHash = new Map()
-    const undoBatchMap = new Map()
-    for (const [linkPath, entry] of registry.links) {
-      if (scopeHashes && !scopeHashes.has(entry.hash)) continue
-      if (!namesByHash.has(entry.hash)) namesByHash.set(entry.hash, [])
-      const location = this.locationForPath(linkPath, entry.source_id)
-      namesByHash.get(entry.hash).push(Object.assign({
-        path: linkPath, app: entry.app || null, mode: entry.mode
-      }, location))
-      if (entry.batch_id && (!scopeId || entry.source_id === scopeId)) {
-        if (!undoBatchMap.has(entry.batch_id)) {
-          undoBatchMap.set(entry.batch_id, { batch_id: entry.batch_id, files: 0, bytes: 0, ts: null })
-        }
-        const batch = undoBatchMap.get(entry.batch_id)
-        const blob = registry.blobs.get(entry.hash)
-        batch.files += 1
-        batch.bytes += blob && Number.isFinite(blob.size) ? blob.size : 0
-      }
-    }
-    const pendingBytesByHash = new Map()
-    for (const entry of registry.duplicates.values()) {
-      if (scopeId && entry.source_id !== scopeId) continue
-      pendingBytesByHash.set(entry.hash, (pendingBytesByHash.get(entry.hash) || 0) + (entry.size || 0))
-    }
-    const blobEntries = [...registry.blobs].filter(([hash]) => !scopeHashes || scopeHashes.has(hash))
-    if (!await this.directoryIfSafe(this.root) || !await this.directoryIfSafe(this.blobRoot)) {
-      throw unsafeStoragePath(this.blobRoot)
-    }
-    const storePaths = blobEntries.map(([hash]) => this.storePathFor(hash))
-    await Promise.all([...new Set(storePaths.map((storePath) => path.dirname(storePath)))]
-      .map((shard) => this.directoryIfSafe(shard)))
-    const blobStats = await statMany(
-      storePaths,
-      this.statConcurrency,
-      null,
-      { strictErrors: true, followSymlinks: false }
+    const view = STATUS_VIEWS.has(options.view) ? options.view : "all"
+    const groupDuplicates =
+      view === "duplicates" && options.display_mode === "files"
+    const statusFilter = STATUS_FILTERS.has(options.status_filter)
+      ? options.status_filter
+      : "all"
+    const query = String(options.query || "").slice(0, 500).trim()
+    const cursor = typeof options.cursor === "string"
+      ? options.cursor.slice(0, 2048)
+      : ""
+    const pageSize = boundedInteger(
+      options.page_size, STATUS_PAGE_SIZE, 1, STATUS_PAGE_SIZE)
+    const requestedPage = boundedInteger(
+      options.page, 0, 0, Number.MAX_SAFE_INTEGER)
+    const locationId = typeof options.location_id === "string" &&
+      options.location_id
+      ? options.location_id
+      : null
+    const scopeSourceIds = this.scopeSourceIds(scopeId)
+    const locationSourceIds = this.scopeSourceIds(
+      scopeId,
+      locationId
     )
-    let bytesOnDisk = 0
-    let wouldBe = 0
-    let trackedLogicalBytes = 0
-    for (let index = 0; index < blobEntries.length; index++) {
-      const [hash, blob] = blobEntries[index]
-      const names = namesByHash.get(hash) || []
-      const apps = new Set(names.map((name) => name.app).filter(Boolean))
-      const storeStat = blobStats[index] && blobStats[index].isFile() ? blobStats[index] : null
-      const nlink = storeStat ? storeStat.nlink : null
-      storeStats.set(hash, storeStat)
-      const size = blob.size || 0
-      const linkedCopy = storeStat || names.some((name) => name.mode === "link") ? 1 : 0
-      const physicalCopies = linkedCopy + names.filter((name) => name.mode === "copy").length
-      const pendingBytes = pendingBytesByHash.get(hash) || 0
-      trackedLogicalBytes += (size * names.length) + pendingBytes
-      bytesOnDisk += (size * physicalCopies) + pendingBytes
-      wouldBe += (size * Math.max(physicalCopies, names.length)) + pendingBytes
-      const orphan = !!(storeStat && storeStat.nlink === 1)
-      const publicBlob = {
-        hash, size: blob.size || 0, orphan, nlink,
-        names, apps: [...apps], source_urls: blob.source_urls || []
-      }
-      blobs.push(publicBlob)
-      blobByHash.set(hash, publicBlob)
-    }
-    if (!scopeId) {
-      // The scan total covers every regular file, including files below the
-      // candidate threshold and files the user kept separate. The registry
-      // figures above cover only content tracked by Save space. Add the
-      // remainder to both sides so the global comparison represents the
-      // complete scanned locations instead of silently omitting small files.
-      const lastScan = registry.scanFor()
-      const scannedBytes = lastScan && Number.isFinite(lastScan.bytes_total)
-        ? lastScan.bytes_total
-        : null
-      const untrackedScannedBytes = scannedBytes === null
-        ? 0
-        : Math.max(0, scannedBytes - trackedLogicalBytes)
-      bytesOnDisk += untrackedScannedBytes
-      wouldBe += untrackedScannedBytes
-    }
-    const duplicates = []
-    for (const [p, entry] of registry.duplicates) {
-      if (scopeId && entry.source_id !== scopeId) continue
-      const location = this.locationForPath(p, entry.source_id)
-      const source = this.sourceForPath(p, location.source_id)
-      const index = registry.scanIndex.get(p)
-      const storeStat = storeStats.get(entry.hash)
-      const shareable = !!(source && source.shareable && storeStat && !entry.unavailable_reason &&
-        (!index || index.dev === undefined || index.dev === storeStat.dev))
-      let unavailableReason = entry.unavailable_reason || null
-      if (!shareable && !unavailableReason) {
-        unavailableReason = source && storeStat && index && index.dev !== undefined && index.dev !== storeStat.dev
-          ? "different_disk"
-          : "unsupported_disk"
-      }
-      const blob = blobByHash.get(entry.hash)
-      const match = blob ? blob.names.find((name) => name.path !== p) || null : null
-      duplicates.push(Object.assign({
-        path: p, hash: entry.hash, size: entry.size || 0, app: entry.app || null,
-        shareable, unavailable_reason: unavailableReason, match
-      }, location))
-    }
-    const events = (await registry.readEvents()).reverse()
-      .filter((event) => !scopeId || event.source_id === scopeId)
-      .map((event) => {
-      const currentLocation = event.path ? this.locationForPath(event.path, event.source_id) : null
-      const fallbackLocation = currentLocation && currentLocation.source_id
-        ? currentLocation
-        : (event.path ? { relative_path: event.path } : {})
-      const publicEvent = Object.assign({}, fallbackLocation, event)
-      if (event.kind === "convert" && event.batch_id && event.path) {
-        const current = registry.links.get(event.path)
-        publicEvent.undoable = !!(current && (
-          current.batch_id === event.batch_id ||
-          (!current.batch_id && current.hash === event.hash)
-        ))
-        const batch = undoBatchMap.get(event.batch_id)
-        if (batch && Number.isFinite(event.ts)) {
-          batch.ts = Math.max(batch.ts || 0, event.ts)
-        }
-      }
-      return publicEvent
+    const snapshot = await this.registry.statusSnapshot({
+      scopeSourceIds,
+      locationSourceIds,
+      scoped: !!scopeId,
+      scopeUnrestricted: !scopeId,
+      locationUnrestricted: !scopeId && !locationId,
+      view,
+      statusFilter,
+      query,
+      pageSize,
+      sizeSort: groupDuplicates
+        ? options.size_sort || "desc"
+        : options.size_sort,
+      groupDuplicates,
+      cursor
     })
-    const undoBatches = [...undoBatchMap.values()].sort((a, b) =>
-      (b.ts || 0) - (a.ts || 0) || a.batch_id.localeCompare(b.batch_id))
-    const scan = this.scanStatus()
-    const excluded = []
-    for (const [p, meta] of registry.excluded) {
-      if (scopeId && meta.source_id !== scopeId) continue
-      excluded.push(Object.assign({
-        path: p,
-        ts: meta.ts || null,
-        size: Number(meta.size) || 0
-      }, this.locationForPath(p, meta.source_id)))
-    }
-    const publicSources = this._sources.filter((source) => !scopeId || source.id === scopeId).map((source) => ({
-      id: source.id, kind: source.kind, label: source.label, root: source.root,
-      display_path: source.kind === "pinokio" ? source.root : (source.mount_path || source.root),
-      target_path: source.kind === "external" ? source.root : null,
-      parent_id: scopeId ? null : source.parent_id, app: source.app || null,
-      available: source.available !== false, shareable: source.kind === "virtual" ? null : !!source.shareable
-    }))
+    let items
+    if (view === "activity") {
+      items = (snapshot.page.rows || []).map((event) => Object.assign(
+        {},
+        event.path
+          ? this.locationForPath(event.path, event.source_id)
+          : {},
+        event
+      ))
+    } else if (view === "reclaimable") {
+      items = snapshot.page.rows || []
+    } else if (groupDuplicates) {
+      items = this.publicDuplicateGroupItems(snapshot.page)
+    } else {
+      items = this.publicFileItems(snapshot.page)
+    }
+
+    const lastScan = await this.scanForScope(scopeId)
+    const before = lastScan && Number.isFinite(lastScan.bytes_total)
+      ? lastScan.bytes_total
+      : 0
+    const saved = Math.max(0, Number(snapshot.saved) || 0)
+    const currentCount = Number(snapshot.total) || 0
+    const pageTotal = Number(snapshot.pageTotal) || 0
+    const pages = Math.max(1, Math.ceil(pageTotal / pageSize))
+    const publicSources = this._sources
+      .filter((source) => !scopeId || source.id === scopeId)
+      .map((source) => ({
+        id: source.id,
+        kind: source.kind,
+        label: source.label,
+        root: source.root,
+        display_path: source.root,
+        target_path: source.kind === "external" ? source.root : null,
+        parent_id: scopeId ? null : source.parent_id,
+        app: source.app || null,
+        available: source.available !== false,
+        shareable: source.kind === "virtual" ? null : !!source.shareable,
+        removable: source.kind === "external" &&
+          source.configured === true
+      }))
+    const sourceCounts = this.sourceCountMaps(snapshot.scopeRows)
     const result = {
       enabled: true,
       mode: this.mode,
-      scan,
-      last_scan: registry.scanFor(scopeId),
-      bytes_on_disk: bytesOnDisk,
-      bytes_without_sharing: wouldBe,
-      saved_by_sharing: wouldBe - bytesOnDisk,
-      lifetime_bytes_saved: registry.totals.lifetime_bytes_saved,
-      reclaimable: blobs.filter((b) => b.orphan).reduce((sum, b) => sum + b.size, 0),
-      pending_bytes: duplicates.filter((d) => d.shareable).reduce((sum, d) => sum + d.size, 0),
+      scan: this.scanStatus(),
+      last_scan: lastScan,
+      bytes_without_sharing: before,
+      bytes_on_disk: Math.max(0, before - saved),
+      saved_by_sharing: saved,
+      effective_bytes: Math.max(0, before - saved),
+      reclaimable: Number(snapshot.reclaimable) || 0,
+      pending_bytes: Number(snapshot.pending) || 0,
       file_action: this.fileActionStatus(scopeId),
-      activity_error: registry.eventError,
-      cloud_sync_warning: this.cloudSyncProvider(),
-      sources: publicSources, blobs, duplicates, excluded, events,
-      undo_batches: undoBatches
-    }
-    if (scopeId) {
-      const duplicateBytes = duplicates.reduce((sum, item) => sum + item.size, 0)
-      const excludedBytes = excluded.reduce((sum, item) => sum + item.size, 0)
-      let linkedBytes = 0
-      let effectiveLinkedBytes = 0
-      let sharedBytes = 0
-      for (const blob of blobs) {
-        const scopedNames = blob.names.filter((name) => name.source_id === scopeId)
-        const scopedLinks = scopedNames.filter((name) => name.mode === "link").length
-        const scopedCopies = scopedNames.length - scopedLinks
-        const registeredLinks = blob.names.filter((name) => name.mode === "link").length
-        // The store name is one hardlink but not a user-visible location.
-        // Registry count prevents stale filesystem metadata from over-attributing the inode.
-        const filesystemLinks = Number.isFinite(blob.nlink) ? Math.max(0, blob.nlink - 1) : 0
-        const sharingLocations = Math.max(1, registeredLinks, filesystemLinks)
-        linkedBytes += blob.size * scopedNames.length
-        effectiveLinkedBytes += (blob.size * scopedCopies) +
-          (blob.size * scopedLinks / sharingLocations)
-        if (registeredLinks >= 2) sharedBytes += blob.size * scopedLinks
-      }
-      const trackedBytes = linkedBytes + duplicateBytes + excludedBytes
-      const effectiveTrackedBytes = effectiveLinkedBytes + duplicateBytes + excludedBytes
-      const folderBytes = result.last_scan && Number.isFinite(result.last_scan.bytes_total)
-        ? result.last_scan.bytes_total
-        : null
-      result.scope_id = scopeId
-      result.tracked_bytes = trackedBytes
-      result.effective_bytes = folderBytes === null
-        ? null
-        : Math.max(0, folderBytes - trackedBytes) + effectiveTrackedBytes
-      result.shared_bytes = sharedBytes
-      result.reclaimable = 0
-    }
+      sources: publicSources,
+      items,
+      inventory: {
+        view,
+        counts: snapshot.counts,
+        source_counts: sourceCounts,
+        shareable_by_source: sourceCounts.shareable,
+        shareable_duplicates:
+          Number(snapshot.shareableDuplicates) || 0,
+        duplicate_locations:
+          Number(snapshot.duplicateLocations) || 0,
+        current: {
+          count: currentCount,
+          locations: Number(snapshot.currentLocations) || 0,
+          shareable_bytes:
+            Number(snapshot.currentShareableBytes) || 0,
+          deduplicate_bytes:
+            Number(snapshot.currentDeduplicateBytes) || 0,
+          separate_count:
+            Number(snapshot.currentSeparateCount) || 0,
+          separate_bytes:
+            Number(snapshot.currentSeparateBytes) || 0
+        },
+        page: requestedPage,
+        page_size: pageSize,
+        start: requestedPage * pageSize,
+        end: Math.min(
+          (requestedPage * pageSize) + items.length,
+          pageTotal
+        ),
+        total: pageTotal,
+        pages,
+        cursor: cursor || null,
+        next_cursor: snapshot.page.nextCursor || null,
+        has_previous: requestedPage > 0,
+        has_next: !!snapshot.page.nextCursor
+      }
+    }
+    if (scopeId) result.scope_id = scopeId
     return result
   }
+
   scanStatus() {
-    const sweeper = this.sweeper
-    if (!sweeper) return null
-    const pending = !!this.scanPromise && !sweeper.state.active
+    if (!this.sweeper) return null
+    const pending = !!this.scanPromise && !this.sweeper.state.active
     const state = pending
-      ? Object.assign(sweeper.idleState(), { phase: "queued", scope_id: this.scanScopeId })
-      : sweeper.state
+      ? Object.assign(this.sweeper.idleState(), {
+        phase: "queued",
+        scope_id: this.scanScopeId
+      })
+      : this.sweeper.state
     return Object.assign({}, state, {
-      current_file: sweeper.currentHash ? path.basename(sweeper.currentHash.path) : null,
-      current_file_bytes: sweeper.currentHash ? sweeper.currentHash.bytes : null,
-      current_file_size: sweeper.currentHash ? sweeper.currentHash.size : null,
+      current_file: this.sweeper.currentHash
+        ? path.basename(this.sweeper.currentHash.path)
+        : null,
+      current_file_bytes: this.sweeper.currentHash
+        ? this.sweeper.currentHash.bytes
+        : null,
+      current_file_size: this.sweeper.currentHash
+        ? this.sweeper.currentHash.size
+        : null,
       pending,
       error: this.scanError
     })
   }
+
   fileActionStatus(scopeId = null) {
     const progress = this.fileActionProgress
     if (!progress) return null
-    if (scopeId) {
-      if (progress.scope_id && progress.scope_id !== scopeId) return null
-      if (progress.path) {
-        const source = this.sourceForPath(progress.path)
-        if (!source || source.id !== scopeId) return null
-      }
-    }
+    if (scopeId && progress.scope_id &&
+        progress.scope_id !== scopeId) return null
     return Object.assign({}, progress)
   }
-  progressStatus(scopeId = null) {
+
+  async progressStatus(scopeId = null) {
     return {
       enabled: !!this.enabled,
       scan: this.scanStatus(),
       file_action: this.fileActionStatus(scopeId),
-      last_scan: this.registry ? this.registry.scanFor(scopeId) : null
-    }
-  }
-  async copyOut(filePath, sourcePath, expectedTarget, expectedSource = expectedTarget, options = {}) {
-    const tmp = filePath + TMP_SUFFIX
-    let copiedStat = null
-    try {
-      await fs.promises.copyFile(sourcePath, tmp, fs.constants.COPYFILE_EXCL)
-      copiedStat = await fs.promises.lstat(tmp)
-      if (options.canReplace && !options.canReplace()) {
-        await unlinkIfSame(tmp, copiedStat)
-        return { status: "locked" }
-      }
-      const currentTarget = await lstatIfPresent(filePath)
-      const currentSource = sourcePath === filePath ? currentTarget : await lstatIfPresent(sourcePath)
-      const currentTmp = await lstatIfPresent(tmp)
-      if (!currentTarget || !currentSource || !sameSnapshot(expectedTarget, currentTarget) ||
-          !sameSnapshot(expectedSource, currentSource) || !sameIdentity(currentTmp, copiedStat)) {
-        await unlinkIfSame(tmp, copiedStat)
-        return { status: "stale" }
-      }
-      await fs.promises.rename(tmp, filePath)
-      let finalStat
-      try {
-        finalStat = await lstatIfPresent(filePath)
-      } catch (error) {
-        // The independent copy was committed by rename(). Preserve that
-        // completed action when only the post-commit metadata read failed.
-        finalStat = copiedStat
-      }
-      if (!finalStat || finalStat.dev !== copiedStat.dev || finalStat.ino !== copiedStat.ino) {
-        return { status: "stale" }
-      }
-      copiedStat = null
-      return { status: "copied", stat: finalStat }
-    } catch (error) {
-      await unlinkIfSame(tmp, copiedStat).catch(() => {})
-      if (error && error.code === "EEXIST") return { status: "conflict" }
-      if (isMissingError(error)) return { status: "stale" }
-      throw error
-    }
-  }
-  // detach: make one name an independent copy again ("go back"), and pin it
-  // so future scans neither re-list nor re-share it. Works on linked names
-  // (copies bytes out) and on pending duplicates (just ignores them).
-  async detach(filePath) {
-    if (!this.enabled) return { status: "disabled" }
-    await this.refreshSources()
-    const entry = this.registry.links.get(filePath)
-    if (entry) {
-      const source = this.sourceForPath(filePath, entry.source_id)
-      if (!source || !await this.canonicalPathIsWithinSource(filePath, source)) {
-        return { status: "stale" }
-      }
-      if (entry.mode === "copy") {
-        const st = await lstatIfPresent(filePath)
-        if (!st || !st.isFile() || st.dev !== entry.dev || st.ino !== entry.ino) return { status: "stale" }
-        this.registry.exclude(filePath, {
-          ts: Date.now(), source_id: entry.source_id || null, size: st.size
-        })
-        await this.recordEvent({
-          kind: "skip", hash: entry.hash, path: filePath,
-          app: entry.app || null, source_id: entry.source_id || null, size: st.size
-        })
-        return { status: "ignored" }
-      }
-      if (this.sourceAppIsRunning(source)) return { status: "locked" }
-      const before = await lstatIfPresent(filePath)
-      if (!before || !before.isFile() || before.dev !== entry.dev || before.ino !== entry.ino) return { status: "stale" }
-      const copied = await this.copyOut(filePath, filePath, fileSnapshot(before), fileSnapshot(before), {
-        canReplace: () => !this.sourceAppIsRunning(source)
-      })
-      if (copied.status !== "copied") return copied
-      const st = copied.stat
-      this.registry.exclude(filePath, { ts: Date.now(), source_id: entry.source_id || null, size: st.size })
-      await this.refreshLinkSnapshots(entry.hash, entry.dev, entry.ino)
-      await this.recordEvent({ kind: "detach", hash: entry.hash, path: filePath, app: entry.app || null, source_id: entry.source_id || null, size: st.size })
-      return { status: "detached" }
-    }
-    if (this.registry.duplicates.has(filePath)) {
-      const dup = this.registry.duplicates.get(filePath)
-      this.registry.exclude(filePath, { ts: Date.now(), source_id: dup.source_id || null, size: dup.size || 0 })
-      await this.recordEvent({ kind: "skip", hash: dup.hash, path: filePath, app: dup.app || null, source_id: dup.source_id || null, size: dup.size || 0 })
-      return { status: "ignored" }
-    }
-    return { status: "not-found" }
-  }
-  // Undo a conversion batch: replace each converted name with an independent
-  // copy of the bytes (spec, UX contract surface 3).
-  async undoBatch(batchId) {
-    if (!this.enabled || !batchId) return { undone: 0 }
-    await this.refreshSources()
-    const events = await this.registry.readEvents()
-    const conversionEvents = new Map(events
-      .filter((event) => event.kind === "convert" && event.batch_id === batchId && event.path)
-      .map((event) => [event.path, event]))
-    const targets = new Set(conversionEvents.keys())
-    for (const [filePath, entry] of this.registry.links) {
-      if (entry.batch_id === batchId) targets.add(filePath)
-    }
-    const summary = { undone: 0, bytes: 0, failed: 0 }
-    for (const filePath of targets) {
-      const event = conversionEvents.get(filePath) || {}
-      const entry = this.registry.links.get(filePath)
-      if (!entry || (entry.batch_id && entry.batch_id !== batchId) ||
-          (event.hash && entry.hash !== event.hash)) continue
-      const storePath = this.storePathFor(entry.hash)
-      try {
-        const source = this.sourceForPath(filePath, entry.source_id || event.source_id)
-        if (!source || !await this.canonicalPathIsWithinSource(filePath, source)) {
-          summary.failed += 1
-          continue
-        }
-        if (this.sourceAppIsRunning(source)) {
-          summary.failed += 1
-          continue
-        }
-        const st = await fs.promises.lstat(filePath)
-        const storeStat = await this.storeStatIfPresent(storePath)
-        if (!st.isFile() || !storeStat || !storeStat.isFile()) {
-          summary.failed += 1
-          continue
-        }
-        if (st.ino !== storeStat.ino || st.dev !== storeStat.dev ||
-            st.dev !== entry.dev || st.ino !== entry.ino) {
-          summary.failed += 1
-          continue
-        }
-        const copied = await this.copyOut(filePath, storePath, fileSnapshot(st), fileSnapshot(storeStat), {
-          canReplace: () => !this.sourceAppIsRunning(source)
-        })
-        if (copied.status !== "copied") {
-          summary.failed += 1
-          continue
-        }
-        const independentStat = copied.stat
-        const duplicateEntry = {
-          hash: entry.hash, size: storeStat.size, app: entry.app || null,
-          source_id: entry.source_id || event.source_id || null, discovered: Date.now(),
-          dev: independentStat.dev, ino: independentStat.ino,
-          mtime: independentStat.mtimeMs, ctime: independentStat.ctimeMs
-        }
-        const scanEntry = {
-          hash: entry.hash, size: independentStat.size,
-          dev: independentStat.dev, ino: independentStat.ino,
-          mtime: independentStat.mtimeMs, ctime: independentStat.ctimeMs,
-          source_id: entry.source_id || event.source_id || null
-        }
-        this.registry.setDuplicate(filePath, duplicateEntry, scanEntry)
-        await this.refreshLinkSnapshots(entry.hash, entry.dev, entry.ino)
-        const bytesSaved = event.bytes_saved || storeStat.size
-        this.registry.totals.lifetime_bytes_saved = Math.max(0,
-          this.registry.totals.lifetime_bytes_saved - bytesSaved)
-        await this.recordEvent({
-          kind: "undo", hash: entry.hash, path: filePath,
-          source_id: entry.source_id || event.source_id || null, batch_id: batchId,
-          bytes_saved: bytesSaved
-        })
-        summary.undone += 1
-        summary.bytes += storeStat.size
-      } catch (e) {
-        summary.failed += 1
-      }
-    }
-    this.registry.schedulePersist()
-    return summary
-  }
-  async reclaimAll() {
-    if (!this.enabled) return { reclaimed: 0, bytes_freed: 0 }
-    const summary = { reclaimed: 0, bytes_freed: 0, failed: 0 }
-    const removedHashes = new Set()
-    const copyHashes = new Set([...this.registry.links.values()]
-      .filter((entry) => entry.mode === "copy")
-      .map((entry) => entry.hash))
-    try {
-      for (const [hash] of [...this.registry.blobs]) {
-        const result = await this.reclaim(hash, {
-          deferRegistry: true,
-          hasCopyNames: copyHashes.has(hash)
-        })
-        if (result.remove_hash) removedHashes.add(hash)
-        if (result.status === "reclaimed") {
-          summary.reclaimed += 1
-          summary.bytes_freed += result.bytes_freed || 0
-        } else if (!["gone", "in-use", "unavailable"].includes(result.status)) summary.failed += 1
-      }
-    } finally {
-      this.registry.removeBlobs(removedHashes)
+      last_scan: this.lastScanCache.get(scopeId || "") || null
     }
-    return summary
   }
 }
 
-Vault.SIZE_THRESHOLD = SIZE_THRESHOLD
-Vault.TMP_SUFFIX = TMP_SUFFIX
-
 module.exports = Vault