pinokiod 8.0.36 → 8.0.38

package/kernel/vault/index.js

@@ -0,0 +1,820 @@
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+const { Worker } = require('worker_threads')
+const Registry = require('./registry')
+const Sweeper = require('./sweeper')
+
+// 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 SIZE_THRESHOLD = 100 * 1024 * 1024
+const TMP_SUFFIX = ".pinokio-dedup-tmp"
+const NO_LINK_CODES = new Set(["EXDEV", "ENOTSUP", "EPERM", "ENOSYS"])
+const LOCK_CODES = new Set(["EBUSY", "EPERM", "EACCES"])
+const STAT_CONCURRENCY = 32
+
+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 samePath = (left, right) => {
+  const a = path.resolve(left)
+  const b = path.resolve(right)
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
+const sourceId = (kind, name) => `${kind}:${encodeURIComponent(name)}`
+
+const statMany = async (paths, concurrency = STAT_CONCURRENCY) => {
+  const results = new Array(paths.length)
+  let cursor = 0
+  const workers = Array.from({ length: Math.min(concurrency, paths.length) }, async () => {
+    while (cursor < paths.length) {
+      const index = cursor++
+      try {
+        results[index] = await fs.promises.stat(paths[index])
+      } catch (error) {
+        results[index] = null
+      }
+    }
+  })
+  await Promise.all(workers)
+  return results
+}
+
+class Vault {
+  constructor(kernel) {
+    this.kernel = kernel
+    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.registry = null
+    this.worker = null
+    this.workerJobs = new Map()
+    this.workerSeq = 0
+    this.workerStarts = 0
+    this.workerIdleTimer = null
+    this.workerIdleMs = 750
+    this.statConcurrency = STAT_CONCURRENCY
+    this.sizeThreshold = SIZE_THRESHOLD
+    this._sources = []
+  }
+  get root() {
+    return path.resolve(this.kernel.homedir, "vault")
+  }
+  get blobRoot() {
+    return path.resolve(this.root, "sha256")
+  }
+  storePathFor(hash) {
+    return path.resolve(this.blobRoot, hash.slice(0, 2), hash)
+  }
+  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
+    try { storeDev = (await fs.promises.stat(this.root)).dev } catch (e) {}
+    const decorate = async (source) => {
+      if (!source.root) return source
+      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"
+      } catch (e) {
+        source.available = false
+        source.shareable = false
+      }
+      return source
+    }
+
+    let apiEntries = []
+    try { apiEntries = await fs.promises.readdir(apiRoot, { withFileTypes: true }) } catch (e) {}
+    const seenExternalRoots = new Set()
+    for (const entry of apiEntries) {
+      const mountPath = path.resolve(apiRoot, entry.name)
+      if (entry.isSymbolicLink()) {
+        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", entry.name), kind: "external", label: entry.name,
+            root: canonical, mount_path: mountPath, parent_id: "external"
+          }))
+        } catch (e) {}
+      } else 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"
+        }))
+      }
+    }
+
+    let homeEntries = []
+    try { homeEntries = await fs.promises.readdir(home, { withFileTypes: true }) } catch (e) {}
+    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
+    return sources
+  }
+  sources() {
+    return this._sources
+  }
+  async addExternalSource(folderPath) {
+    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)
+    let canonicalHome = home
+    try { canonicalHome = path.resolve(await fs.promises.realpath(home)) } catch (error) {}
+    if (isPathWithin(canonicalHome, canonical) || isPathWithin(canonical, canonicalHome)) {
+      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 apiRoot = path.resolve(home, "api")
+    await fs.promises.mkdir(apiRoot, { recursive: true })
+    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(apiRoot, label)
+      try {
+        await fs.promises.symlink(canonical, candidate, this.kernel.platform === "win32" ? "junction" : "dir")
+        mountPath = candidate
+        break
+      } 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 (!mountPath) throw new Error("Pinokio could not create a unique name for that folder.")
+
+    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 was added but could not be loaded. Restart Pinokio and try again.")
+    return { created: true, source }
+  }
+  sourceForPath(filePath, preferredId) {
+    const sources = this._sources || []
+    if (preferredId) {
+      const preferred = sources.find((source) => source.id === preferredId)
+      if (preferred) return preferred
+    }
+    const absolute = path.resolve(filePath)
+    const concrete = sources.filter((source) => source.root && source.kind !== "virtual")
+      .filter((source) => isPathWithin(source.root, absolute) || (source.mount_path && isPathWithin(source.mount_path, absolute)))
+      .sort((a, b) => Math.max((b.root || "").length, (b.mount_path || "").length) -
+        Math.max((a.root || "").length, (a.mount_path || "").length))
+    return concrete[0] || sources.find((source) => source.id === "pinokio") || null
+  }
+  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
+    }
+  }
+  scanRoots() {
+    const home = path.resolve(this.kernel.homedir)
+    const roots = [{ root: home, source_id: "pinokio" }]
+    const seen = new Set([home])
+    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) || seen.has(canonical)) continue
+      seen.add(canonical)
+      roots.push({ root: canonical, source_id: source.id })
+    }
+    return roots
+  }
+  // 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 (e) {}
+    }
+    return String(value).toLowerCase() !== "false"
+  }
+  // Disabled ⇒ do nothing observable: no directory, no registry, no probes.
+  async init() {
+    this.enabled = await this.isEnabled()
+    if (!this.enabled) return { enabled: false }
+    await fs.promises.mkdir(this.blobRoot, { recursive: true })
+    this.registry = new Registry(this.root)
+    this.mode = await this.probe(this.root)
+    await this.refreshSources()
+    const loaded = await this.registry.load()
+    if (loaded.corrupt) {
+      await this.rebuild(undefined, { preserveState: false })
+    }
+    this.sweeper = new Sweeper(this)
+    this.initialized = true
+    return { enabled: true, mode: this.mode, corrupt_recovered: !!loaded.corrupt }
+  }
+  // Capability probe: temp file + node:fs.link + nlink check. Once per volume.
+  async probe(dir) {
+    let dev
+    try {
+      dev = (await fs.promises.stat(dir)).dev
+      if (this.volumeModes.has(dev)) return this.volumeModes.get(dev)
+    } catch (e) {
+      return "copy"
+    }
+    const a = path.resolve(dir, `.pinokio-probe-${crypto.randomBytes(6).toString("hex")}`)
+    const b = a + "-link"
+    let mode = "copy"
+    try {
+      await fs.promises.writeFile(a, "probe")
+      await fs.promises.link(a, b)
+      const st = await fs.promises.stat(b)
+      if (st.nlink === 2) mode = "link"
+    } catch (e) {
+    } finally {
+      await fs.promises.unlink(a).catch(() => {})
+      await fs.promises.unlink(b).catch(() => {})
+    }
+    this.volumeModes.set(dev, mode)
+    return mode
+  }
+  async hashFile(filePath) {
+    if (this.workerIdleTimer) {
+      clearTimeout(this.workerIdleTimer)
+      this.workerIdleTimer = null
+    }
+    if (!this.worker) {
+      const worker = new Worker(path.resolve(__dirname, "hash_worker.js"))
+      this.worker = worker
+      this.workerStarts += 1
+      worker.unref()
+      worker.on("message", ({ id, hash, size, error }) => {
+        const job = this.workerJobs.get(id)
+        if (!job) return
+        this.workerJobs.delete(id)
+        if (error) job.reject(new Error(error))
+        else 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
+            if (this.workerJobs.size === 0 && this.worker === worker) {
+              this.worker = null
+              worker.terminate().catch(() => {})
+            }
+          }, this.workerIdleMs)
+          if (this.workerIdleTimer.unref) this.workerIdleTimer.unref()
+        }
+      })
+      worker.on("error", (error) => {
+        if (this.worker !== worker) return
+        if (this.workerIdleTimer) clearTimeout(this.workerIdleTimer)
+        this.workerIdleTimer = null
+        for (const job of this.workerJobs.values()) job.reject(error)
+        this.workerJobs.clear()
+        this.worker = null
+      })
+      worker.on("exit", (code) => {
+        if (this.worker !== worker) return
+        if (this.workerIdleTimer) clearTimeout(this.workerIdleTimer)
+        this.workerIdleTimer = null
+        for (const job of this.workerJobs.values()) {
+          job.reject(new Error(`hash worker exited with code ${code}`))
+        }
+        this.workerJobs.clear()
+        this.worker = null
+      })
+    }
+    const id = ++this.workerSeq
+    return new Promise((resolve, reject) => {
+      this.workerJobs.set(id, { resolve, reject })
+      this.worker.postMessage({ id, filePath })
+    })
+  }
+  // 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.stat(filePath)
+    const linkEntry = {
+      hash,
+      app: meta.app || null,
+      source_id: meta.source_id || null,
+      dev: st.dev,
+      ino: st.ino,
+      mode: "link"
+    }
+    let storeStat = null
+    try {
+      storeStat = await fs.promises.stat(storePath)
+    } catch (e) {}
+    if (storeStat) {
+      if (storeStat.dev === st.dev && storeStat.ino === st.ino) {
+        this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
+        this.registry.addLink(filePath, linkEntry)
+        return { status: "already" }
+      }
+      return { status: "duplicate", storePath }
+    }
+    try {
+      await fs.promises.mkdir(path.dirname(storePath), { recursive: true })
+      await fs.promises.link(filePath, storePath)
+    } catch (e) {
+      if (NO_LINK_CODES.has(e.code)) {
+        linkEntry.mode = "copy"
+        this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
+        this.registry.addLink(filePath, linkEntry)
+        await this.registry.appendEvent({ kind: "adopt", hash, path: filePath, app: meta.app || null, source_id: meta.source_id || null, bytes_saved: 0, mode: "copy" })
+        return { status: "copy-mode" }
+      }
+      throw e
+    }
+    this.registry.addBlob(hash, { size: st.size, source_urls: meta.source_urls || [] })
+    this.registry.addLink(filePath, linkEntry)
+    await this.registry.appendEvent({ 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
+    try {
+      storeStat = await fs.promises.stat(storePath)
+    } catch (e) {
+      return { status: "no-blob" }
+    }
+    const targetStat = await fs.promises.stat(targetPath)
+    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" })
+      return { status: "already" }
+    }
+    if (storeStat.size !== targetStat.size) {
+      return { status: "size-mismatch" }
+    }
+    const tmp = targetPath + TMP_SUFFIX
+    try {
+      try {
+        await fs.promises.link(storePath, tmp)
+      } catch (e) {
+        if (e.code === "EEXIST") {
+          await fs.promises.unlink(tmp)
+          await fs.promises.link(storePath, tmp)
+        } else {
+          throw e
+        }
+      }
+      await fs.promises.rename(tmp, targetPath)
+    } catch (e) {
+      await fs.promises.unlink(tmp).catch(() => {})
+      if (LOCK_CODES.has(e.code)) {
+        return { status: "locked" }
+      }
+      if (NO_LINK_CODES.has(e.code)) {
+        return { status: "unavailable", code: e.code }
+      }
+      throw e
+    }
+    const st = await fs.promises.stat(targetPath)
+    this.registry.addLink(targetPath, { hash, app: meta.app || null, source_id: meta.source_id || null, dev: st.dev, ino: st.ino, mode: "link" })
+    this.registry.addSaved(storeStat.size)
+    await this.registry.appendEvent({
+      kind: "convert", hash, path: targetPath, app: meta.app || null, source_id: meta.source_id || null,
+      auto: !!meta.auto, bytes_saved: storeStat.size, batch_id: meta.batch_id || null
+    })
+    return { status: "converted", bytes_saved: storeStat.size }
+  }
+  // reclaim: delete an orphan's store name. Refuses when any app name remains.
+  async reclaim(hash) {
+    if (!this.enabled) return { status: "disabled" }
+    const storePath = this.storePathFor(hash)
+    let st
+    try {
+      st = await fs.promises.stat(storePath)
+    } catch (e) {
+      this.registry.removeBlob(hash)
+      return { status: "gone" }
+    }
+    if (st.nlink > 1) return { status: "in-use" }
+    await fs.promises.unlink(storePath)
+    this.registry.removeBlob(hash)
+    await this.registry.appendEvent({ kind: "reclaim", hash, bytes_saved: st.size })
+    return { 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() {
+    if (!this.enabled || !this.registry) return
+    for (const [linkPath, entry] of [...this.registry.links]) {
+      await fs.promises.unlink(linkPath + TMP_SUFFIX).catch(() => {})
+      let st = null
+      try {
+        st = await fs.promises.stat(linkPath)
+      } catch (e) {}
+      if (!st || st.ino !== entry.ino || st.dev !== entry.dev) {
+        this.registry.removeLink(linkPath)
+      }
+    }
+    for (const [dupPath] of [...this.registry.duplicates]) {
+      try {
+        await fs.promises.stat(dupPath)
+      } catch (e) {
+        this.registry.duplicates.delete(dupPath)
+      }
+    }
+    for (const [hash, blob] of [...this.registry.blobs]) {
+      const storePath = this.storePathFor(hash)
+      let st = null
+      try {
+        st = await fs.promises.stat(storePath)
+      } catch (e) {}
+      if (!st) {
+        // Store name gone; re-adopt from a surviving app name if one exists.
+        let readopted = false
+        for (const [linkPath, entry] of this.registry.links) {
+          if (entry.hash !== hash || entry.mode !== "link") continue
+          try {
+            await fs.promises.mkdir(path.dirname(storePath), { recursive: true })
+            await fs.promises.link(linkPath, storePath)
+            readopted = true
+            break
+          } catch (e) {}
+        }
+        if (!readopted) this.registry.removeBlob(hash)
+        continue
+      }
+      blob.orphan = st.nlink === 1
+      blob.verified_at = Date.now()
+    }
+    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 ? {
+      excluded: new Map(registry.excluded),
+      totals: Object.assign({}, registry.totals),
+      lastScan: registry.lastScan ? Object.assign({}, registry.lastScan) : null,
+      duplicates: new Map(registry.duplicates)
+    } : null
+    const rebuiltBlobs = new Map()
+    const rebuiltLinks = new Map()
+    const storeInoToHash = new Map()
+    let shards = []
+    try {
+      shards = await fs.promises.readdir(this.blobRoot)
+    } catch (e) {}
+    for (const shard of shards) {
+      let names = []
+      try {
+        names = await fs.promises.readdir(path.resolve(this.blobRoot, shard))
+      } catch (e) { continue }
+      for (const name of names) {
+        if (!/^[0-9a-f]{64}$/.test(name)) continue
+        try {
+          const st = await fs.promises.stat(path.resolve(this.blobRoot, shard, name))
+          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)
+        } catch (e) {}
+      }
+    }
+    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()
+    if (preserved) {
+      for (const [duplicatePath, duplicate] of preserved.duplicates) {
+        if (preserved.excluded.has(duplicatePath) || rebuiltLinks.has(duplicatePath) || !rebuiltBlobs.has(duplicate.hash)) continue
+        try {
+          const st = await fs.promises.stat(duplicatePath)
+          if (st.isFile() && (!duplicate.size || duplicate.size === st.size)) {
+            rebuiltDuplicates.set(duplicatePath, Object.assign({}, duplicate, { size: st.size }))
+          }
+        } catch (error) {}
+      }
+    }
+    const rebuiltByIno = new Map()
+    for (const entry of rebuiltLinks.values()) {
+      rebuiltByIno.set(registry.inoKey(entry.dev, entry.ino), entry.hash)
+    }
+    registry.blobs = rebuiltBlobs
+    registry.links = rebuiltLinks
+    registry.scanIndex = new Map()
+    registry.duplicates = rebuiltDuplicates
+    registry.excluded = preserved ? preserved.excluded : new Map()
+    registry.lastScan = preserved ? preserved.lastScan : null
+    registry.totals = preserved ? preserved.totals : { lifetime_bytes_saved: 0 }
+    registry.byIno = rebuiltByIno
+    await registry.flush()
+  }
+  async walkForInoMatch(root, storeInoToHash, preferredSourceId = null, outputLinks = null) {
+    const stack = [root]
+    const vaultRoot = path.resolve(this.root)
+    while (stack.length) {
+      const dir = stack.pop()
+      let entries = []
+      try {
+        entries = await fs.promises.readdir(dir, { withFileTypes: true })
+      } catch (error) { continue }
+      const files = []
+      for (const entry of entries) {
+        const full = path.resolve(dir, entry.name)
+        if (entry.isSymbolicLink()) continue
+        if (entry.isDirectory()) {
+          if (full === vaultRoot) continue
+          stack.push(full)
+        }
+        else if (entry.isFile()) files.push(full)
+      }
+      const stats = await statMany(files, this.statConcurrency)
+      for (let index = 0; index < files.length; index++) {
+        const st = stats[index]
+        if (!st || st.size < this.sizeThreshold) continue
+        const hash = storeInoToHash.get(`${st.dev}:${st.ino}`)
+        if (hash) {
+          const source = this.sourceForPath(files[index], preferredSourceId)
+          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()
+          }
+          if (outputLinks) outputLinks.set(files[index], link)
+          else this.registry.addLink(files[index], link)
+        }
+      }
+    }
+  }
+  appNameFor(filePath) {
+    const source = this.sourceForPath(filePath)
+    return source && source.kind === "app" ? source.app : null
+  }
+  // Global state for the vault page and the health endpoint. Answered from
+  // memory + one stat per blob; never a walk.
+  async status() {
+    if (!this.enabled || !this.registry) return { enabled: false }
+    const registry = this.registry
+    const blobs = []
+    const blobByHash = new Map()
+    const storeStats = new Map()
+    const namesByHash = new Map()
+    for (const [linkPath, entry] of registry.links) {
+      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))
+    }
+    let bytesOnDisk = 0
+    let wouldBe = 0
+    for (const [hash, blob] of registry.blobs) {
+      const names = namesByHash.get(hash) || []
+      const apps = new Set(names.map((name) => name.app).filter(Boolean))
+      let nlink = null
+      let storeStat = null
+      try {
+        storeStat = await fs.promises.stat(this.storePathFor(hash))
+        nlink = storeStat.nlink
+      } catch (e) {}
+      storeStats.set(hash, storeStat)
+      const size = blob.size || 0
+      const physicalCopies = Math.max(1, (storeStat ? 1 : 0) + names.filter((name) => name.mode === "copy").length)
+      bytesOnDisk += size * physicalCopies
+      wouldBe += size * Math.max(physicalCopies, names.length)
+      const publicBlob = {
+        hash, size: blob.size || 0, orphan: !!blob.orphan, nlink,
+        names, apps: [...apps], source_urls: blob.source_urls || []
+      }
+      blobs.push(publicBlob)
+      blobByHash.set(hash, publicBlob)
+    }
+    const duplicates = []
+    for (const [p, entry] of registry.duplicates) {
+      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 && (!index || index.dev === undefined || index.dev === storeStat.dev))
+      const blob = blobByHash.get(entry.hash)
+      duplicates.push(Object.assign({
+        path: p, hash: entry.hash, size: entry.size || 0, app: entry.app || null,
+        shareable, matches: blob ? blob.names : []
+      }, location))
+    }
+    const events = (await registry.readEvents()).slice(-100).reverse()
+    const scan = this.scanStatus()
+    const excluded = []
+    for (const [p, meta] of registry.excluded) {
+      let size = Number(meta.size) || 0
+      if (!size) {
+        try { size = (await fs.promises.stat(p)).size } catch (error) {}
+      }
+      excluded.push(Object.assign({ path: p, ts: meta.ts || null, size }, this.locationForPath(p, meta.source_id)))
+    }
+    const publicSources = this._sources.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: source.parent_id, app: source.app || null,
+      available: source.available !== false, shareable: source.kind === "virtual" ? null : !!source.shareable
+    }))
+    return {
+      enabled: true,
+      mode: this.mode,
+      scan,
+      last_scan: registry.lastScan,
+      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),
+      unavailable_bytes: duplicates.filter((d) => !d.shareable).reduce((sum, d) => sum + d.size, 0),
+      sources: publicSources, blobs, duplicates, excluded, events
+    }
+  }
+  scanStatus() {
+    const sweeper = this.sweeper
+    return sweeper ? Object.assign({}, sweeper.state, {
+      current_file: sweeper.currentHash ? path.basename(sweeper.currentHash.path) : null
+    }) : null
+  }
+  progressStatus() {
+    return {
+      enabled: !!this.enabled,
+      scan: this.scanStatus(),
+      last_scan: this.registry ? this.registry.lastScan : null
+    }
+  }
+  // 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" }
+    const entry = this.registry.links.get(filePath)
+    if (entry) {
+      const tmp = filePath + TMP_SUFFIX
+      await fs.promises.copyFile(filePath, tmp)
+      await fs.promises.rename(tmp, filePath)
+      const st = await fs.promises.stat(filePath)
+      this.registry.removeLink(filePath)
+      this.registry.excluded.set(filePath, { ts: Date.now(), source_id: entry.source_id || null, size: st.size })
+      this.registry.schedulePersist()
+      await this.registry.appendEvent({ 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.duplicates.delete(filePath)
+      this.registry.excluded.set(filePath, { ts: Date.now(), source_id: dup.source_id || null, size: dup.size || 0 })
+      this.registry.schedulePersist()
+      await this.registry.appendEvent({ kind: "detach", 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" }
+  }
+  // reshare: un-pin a detached path; the next scan may list it again.
+  async reshare(filePath) {
+    if (!this.enabled) return { status: "disabled" }
+    const excluded = this.registry.excluded.get(filePath)
+    if (this.registry.excluded.delete(filePath)) {
+      this.registry.schedulePersist()
+      await this.registry.appendEvent({ kind: "reshare", path: filePath, source_id: excluded && excluded.source_id ? excluded.source_id : null })
+      return { status: "resharable" }
+    }
+    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 }
+    const events = await this.registry.readEvents()
+    const summary = { undone: 0, bytes: 0 }
+    for (const event of events) {
+      if (event.kind !== "convert" || event.batch_id !== batchId || !event.path) continue
+      const entry = this.registry.links.get(event.path)
+      if (!entry || entry.hash !== event.hash) continue
+      const storePath = this.storePathFor(event.hash)
+      try {
+        const st = await fs.promises.stat(event.path)
+        const storeStat = await fs.promises.stat(storePath)
+        if (st.ino !== storeStat.ino || st.dev !== storeStat.dev) continue
+        const tmp = event.path + TMP_SUFFIX
+        await fs.promises.copyFile(storePath, tmp)
+        await fs.promises.rename(tmp, event.path)
+        this.registry.removeLink(event.path)
+        this.registry.duplicates.set(event.path, {
+          hash: event.hash, size: storeStat.size, app: entry.app || null,
+          source_id: entry.source_id || event.source_id || null, discovered: Date.now()
+        })
+        this.registry.totals.lifetime_bytes_saved = Math.max(0,
+          this.registry.totals.lifetime_bytes_saved - (event.bytes_saved || 0))
+        await this.registry.appendEvent({
+          kind: "undo", hash: event.hash, path: event.path,
+          source_id: entry.source_id || event.source_id || null, batch_id: batchId,
+          bytes_saved: event.bytes_saved || storeStat.size
+        })
+        summary.undone += 1
+        summary.bytes += storeStat.size
+      } catch (e) {}
+    }
+    this.registry.schedulePersist()
+    return summary
+  }
+  async reclaimAll() {
+    if (!this.enabled) return { reclaimed: 0, bytes_freed: 0 }
+    const summary = { reclaimed: 0, bytes_freed: 0 }
+    for (const [hash, blob] of [...this.registry.blobs]) {
+      if (!blob.orphan) continue
+      const result = await this.reclaim(hash)
+      if (result.status === "reclaimed") {
+        summary.reclaimed += 1
+        summary.bytes_freed += result.bytes_freed || 0
+      }
+    }
+    return summary
+  }
+}
+
+Vault.SIZE_THRESHOLD = SIZE_THRESHOLD
+Vault.TMP_SUFFIX = TMP_SUFFIX
+
+module.exports = Vault