pinokiod 8.0.36 → 8.0.37

package/kernel/index.js

@@ -37,6 +37,7 @@ const PinokioDomainRouter = require("./router/pinokio_domain_router")
 const Procs = require('./procs')
 const Peer = require('./peer')
 const Git = require('./git')
+const Vault = require('./vault')
 const Connect = require('./connect')
 const Favicon = require('./favicon')
 const AppLauncher = require('./app_launcher')
@@ -1216,6 +1217,17 @@ class Kernel {
       await this.git.loadCheckpoints()
       console.timeEnd("git.loadCheckpoints")
 
+      // Shared model store: registry verification only at startup — never a
+      // discovery walk (spec/requirements/shared-model-store.md, trigger 5).
+      this.vault = new Vault(this)
+      if (this.homedir) {
+        this.vault.init().then((result) => {
+          if (result && result.enabled) return this.vault.verify()
+        }).catch((err) => {
+          console.warn("Vault init error:", err && err.message ? err.message : err)
+        })
+      }
+
 //      let contents = await fs.promises.readdir(this.homedir)
       //await this.bin.init()
       let ts = Date.now()

package/kernel/vault/hash_worker.js

@@ -0,0 +1,19 @@
+const { parentPort } = require('worker_threads')
+const crypto = require('crypto')
+const fs = require('fs')
+
+parentPort.on('message', ({ id, filePath }) => {
+  const hash = crypto.createHash('sha256')
+  let size = 0
+  const stream = fs.createReadStream(filePath)
+  stream.on('data', (chunk) => {
+    size += chunk.length
+    hash.update(chunk)
+  })
+  stream.on('error', (error) => {
+    parentPort.postMessage({ id, error: error.message })
+  })
+  stream.on('end', () => {
+    parentPort.postMessage({ id, hash: hash.digest('hex'), size })
+  })
+})

package/kernel/vault/index.js

@@ -0,0 +1,651 @@
+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 PRUNE_DIRS = new Set(["node_modules", ".git", "env", "venv", "__pycache__", "logs"])
+const NO_LINK_CODES = new Set(["EXDEV", "ENOTSUP", "EPERM", "ENOSYS"])
+const LOCK_CODES = new Set(["EBUSY", "EPERM", "EACCES"])
+
+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 sourceId = (kind, name) => `${kind}:${encodeURIComponent(name)}`
+
+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.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
+  }
+  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()
+    }
+    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.worker) {
+      const worker = new Worker(path.resolve(__dirname, "hash_worker.js"))
+      this.worker = worker
+      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 })
+        // Terminate when idle: lingering workers hold pipe handles that can
+        // keep processes alive (observed under node --test); respawning for
+        // the next batch costs ~30ms and hashing is idle-priority anyway.
+        if (this.workerJobs.size === 0 && this.worker === worker) {
+          this.worker = null
+          worker.terminate().catch(() => {})
+        }
+      })
+      worker.on("error", (error) => {
+        if (this.worker !== worker) return
+        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
+        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 volumeMode = this.volumeModes.get(targetStat.dev)
+    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 (NO_LINK_CODES.has(e.code) && volumeMode !== "link") {
+        this.registry.addLink(targetPath, { hash, app: meta.app || null, source_id: meta.source_id || null, dev: targetStat.dev, ino: targetStat.ino, mode: "copy" })
+        return { status: "copy-mode" }
+      }
+      if (LOCK_CODES.has(e.code)) {
+        return { status: "locked" }
+      }
+      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 from disk alone: store filenames are hashes, stat gives nlink,
+  // (dev, ino) matching re-associates app paths. No hashing required.
+  async rebuild(roots) {
+    if (!this.enabled) return
+    this.registry.reset()
+    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))
+          this.registry.addBlob(name, { size: st.size })
+          this.registry.blobs.get(name).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)
+    }
+    await this.registry.flush()
+  }
+  async walkForInoMatch(dir, storeInoToHash, preferredSourceId = null) {
+    let entries = []
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true })
+    } catch (e) { return }
+    for (const entry of entries) {
+      const full = path.resolve(dir, entry.name)
+      if (entry.isSymbolicLink()) continue
+      if (entry.isDirectory()) {
+        if (PRUNE_DIRS.has(entry.name)) continue
+        await this.walkForInoMatch(full, storeInoToHash, preferredSourceId)
+      } else if (entry.isFile()) {
+        try {
+          const st = await fs.promises.stat(full)
+          if (st.size < SIZE_THRESHOLD) continue
+          const hash = storeInoToHash.get(`${st.dev}:${st.ino}`)
+          if (hash) {
+            const source = this.sourceForPath(full, preferredSourceId)
+            this.registry.addLink(full, {
+              hash, app: source && source.kind === "app" ? source.app : null,
+              source_id: source ? source.id : null, dev: st.dev, ino: st.ino, mode: "link"
+            })
+          }
+        } catch (e) {}
+      }
+    }
+  }
+  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 storeStats = new Map()
+    let bytesOnDisk = 0
+    let wouldBe = 0
+    for (const [hash, blob] of registry.blobs) {
+      const names = []
+      const apps = new Set()
+      for (const [linkPath, entry] of registry.links) {
+        if (entry.hash === hash) {
+          const location = this.locationForPath(linkPath, entry.source_id)
+          names.push(Object.assign({ path: linkPath, app: entry.app || null, mode: entry.mode }, location))
+          if (entry.app) apps.add(entry.app)
+        }
+      }
+      let nlink = null
+      let storeStat = null
+      try {
+        storeStat = await fs.promises.stat(this.storePathFor(hash))
+        nlink = storeStat.nlink
+      } catch (e) {}
+      storeStats.set(hash, storeStat)
+      bytesOnDisk += blob.size || 0
+      wouldBe += (blob.size || 0) * Math.max(1, names.length)
+      blobs.push({
+        hash, size: blob.size || 0, orphan: !!blob.orphan, nlink,
+        names, apps: [...apps], source_urls: blob.source_urls || []
+      })
+    }
+    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 = blobs.find((item) => item.hash === 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 sweeper = this.sweeper
+    const scan = sweeper ? Object.assign({}, sweeper.state, {
+      current_file: sweeper.currentHash ? path.basename(sweeper.currentHash.path) : null
+    }) : null
+    const excluded = []
+    for (const [p, meta] of registry.excluded) {
+      excluded.push(Object.assign({ path: p, ts: meta.ts || null }, 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
+    }
+  }
+  // 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 storePath = this.storePathFor(entry.hash)
+      const tmp = filePath + TMP_SUFFIX
+      await fs.promises.copyFile(filePath, tmp)
+      await fs.promises.rename(tmp, filePath)
+      this.registry.removeLink(filePath)
+      this.registry.excluded.set(filePath, { ts: Date.now(), source_id: entry.source_id || null })
+      this.registry.schedulePersist()
+      await this.registry.appendEvent({ kind: "detach", hash: entry.hash, path: filePath, app: entry.app || null, source_id: entry.source_id || null })
+      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 })
+      this.registry.schedulePersist()
+      await this.registry.appendEvent({ kind: "detach", hash: dup.hash, path: filePath, app: dup.app || null, source_id: dup.source_id || null })
+      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
+        })
+        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
+Vault.PRUNE_DIRS = PRUNE_DIRS
+
+module.exports = Vault