@augmentd-labs/canvas-edge 0.6.2 → 0.7.0

package/node_modules/canvas-stored/src/index.js

@@ -1,26 +1,44 @@
 import EventEmitter2 from 'eventemitter2';
 import path from 'path';
 import crypto from 'crypto';
+import MutationQueue from './runtime/MutationQueue.js';
 import { createReadStream, createWriteStream, promises as fsp } from 'fs';
 import { once } from 'events';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
+import { setImmediate as yieldToIO } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
 import Debug from 'debug';
 import Cache from './cache/index.js';
 import BackendManager from './backends/BackendManager.js';
+export { getBackendCapabilities } from './backends/BackendManager.js';
 import Index from './index/index.js';
+import { prepareIndex } from './storage/recover-index.js';
 import SyncQueue from './sync/SyncQueue.js';
 import JobQueue from './sync/JobQueue.js';
 import Ledger from './sync/Ledger.js';
 import Mirror from './sync/Mirror.js';
-import { isBuffer, isFile, isStream, resolveStoredPaths } from './utils/common.js';
-import { checksumBuffer, formatId } from './utils/checksum.js';
+import BackendTrash from './trash.js';
+import ReplicaService from './sync/ReplicaService.js';
+import { isBuffer, isFileAsync, isStream, resolveStoredPaths } from './utils/common.js';
+import { checksumBuffer, checksumStream, formatId } from './utils/checksum.js';
 import { detectMimeType, detectMimeFromHead } from './utils/mime.js';
 
 const debug = Debug('stored');
+// Source retirement belongs to the final move event, never a source-loss unlink.
+const MOVE_SOURCE = Symbol('move-source');
 
 const HEAD_BYTES = 4096;
 
+async function readHead(file) {
+    const handle = await fsp.open(file, 'r');
+    try {
+        const buffer = Buffer.alloc(HEAD_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+        return buffer.subarray(0, bytesRead);
+    } finally { await handle.close(); }
+}
+
 // A filesystem move reaches the watcher as unlink(old) + add(new). Unlink
 // processing is held back this long so an add carrying the same inode can
 // claim it as a rename (in-place URL rewrite, no orphan churn). Expired
@@ -36,6 +54,29 @@ const RENAME_WINDOW_MS = 1000;
 const MOVE_SUPPRESS_MS = 3000;
 
 export default class Stored extends EventEmitter2 {
+    /** Safe startup for persistent indexes. The sync constructor remains for
+     * callers that already verified their environment (or create a new one).
+     */
+    static async open(config = {}) {
+        const databasePath = resolveStoredPaths(config).index;
+        config.onStartupStage?.({ stage: 'stored.index.verify', databasePath });
+        const recovery = await prepareIndex(databasePath);
+        if (recovery) {
+            config.onStartupStage?.({ stage: 'stored.index.quarantined', ...recovery });
+            console.warn(`Stored index verification failed; preserved at ${recovery.preservedIndexPath}. Opening an empty index; rescan backends to rebuild. Operational records remain in quarantine. Reason: ${recovery.reason}`);
+        }
+        config.onStartupStage?.({ stage: 'stored.index.open', databasePath });
+        return new this(config);
+    }
+
+    supportsScopedFolderDeletion = true;
+    #mutations;
+    #closing = false;
+    #stopPromise = null;
+
+    withStorageMutation(action, operation) { return this.#mutations.run(action, operation); }
+    detachedStorageWork(action) { return this.#mutations.detach(action); }
+    get mutationDiagnostics() { return this.#mutations.diagnostics; }
     #cache;
     #backends;
     #index;
@@ -55,11 +96,24 @@ export default class Stored extends EventEmitter2 {
     #pendingMoves = new Map();
     #retention = null;
     #retainedDb = null;
+    #retentionTasks = new Map();
+    #trash;
     #sweepTimer = null;
+    #directoryMovesDb = null;
+    #directoryMoveTasks = new Map();
+    #replicas;
 
     constructor(config = {}) {
         // Wildcards (':' delimiter) let consumers bind `object:*` across backends.
         super({ wildcard: true, delimiter: ':', maxListeners: 100, verboseMemoryLeak: false });
+        this.#mutations = new MutationQueue({ onStall: config.onStall || (state => debug('Mutation still pending: %o', state)) });
+        // API/FUSE mutations and replication share one physical executor.
+        // Reentrant calls (rename -> move, replica -> write) keep the lock.
+        for (const name of ['put', 'copy', 'move', 'writeObject', 'removeObject', 'removeToTrash', 'renameObject', 'renameDirectory', 'trashDirectory', 'removeDirectory',
+            'ensureDirectory', 'removeEmptyDirectory', 'restoreTrash', 'discardTrash', 'restoreRetained', 'deleteByUrl', 'delete']) {
+            const method = this[name].bind(this);
+            this[name] = (...args) => this.withStorageMutation(() => method(...args), name);
+        }
         this.#paths = resolveStoredPaths(config);
         this.#config = {
             checksums: config.checksums || ['sha256'],
@@ -79,16 +133,19 @@ export default class Stored extends EventEmitter2 {
         // entry, after the transaction that produced them committed).
         this.#index = new Index(this.#paths.index, {
             changes: config.changes,
-            onChange: (entries) => { for (const entry of entries) this.emit('change', entry); },
+            onChange: (entries) => this.detachedStorageWork(() => { for (const entry of entries) this.emit('change', entry); }),
         });
 
-        // Background sync queue for remote backends: file targets are copied by
-        // a worker thread, network drivers (gdrive, …) are committed in-process
-        // through their live backend (async I/O — nothing to offload, and the
-        // driver's credentials/path cache stay on the main thread).
-        this.#syncQueue = new SyncQueue({ resolveBackend: (name) => this.#backends.get(name) });
+        this.#trash = new BackendTrash(this);
+
+        try { this.#replicas = new ReplicaService(this, config.replication || {}); }
+        catch (error) { this.#index.close(); void this.#cache.stop(); throw error; }
+        this.#replicas.on('changed', operation => this.detachedStorageWork(() => this.emit('replica:changed', operation)));
+        this.#replicas.on('fault', error => this.emit('error', error));
+        this.#syncQueue = new SyncQueue({ service: this.#replicas });
         this.#syncQueue.on('synced', ({ id, results }) => this.#handleSyncResult(id, results));
-        this.#syncQueue.on('error', (err) => this.emit('error', err));
+        this.#syncQueue.on('error', error => this.emit('error', error));
+        this.#pendingMoves = this.#index.openDB('pending-moves.v1');
 
         debug('Stored initialized');
     }
@@ -103,6 +160,36 @@ export default class Stored extends EventEmitter2 {
     get cache() { return this.#cache; }
     get index() { return this.#index; }
     get backends() { return this.#backends; }
+    get replicas() { return this.#replicas; }
+
+    // Called only after the executor has verified the exact target bytes.
+    async acknowledgeReplica(backendName, key, id, origin) {
+        const meta = this.#index.get(id);
+        if (!meta) throw new Error('Replica content is not indexed');
+        const backend = this.#backends.get(backendName);
+        const stat = await backend.stat(key);
+        if (!stat) throw new Error('Verified replica disappeared');
+        const location = this.#buildLocation(backendName, key, true, {
+            size: stat.size, mtime: stat.modified,
+            ...(stat.ino != null ? { ino: stat.ino, dev: stat.dev } : {}),
+        });
+        const saved = this.#index.put(id, { ...meta, locations: this.#mergeLocations(meta, [location]) }, { origin });
+        this.#emitLocationEvent('location:add', saved, location, { origin });
+    }
+
+    async ensureDirectory(backendName, key) {
+        const backend = this.#backends.get(backendName);
+        if (!this.#replicas.capabilities(backendName).directories || !this.#isSafeKey(key)) throw new Error('Safe directory creation is unsupported');
+        if (!(await this.#verifyBackendRoot(backend)).ok) throw Object.assign(new Error('Backend is offline'), { code: 'BACKEND_UNAVAILABLE', retryable: true });
+        return backend.createContainer(key);
+    }
+
+    async removeEmptyDirectory(backendName, key) {
+        const backend = this.#backends.get(backendName);
+        if (!this.#replicas.capabilities(backendName).directories || !this.#isSafeKey(key) || typeof backend.removeEmptyContainer !== 'function') throw new Error('Safe directory removal is unsupported');
+        if (!(await this.#verifyBackendRoot(backend)).ok) throw Object.assign(new Error('Backend is offline'), { code: 'BACKEND_UNAVAILABLE', retryable: true });
+        return backend.removeEmptyContainer(key);
+    }
 
     // ─────────────────────────────────────────────────────────────────────────
     // Backend Management
@@ -124,7 +211,13 @@ export default class Stored extends EventEmitter2 {
         backend.on('scan:complete', e => this.emit('scan:complete', e));
         backend.on('error', e => this.emit('error', e));
 
-        if (config.watch) backend.watch();
+        backend.isDirectoryProtected = key => this.#replicas.owners().some(owner => owner.replicas.some(r =>
+            r.kind === 'directory' && r.backend === name && (r.key === key || r.key.startsWith(`${key}/`))));
+        if (config.watch) backend.watch().catch(error => {
+            debug('Backend %s watcher startup failed: %s', name, error.message);
+            this.emit('backend:state', { backend: name, watching: false, error: error.message });
+            if (this.listenerCount('error')) this.emit('error', error);
+        });
         return backend;
     }
 
@@ -139,6 +232,7 @@ export default class Stored extends EventEmitter2 {
 
     listBackends() { return this.#backends.list(); }
     getBackend(name) { return this.#backends.get(name); }
+    getBackendCapabilities(name) { return this.#backends.get(name)?.capabilities || null; }
 
     /**
      * Parse a canonical `stored://<backend>/<key>` URL. The backend name may
@@ -203,8 +297,10 @@ export default class Stored extends EventEmitter2 {
         const backend = this.#backends.get(p.backend);
         if (!backend) return { ok: false, reason: 'unknown-backend' };
         if (!backend.canDelete) return { ok: false, reason: 'read-only-backend' };
-        await this.#retain(p.backend, p.key, this.#index.get(`${p.backend}:${p.key}`));
+        const retained = await this.#retain(p.backend, p.key, this.#index.get(`${p.backend}:${p.key}`), 'delete');
+        const trashed = retained?.trashItem;
         const deleted = !!(await backend.delete(p.key));
+        if (deleted) this.#trash.finish(trashed);
         if (deleted) this.#dropLocation(p.backend, p.key);
         return { ok: deleted };
     }
@@ -235,6 +331,11 @@ export default class Stored extends EventEmitter2 {
      * Store a blob. Accepts Buffer | string (content) | filesystem path |
      * Readable. Paths and streams are ingested without ever materializing the
      * whole blob in memory. `backends` is required (no implicit fan-out).
+     * `adopt: true` with a path hands the file over (writeObject takes the
+     * same option): a blob-store target moves
+     * it in rather than copying it, and the file is gone afterwards. With
+     * `checksums` (hex per configured algorithm, computed by the caller as the
+     * bytes arrived) the file is not read again to hash it.
      * Returns { ok:true, id, key, size, mimeType, checksums, locations, ... }
      * or { ok:false, reason:'no-targets'|'unknown-backend' }.
      */
@@ -248,18 +349,22 @@ export default class Stored extends EventEmitter2 {
         if (!targets.length) return { ok: false, reason: 'unknown-backend' };
 
         const ingestOptions = { mtime: options.mtime ?? null };
-        const ingest = (isBuffer(blob) || (typeof blob === 'string' && !isFile(blob)))
+        const ingest = (isBuffer(blob) || (typeof blob === 'string' && !await isFileAsync(blob)))
             ? await this.#ingestMemory(blob, targets, key, options.mimeType, ingestOptions)
-            : await this.#ingestStream(blob, targets, key, options.mimeType, ingestOptions);
+            : (options.adopt && typeof blob === 'string')
+                ? await this.#ingestAdopted(blob, targets, key, options.mimeType, { ...ingestOptions, checksums: options.checksums })
+                : await this.#ingestStream(blob, targets, key, options.mimeType, ingestOptions);
 
         // Caller-supplied metadata + inline-extracted (EXIF/GPS/dimensions/media)
         // → persisted under `custom`, returned to caller + on the 'put' event.
         const extracted = ingest.extracted && Object.keys(ingest.extracted).length ? ingest.extracted : null;
-        const meta = this.#index.put(ingest.id, {
+        let meta;
+        this.#index.transaction(() => {
+        meta = this.#index.put(ingest.id, {
             checksums: ingest.checksums,
             size: ingest.size,
             mimeType: ingest.mimeType,
-            locations: ingest.locations,
+            locations: this.#mergeLocations(this.#index.get(ingest.id) || {}, ingest.locations),
             custom: extracted ? { ...metadata, ...extracted } : metadata,
         }, { origin: options.origin });
 
@@ -267,6 +372,8 @@ export default class Stored extends EventEmitter2 {
             this.#syncQueue.enqueue({ id: ingest.id, cacheRoot: this.#cache.root, cacheKey: ingest.id, targets: ingest.remoteTargets });
         }
 
+        });
+
         this.emit('put', { id: ingest.id, key: ingest.finalKey, metadata: meta });
         debug(`PUT ${ingest.id.slice(0, 19)}... → ${targets.map(t => t.name).join(', ')}`);
         return { ok: true, key: ingest.finalKey, ...meta };
@@ -293,8 +400,10 @@ export default class Stored extends EventEmitter2 {
         const removed = new Set();
         for (const loc of targets) {
             const backend = this.#backends.get(loc.backend);
-            if (backend) await this.#retain(loc.backend, loc.key, meta);
+            const retained = backend && await this.#retain(loc.backend, loc.key, meta, 'delete');
+            const trashed = retained?.trashItem;
             if (backend && await backend.delete(loc.key)) {
+                this.#trash.finish(trashed);
                 deleted.push(loc.backend);
                 removed.add(loc);
             }
@@ -366,7 +475,9 @@ export default class Stored extends EventEmitter2 {
         const backend = this.#backends.get(backendName);
         if (!backend) return { ok: false, reason: 'unknown-backend', backend: backendName };
         if (!backend.canWrite) return { ok: false, reason: 'read-only-target', backend: backendName };
-        if (backend.type !== 'local' || typeof backend.commit !== 'function') {
+        const remoteCreate = backend.type === 'remote' && typeof backend.createFrom === 'function'
+            && String(options.ifNoneMatch || '').trim() === '*';
+        if ((!remoteCreate && backend.type !== 'local') || typeof backend.commit !== 'function') {
             return { ok: false, reason: 'unsupported-backend', backend: backendName };
         }
         const destKey = this.#normalizeKey(key, { nfc: true });
@@ -375,22 +486,44 @@ export default class Stored extends EventEmitter2 {
         if (!live.ok) return { ok: false, reason: 'target-offline', backend: backendName, detail: live.reason };
 
         const pathKey = `${backendName}:${destKey}`;
+        // `adopt`: the source path is a finished file the caller hands over
+        // (a resumable upload's part). It is placed itself, not copied, and
+        // stays where it is if the write does not happen.
+        const adopted = options.adopt && typeof source === 'string' && await isFileAsync(source);
         const tempDir = backend.tempDir || path.join(this.#paths.cache, '.tmp');
-        const tempPath = path.join(tempDir, `${Date.now()}-${crypto.randomUUID()}`);
-        await fsp.mkdir(tempDir, { recursive: true });
+        const tempPath = adopted ? source : path.join(tempDir, `${Date.now()}-${crypto.randomUUID()}`);
+        if (!adopted) await fsp.mkdir(tempDir, { recursive: true });
+        let ingress = null;
+        let accepted = false;
 
         try {
-            const stream = isBuffer(source) ? Readable.from([source])
-                : (typeof source === 'string' && !isFile(source)) ? Readable.from([Buffer.from(source)])
-                    : (isStream(source) ? source : createReadStream(source));
-            const { checksums, size, head } = await this.#hashToFile(stream, tempPath);
+            const known = adopted && options.checksums && this.#config.checksums.every(algo => /^[0-9a-f]+$/.test(options.checksums[algo] || ''));
+            const { checksums, size, head } = known
+                ? { checksums: Object.fromEntries(this.#config.checksums.map(algo => [algo, options.checksums[algo]])), size: (await fsp.stat(tempPath)).size, head: await readHead(tempPath) }
+                : adopted
+                    ? await this.#hashFile(tempPath)
+                    : await this.#hashToFile(isBuffer(source) ? Readable.from([source])
+                        : (typeof source === 'string' && !await isFileAsync(source)) ? Readable.from([Buffer.from(source)])
+                            : (isStream(source) ? source : createReadStream(source)), tempPath);
             const id = formatId(checksums, this.#config.primaryChecksum);
             const sha256 = checksums.sha256 ?? null;
             if (options.sha256 && sha256 && String(options.sha256).toLowerCase() !== sha256) {
                 return { ok: false, reason: 'checksum-mismatch', expected: String(options.sha256).toLowerCase(), actual: sha256 };
             }
 
-            const current = this.#index.get(pathKey);
+            const indexed = this.#index.get(pathKey);
+            const physical = await backend.stat(destKey);
+            let current = physical && indexed?.locations?.some(l => l.backend === backendName && l.key === destKey && l.synced !== false) ? indexed : null;
+            if (physical && backend.config.driver === 'file') {
+                // A watcher/index can lag behind an external writer. Check
+                // actual bytes before preconditions or the unchanged shortcut,
+                // and index previously unknown files so overwrites retain them.
+                const input = await backend.get(destKey, { stream: true });
+                const actual = await checksumStream(Buffer.isBuffer(input) ? Readable.from([input]) : input);
+                const after = await backend.stat(destKey);
+                if (!after || ['size', 'modified', 'ino', 'dev'].some(k => physical[k] !== after[k])) return { ok: false, reason: 'source-changed' };
+                if (!current || current.checksums?.sha256 !== actual.sha256) current = await this.refreshObject(backendName, destKey);
+            }
             const currentLoc = current?.locations?.find(l => l.backend === backendName && l.key === destKey) || null;
             const failed = this.#checkPrecondition(current, currentLoc, options);
             if (failed) return failed;
@@ -413,13 +546,32 @@ export default class Stored extends EventEmitter2 {
             }
 
             const mimeType = options.mimeType || await detectMimeFromHead(head, destKey);
+            if (!String(options.origin || '').startsWith('replica:')) ingress = await this.#replicas.captureIngress(backendName, destKey, id, tempPath);
             const release = this.#holdKeys([pathKey]);
             try {
-                if (current) await this.#retain(backendName, destKey, current);
+                const retained = current ? await this.#retain(backendName, destKey, current) : null;
                 let placed = null;
-                if (String(options.ifNoneMatch || '').trim() === '*') {
+                if (current && retained && typeof backend.trashFile === 'function') {
+                    // Capture the actual inode before publishing. A writer
+                    // outside Stored can race a precondition/retention read;
+                    // its bytes must survive even if it keeps the inode open.
+                    const captured = this.#trash.prepare(backendName, destKey, { retained, reason: 'overwrite' });
+                    this.#trash.quarantine(captured);
+                    const moved = await backend.trashFile(destKey, captured.id);
+                    this.#trash.finish(captured);
+                    if (moved.checksums.sha256 !== current.checksums?.sha256) {
+                        await this.#trash.restore(backendName, captured.id).catch(() => {});
+                        return { ok: false, reason: 'source-changed', trashId: captured.id };
+                    }
+                    try { placed = await backend.createFrom(destKey, tempPath, { owned: true }); }
+                    catch (error) {
+                        await this.#trash.restore(backendName, captured.id).catch(() => {});
+                        if (error.code === 'EEXIST') return { ok: false, reason: 'precondition-failed', trashId: captured.id };
+                        throw error;
+                    }
+                } else if (String(options.ifNoneMatch || '').trim() === '*') {
                     if (typeof backend.createFrom !== 'function') return { ok: false, reason: 'unsupported-backend' };
-                    try { placed = await backend.createFrom(destKey, tempPath); }
+                    try { placed = await backend.createFrom(destKey, tempPath, { owned: true }); }
                     catch (error) {
                         if (error.code === 'EEXIST') return { ok: false, reason: 'precondition-failed', current: null };
                         throw error;
@@ -453,6 +605,8 @@ export default class Stored extends EventEmitter2 {
                 const saved = this.#index.get(id);
                 const loc = saved?.locations?.find(l => l.backend === backendName && l.key === destKey) || null;
                 debug(`WRITE ${pathKey} ← ${id.slice(0, 19)}...${current ? ` (replaces ${current.id.slice(0, 19)}...)` : ''}`);
+                this.#replicas.commitIngress(ingress);
+                accepted = true;
                 return {
                     ok: true,
                     id,
@@ -468,7 +622,8 @@ export default class Stored extends EventEmitter2 {
                 release();
             }
         } finally {
-            await fsp.rm(tempPath, { force: true }).catch(() => {});
+            if (!accepted) await this.#replicas.discardIngress(ingress);
+            if (accepted || !adopted) await fsp.rm(tempPath, { force: true }).catch(() => {});
         }
     }
 
@@ -491,36 +646,93 @@ export default class Stored extends EventEmitter2 {
         return this.#retainedDb;
     }
 
-    async #retain(backendName, key, meta) {
+    async #retain(backendName, key, meta, reason = 'version') {
         if (!this.#retention || !meta) return null;
         const backend = this.#backends.get(backendName);
         if (!backend || backend.type !== 'local' || typeof backend.retain !== 'function') return null;
         const sha256 = meta.checksums?.sha256 ? String(meta.checksums.sha256).toLowerCase() : null;
         if (!sha256) return null;
-        try {
-            const kept = await backend.retain(key, sha256);
-            if (!kept) return null;
-            const now = Date.now();
-            const prev = this.#retained.get(sha256) || null;
-            const keys = [...new Set([...(prev?.keys || []), `${backendName}:${key}`])].slice(-20);
-            const entry = {
-                sha256,
-                backend: prev?.backend || backendName,
-                size: kept.size ?? prev?.size ?? meta.size ?? null,
-                mimeType: meta.mimeType ?? prev?.mimeType ?? null,
-                id: meta.id ?? prev?.id ?? null,
-                keys,
-                firstAt: prev?.firstAt ?? now,
-                lastAt: now,
-            };
-            this.#retained.putSync(sha256, entry);
-            this.#scheduleSweep();
-            return entry;
-        } catch (err) {
-            debug(`retain ${backendName}:${key} failed: ${err.message}`);
-            this.emit('error', Object.assign(new Error(`retention failed for ${backendName}:${key}: ${err.message}`), { code: 'RETAIN_FAILED' }));
-            return null;
-        }
+        return this.#withRetainedLock(sha256, async () => {
+            try {
+                const kept = await backend.retain(key, sha256);
+                if (!kept) return null;
+                const now = Date.now();
+                const prev = this.#retained.get(sha256) || null;
+                const keys = [...new Set([...(prev?.keys || []), `${backendName}:${key}`])];
+                const entry = {
+                    sha256,
+                    backend: prev?.backend || backendName,
+                    size: kept.size ?? prev?.size ?? meta.size ?? null,
+                    mimeType: meta.mimeType ?? prev?.mimeType ?? null,
+                    id: meta.id ?? prev?.id ?? null,
+                    keys,
+                    backends: [...new Set([...(prev?.backends || this.#retainedBackendNames(prev)), backendName])],
+                    versionKeys: [...new Set([...(prev?.versionKeys || []), ...(reason === 'version' ? [`${backendName}:${key}`] : [])])],
+                    firstAt: prev?.firstAt ?? now,
+                    lastAt: now,
+                    trashVersion: 1,
+                    legacyKeys: prev?.legacyKeys ?? (prev && !prev.trashVersion ? prev.keys : []),
+                    legacyAt: prev?.legacyAt ?? prev?.lastAt ?? null,
+                };
+                this.#retained.putSync(sha256, entry);
+                this.#scheduleSweep();
+                if (reason === 'delete') {
+                    // Publish the pending deletion while still holding the
+                    // digest lock: discard must see this new reference even
+                    // if the physical unlink has not happened yet.
+                    const mtime = meta.locations?.find(loc => loc.backend === backendName && loc.key === key)?.mtime ?? null;
+                    return { ...entry, trashItem: this.#trash.prepare(backendName, key, { retained: entry, mtime }) };
+                }
+                return entry;
+            } catch (err) {
+                debug(`retain ${backendName}:${key} failed: ${err.message}`);
+                // A failed backup must never turn a recoverable delete/overwrite
+                // into permanent data loss (for example when the disk is full).
+                throw Object.assign(new Error(`retention failed for ${backendName}:${key}: ${err.message}`, { cause: err }), { code: 'RETAIN_FAILED' });
+            }
+        });
+    }
+
+    #withRetainedLock(sha256, fn) {
+        const previous = this.#retentionTasks.get(sha256) || Promise.resolve();
+        const task = previous.catch(() => {}).then(fn);
+        this.#retentionTasks.set(sha256, task);
+        void task.finally(() => {
+            if (this.#retentionTasks.get(sha256) === task) this.#retentionTasks.delete(sha256);
+        }).catch(() => {});
+        return task;
+    }
+
+    #retainedBackendNames(entry) {
+        return [...new Set([...(entry?.backends || []), ...(entry?.backend ? [entry.backend] : []),
+            ...this.#backends.list().filter(name => entry?.keys?.some(key => key.startsWith(`${name}:`)))])];
+    }
+
+    // Called only for a recorded Trash deletion. Other locations and retained
+    // overwrite versions keep their shared bytes. Never touch the original key.
+    async discardTrashBytes(item, finish) {
+        return this.#withRetainedLock(item.sha256, async () => {
+            const entry = this.getRetained(item.sha256);
+            if (!entry) { finish(); return; }
+            const address = `${item.backend}:${item.key}`;
+            const shared = this.#trash.hasReference(item.sha256, item.id, address);
+            const keys = (entry.keys || []).filter(key => key !== address || shared || entry.versionKeys?.includes(key));
+            const backends = this.#retainedBackendNames(entry);
+            if (keys.length || this.#trash.hasReference(item.sha256, item.id)) {
+                this.#retained.putSync(item.sha256, { ...entry, keys, backends });
+                finish();
+                return;
+            }
+            // Leave metadata intact on failure so the user can retry; drops
+            // are idempotent if an earlier attempt removed some copies.
+            for (const name of backends) {
+                const backend = this.#backends.get(name);
+                if (!backend?.dropRetained) throw new Error(`Recovery backend unavailable: ${name}`);
+                await backend.dropRetained(item.sha256);
+            }
+            this.#retained.removeSync(item.sha256);
+            finish();
+        });
     }
 
     #scheduleSweep() {
@@ -549,13 +761,21 @@ export default class Stored extends EventEmitter2 {
     }
 
     /** Readable stream of retained bytes, or null. */
-    async retainedStream(sha256) {
+    async retainedStream(sha256, preferredBackend = null) {
         const entry = this.getRetained(sha256);
-        const backend = entry && this.#backends.get(entry.backend);
-        if (!backend || typeof backend.retainedPath !== 'function') return null;
-        const p = backend.retainedPath(entry.sha256);
-        if (!await fsp.stat(p).catch(() => null)) return null;
-        return createReadStream(p);
+        if (!entry) return null;
+        // Equal contents can have retained copies on several backends. A
+        // missing first backend must not hide another backend's recovery copy.
+        const candidates = this.#backends.list().filter(name => name === entry.backend
+            || entry.keys?.some(key => key.startsWith(`${name}:`)));
+        if (preferredBackend && candidates.includes(preferredBackend)) candidates.unshift(preferredBackend);
+        for (const name of new Set(candidates)) {
+            const backend = this.#backends.get(name);
+            if (typeof backend.retainedPath !== 'function') continue;
+            const p = backend.retainedPath(entry.sha256);
+            if (await fsp.stat(p).catch(() => null)) return createReadStream(p);
+        }
+        return null;
     }
 
     /**
@@ -566,7 +786,7 @@ export default class Stored extends EventEmitter2 {
     async restoreRetained(sha256, { backend, key, ifMatch = null, ifNoneMatch = null, origin = null, mtime = null } = {}) {
         const entry = this.getRetained(sha256);
         if (!entry) return { ok: false, reason: 'not-found', sha256 };
-        const stream = await this.retainedStream(entry.sha256);
+        const stream = await this.retainedStream(entry.sha256, backend);
         if (!stream) return { ok: false, reason: 'not-found', sha256, detail: 'retained bytes missing on disk' };
         const target = backend || entry.backend;
         const targetKey = key || entry.keys?.at(-1)?.slice(target.length + 1) || null;
@@ -582,16 +802,22 @@ export default class Stored extends EventEmitter2 {
     /** Drop entries (and their bytes) displaced longer than the window ago. Returns `{ swept, kept }`. */
     async sweepRetained({ olderThanMs = null, now = Date.now() } = {}) {
         if (!this.#retention) return { swept: 0, kept: 0 };
+        await this.#trash.sweep(now);
         const window = olderThanMs ?? this.#retention.days * 86_400_000;
         let swept = 0;
         let kept = 0;
-        for (const { key: sha, value } of [...this.#retained.getRange()]) {
-            if (!value?.sha256) continue;
-            if ((now - (value.lastAt ?? 0)) < window) { kept += 1; continue; }
-            const backend = this.#backends.get(value.backend);
-            if (backend && typeof backend.dropRetained === 'function') await backend.dropRetained(value.sha256).catch(() => {});
-            this.#retained.removeSync(sha);
-            swept += 1;
+        for (const { key: sha } of [...this.#retained.getRange()]) {
+            await this.#withRetainedLock(sha, async () => {
+                const value = this.#retained.get(sha);
+                if (!value?.sha256) return;
+                if ((now - (value.lastAt ?? 0)) < window) { kept += 1; return; }
+                for (const name of this.#retainedBackendNames(value)) {
+                    const backend = this.#backends.get(name);
+                    if (backend?.dropRetained) await backend.dropRetained(value.sha256);
+                }
+                this.#retained.removeSync(sha);
+                swept += 1;
+            });
         }
         if (swept) debug(`retention sweep: ${swept} dropped, ${kept} kept`);
         return { swept, kept };
@@ -606,6 +832,70 @@ export default class Stored extends EventEmitter2 {
         return true;
     }
 
+    listTrash(backend, options = {}) { return this.#trash.list(backend, options); }
+    removeToTrash(backend, key, options = {}) { return this.#trash.remove(backend, key, options); }
+    getTrashItem(backend, id) { return this.#trash.get(backend, id); }
+    restoreTrash(backend, id, options = {}) { return this.#trash.restore(backend, id, options); }
+    discardTrash(backend, id) { return this.#trash.discard(backend, id); }
+
+    /** Delete a native remote folder and unlink only its indexed descendants.
+     * Local folders retain the recoverable, whole-directory Trash operation.
+     * The driver owns remote deletion policy (Drive uses its native Trash).
+     */
+    async removeDirectory(backendName, key, { origin = null } = {}) {
+        const backend = this.#backends.get(backendName);
+        if (!backend?.canDelete || backend.config.readOnly === true) throw new Error('Backend is read-only or unavailable');
+        if (typeof backend.trashContainer === 'function') return this.trashDirectory(backendName, key, { origin });
+        if (backend.transport !== 'gdrive') throw new Error('Backend does not support native folder deletion');
+        const normalized = this.#normalizeKey(key, { nfc: true });
+        if (!normalized || !this.#isSafeKey(normalized)) throw new Error('Invalid folder key');
+        this.#replicas.assertIdleEndpoint(backendName, normalized, { directory: true });
+        const keys = new Set();
+        for (const [, meta] of this.#index.entries()) {
+            for (const location of meta.locations || []) {
+                if (location.backend === backendName && location.key.startsWith(`${normalized}/`)) keys.add(location.key);
+            }
+        }
+        const release = this.#holdKeys([...keys].map(k => `${backendName}:${k}`));
+        try {
+            // A missing folder is an idempotent success; a failed remote write
+            // must leave every local location intact for retry.
+            await backend.deleteContainer(normalized);
+            for (const key of keys) this.#processUnlink({ backend: backendName, key, ...(origin ? { origin } : {}) });
+            await this.#replicas.abandonUnownedIngress(backendName, normalized, { directory: true });
+            return { ok: true, key: normalized, type: 'directory' };
+        } finally { release(); }
+    }
+
+    /** Move the whole directory into private trash in one filesystem rename.
+     * This preserves unindexed/hidden files, empty folders and timestamps too.
+     * No recursive rm is permitted when recoverable deletion is enabled.
+     */
+    async trashDirectory(backendName, key, { origin = null } = {}) {
+        const backend = this.#backends.get(backendName);
+        if (!backend?.canDelete || typeof backend.trashContainer !== 'function') throw new Error('Backend does not support recoverable folder deletion');
+        const normalized = this.#normalizeKey(key, { nfc: true });
+        if (!normalized || !this.#isSafeKey(normalized)) throw new Error('Invalid trash folder key');
+        this.#replicas.assertIdleEndpoint(backendName, normalized, { directory: true });
+        if (!this.#retention) throw new Error('Enable backend retention before moving folders to Trash');
+        const keys = [];
+        for (const [, meta] of this.#index.entries()) {
+            for (const location of meta.locations || []) {
+                if (location.backend === backendName && location.key.startsWith(`${normalized}/`)) keys.push(location.key);
+            }
+        }
+        const item = this.#trash.prepare(backendName, normalized, { directory: true });
+        const release = this.#holdKeys(keys.map(k => `${backendName}:${k}`));
+        try {
+            await backend.trashContainer(normalized, item.id);
+            this.#trash.finish(item);
+            this.#scheduleSweep();
+            for (const key of keys) this.#processUnlink({ backend: backendName, key, ...(origin ? { origin } : {}) });
+            await this.#replicas.abandonUnownedIngress(backendName, normalized, { directory: true });
+            return { ok: true, id: item.id, key: normalized, type: 'directory' };
+        } finally { release(); }
+    }
+
     /**
      * Delete the bytes at `backend:key` (precondition-checked like
      * writeObject) and process it as the genuine unlink it is: consumers get
@@ -617,6 +907,7 @@ export default class Stored extends EventEmitter2 {
         if (!backend.canDelete) return { ok: false, reason: 'read-only-backend', backend: backendName };
         const destKey = this.#normalizeKey(key, { nfc: true });
         if (!destKey || !this.#isSafeKey(destKey)) return { ok: false, reason: 'invalid-key', key };
+        this.#replicas.assertIdleEndpoint(backendName, destKey, { except: String(options.origin || '').startsWith('replica:') ? options.origin.slice(8) : null });
 
         const pathKey = `${backendName}:${destKey}`;
         const current = this.#index.get(pathKey);
@@ -630,9 +921,22 @@ export default class Stored extends EventEmitter2 {
             // false = bytes already gone; the location still goes. A remote
             // driver re-evaluates the precondition at the other end (412 →
             // typed error, nothing is unlinked here).
-            await this.#retain(backendName, destKey, current);
-            await backend.delete(destKey, { ifMatch: options.ifMatch, origin: options.origin });
-            this.#processUnlink({ backend: backendName, key: destKey, ...(options.origin ? { origin: options.origin } : {}) });
+            const retained = await this.#retain(backendName, destKey, current, options.trashItem ? 'version' : 'delete');
+            const trashed = options.trashItem || retained?.trashItem;
+            if (trashed && typeof backend.trashFile === 'function') {
+                this.#trash.quarantine(trashed);
+                const moved = await backend.trashFile(destKey, trashed.id);
+                this.#trash.finish(trashed);
+                if (moved.checksums.sha256 !== current.checksums?.sha256) {
+                    // A filesystem writer won the race. The captured inode is
+                    // recoverable even if it is still open in that process.
+                    await this.#trash.restore(backendName, trashed.id).catch(() => {});
+                    return { ok: false, reason: 'source-changed', trashId: trashed.id };
+                }
+            } else await backend.delete(destKey, { ifMatch: options.ifMatch, origin: options.origin });
+            this.#trash.finish(trashed);
+            if (!options[MOVE_SOURCE]) this.#processUnlink({ backend: backendName, key: destKey, ...(options.origin ? { origin: options.origin } : {}) });
+            await this.#replicas.abandonUnownedIngress(backendName, destKey);
             debug(`REMOVE ${pathKey}`);
             return { ok: true, id: current.id, sha256: current.checksums?.sha256 ?? null, seq: this.#index.head() };
         } finally {
@@ -640,6 +944,19 @@ export default class Stored extends EventEmitter2 {
         }
     }
 
+    async refreshObject(backendName, key, origin = null) {
+        const backend = this.#backends.get(backendName);
+        const before = await backend.stat(key);
+        if (!before) return null;
+        const input = await backend.get(key, { stream: true });
+        const checksums = await checksumStream(Buffer.isBuffer(input) ? Readable.from([input]) : input);
+        const after = await backend.stat(key);
+        if (!after || ['size', 'modified', 'ino', 'dev'].some(k => before[k] !== after[k])) throw new Error('File changed during refresh');
+        this.#handleFileEvent('file:add', { backend: backendName, key, checksums, ...after, origin,
+            path: backend.resolveKeyPath?.(key), mimeType: await detectMimeType(backend.resolveKeyPath(key)) }, { force: true });
+        return this.#index.get(`${backendName}:${key}`);
+    }
+
     /**
      * Rename `backend:from` to `backend:to` on the same backend: one
      * `rename(2)` where the driver supports it, identity and inode intact,
@@ -654,6 +971,8 @@ export default class Stored extends EventEmitter2 {
         if (!fromKey || !this.#isSafeKey(fromKey)) return { ok: false, reason: 'invalid-key', key: from };
         if (!toKey || !this.#isSafeKey(toKey)) return { ok: false, reason: 'invalid-key', key: to };
         if (fromKey === toKey) return { ok: false, reason: 'same-key', key: fromKey };
+        this.#replicas.assertIdleEndpoint(backendName, fromKey);
+        this.#replicas.assertIdleEndpoint(backendName, toKey);
 
         const current = this.#index.get(`${backendName}:${fromKey}`);
         const currentLoc = current?.locations?.find(l => l.backend === backendName && l.key === fromKey) || null;
@@ -684,6 +1003,133 @@ export default class Stored extends EventEmitter2 {
         };
     }
 
+    /** One filesystem rename, then an atomic re-key of indexed locations.
+     * The durable operation receipt makes a lost HTTP response safe to retry.
+     * No object streams, checksums or per-file filesystem moves are needed.
+     */
+    async renameDirectory(backendName, from, to, { operationId, origin = null } = {}) {
+        const backend = this.#backends.get(backendName);
+        if (!backend) return { ok: false, reason: 'unknown-backend' };
+        if (!backend.canWrite) return { ok: false, reason: 'read-only-target' };
+        const remote = typeof backend.renameDirectory === 'function';
+        if (!remote && (!backend.root || typeof backend.resolveKeyPath !== 'function')) return { ok: false, reason: 'unsupported-backend' };
+        const fromKey = this.#normalizeKey(from, { nfc: true });
+        const toKey = this.#normalizeKey(to, { nfc: true });
+        if (!fromKey || !toKey || !this.#isSafeKey(fromKey) || !this.#isSafeKey(toKey)
+            || backend.isIgnored?.(fromKey) || backend.isIgnored?.(toKey)
+            || fromKey === toKey || toKey.startsWith(`${fromKey}/`) || fromKey.startsWith(`${toKey}/`)
+            || typeof operationId !== 'string' || !operationId || operationId.length > 128) {
+            return { ok: false, reason: 'invalid-key' };
+        }
+        const receiptKey = `${backendName}:${operationId}`;
+        this.#replicas.assertIdleEndpoint(backendName, fromKey, { directory: true });
+        this.#replicas.assertIdleEndpoint(backendName, toKey, { directory: true });
+        if (remote) return this.#renameRemoteDirectory(backend, fromKey, toKey, { operationId, origin });
+        const prior = this.#directoryMoveTasks.get(backendName) || Promise.resolve();
+        const task = prior.catch(() => {}).then(async () => {
+            const db = this.#directoryMovesDb ||= this.#index.openDB('directory-moves');
+            let receipt = db.get(receiptKey);
+            if (receipt && (receipt.from !== fromKey || receipt.to !== toKey)) return { ok: false, reason: 'invalid-key' };
+            const result = () => ({ ok: true, directory: true, from: fromKey, to: toKey, state: 'complete', seq: this.#index.head() });
+            if (receipt?.done) return result();
+            const source = backend.resolveKeyPath(fromKey);
+            const target = backend.resolveKeyPath(toKey);
+            const root = await fsp.realpath(backend.root);
+            const contained = (p) => { const rel = path.relative(root, p); return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)); };
+            const stat = async (p) => { try { return await fsp.lstat(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } };
+            const sourceStat = await stat(source);
+            if (!receipt) {
+                if (!sourceStat) return { ok: false, reason: 'not-found' };
+                if (!sourceStat.isDirectory() || !contained(await fsp.realpath(source))) return { ok: false, reason: 'invalid-key' };
+                if (await stat(target)) return { ok: false, reason: 'target-exists' };
+                const rows = this.#index.locationsByBackend(backendName, { prefix: `${fromKey}/`, limit: Number.MAX_SAFE_INTEGER }).objects;
+                if (rows.some(row => backend.isIgnored?.(`${toKey}/${row.key.slice(fromKey.length + 1)}`))) return { ok: false, reason: 'invalid-key' };
+                receipt = { from: fromKey, to: toKey, dev: sourceStat.dev, ino: sourceStat.ino, keys: rows.map(row => row.key) };
+                db.putSync(receiptKey, receipt);
+            }
+            const movedKey = (key) => `${toKey}/${key.slice(fromKey.length + 1)}`;
+            const release = this.#holdKeys(receipt.keys.flatMap(key => [`${backendName}:${key}`, `${backendName}:${movedKey(key)}`]));
+            try {
+                if (sourceStat?.dev === receipt.dev && sourceStat.ino === receipt.ino) {
+                    if (!contained(await fsp.realpath(source))) return { ok: false, reason: 'invalid-key' };
+                    if (await stat(target)) return { ok: false, reason: 'target-exists' };
+                    // Check existing parents before mkdir: a symlink must not create
+                    // directories outside this backend, even if the rename fails.
+                    let parent = path.dirname(target);
+                    while (!await stat(parent)) parent = path.dirname(parent);
+                    if (!contained(await fsp.realpath(parent))) return { ok: false, reason: 'invalid-key' };
+                    await fsp.mkdir(path.dirname(target), { recursive: true });
+                    if (!contained(await fsp.realpath(path.dirname(target)))) return { ok: false, reason: 'invalid-key' };
+                    await fsp.rename(source, target); // EXDEV is an error, never a copy fallback.
+                } else {
+                    // A recreated source may now have different indexed data.
+                    // Leave both trees intact instead of re-keying that data.
+                    if (sourceStat) return { ok: false, reason: 'target-exists' };
+                    const targetStat = await stat(target);
+                    if (targetStat?.dev !== receipt.dev || targetStat.ino !== receipt.ino) return { ok: false, reason: 'target-exists' };
+                }
+                const events = [];
+                this.#index.transaction(() => {
+                    for (const key of receipt.keys) {
+                        const current = this.#index.get(`${backendName}:${key}`);
+                        const old = current?.locations?.find(l => l.backend === backendName && l.key === key);
+                        if (!old) continue;
+                        const nextKey = movedKey(key);
+                        const location = this.#buildLocation(backendName, nextKey, old.synced, { ...old, key: nextKey });
+                        const saved = this.#index.put(current.id, {
+                            ...current,
+                            locations: current.locations.map(l => l === old ? location : l),
+                        }, { origin, rename: { backend: backendName, from: key, to: nextKey } });
+                        events.push({ id: current.id, checksums: saved.checksums,
+                            from: this.#endpoint(old), to: this.#endpoint(location),
+                            location: this.#describeLocation(location),
+                            locations: saved.locations.map(l => this.#describeLocation(l)), origin });
+                    }
+                    db.putSync(receiptKey, { from: fromKey, to: toKey, done: true });
+                    this.#replicas.moveIngress(backendName, fromKey, backendName, toKey, { directory: true });
+                });
+                for (const event of events) this.#emitObject('move', event);
+                return result();
+            } finally { release(); }
+        });
+        this.#directoryMoveTasks.set(backendName, task);
+        try { return await task; }
+        finally { if (this.#directoryMoveTasks.get(backendName) === task) this.#directoryMoveTasks.delete(backendName); }
+    }
+
+    // A backend that renames a directory itself (the canvas driver: one hub
+    // request). The index follows with one re-key of the locations under it.
+    async #renameRemoteDirectory(backend, fromKey, toKey, { operationId, origin }) {
+        const name = backend.name;
+        const prefix = `${fromKey}/`;
+        const rows = this.#index.locationsByBackend(name, { prefix, limit: Number.MAX_SAFE_INTEGER }).objects;
+        const movedKey = (key) => `${toKey}/${key.slice(prefix.length)}`;
+        const release = this.#holdKeys(rows.flatMap(row => [`${name}:${row.key}`, `${name}:${movedKey(row.key)}`]));
+        try {
+            const moved = await backend.renameDirectory(fromKey, toKey, { operationId, origin });
+            const events = [];
+            this.#index.transaction(() => {
+                for (const { key } of rows) {
+                    const current = this.#index.get(`${name}:${key}`);
+                    const old = current?.locations?.find(l => l.backend === name && l.key === key);
+                    if (!old) continue;
+                    const nextKey = movedKey(key);
+                    const location = this.#buildLocation(name, nextKey, old.synced, { ...old, key: nextKey });
+                    const saved = this.#index.put(current.id, {
+                        ...current,
+                        locations: current.locations.map(l => l === old ? location : l),
+                    }, { origin, rename: { backend: name, from: key, to: nextKey } });
+                    events.push({ id: current.id, checksums: saved.checksums,
+                        from: this.#endpoint(old), to: this.#endpoint(location),
+                        location: this.#describeLocation(location),
+                        locations: saved.locations.map(l => this.#describeLocation(l)), origin });
+                }
+            });
+            for (const event of events) this.#emitObject('move', event);
+            return { ok: true, directory: true, from: fromKey, to: toKey, state: 'complete', seq: moved.seq ?? null, count: events.length };
+        } finally { release(); }
+    }
+
     // `If-Match` / `If-None-Match` semantics over the index. Returns the typed
     // failure (with what is actually there) or null when the write may go on.
     #checkPrecondition(current, currentLoc, { ifMatch = null, ifNoneMatch = null } = {}) {
@@ -774,11 +1220,9 @@ export default class Stored extends EventEmitter2 {
                 const previous = this.#displaceTargets(targets, destKey, meta.id, options);
                 const current = this.#index.get(meta.id) || meta;
                 const saved = this.#index.put(meta.id, { ...current, locations: this.#mergeLocations(current, transferred.locations) }, { origin: options.origin });
+                if (transferred.remoteTargets.length) this.#syncQueue.enqueue({ id: meta.id, cacheRoot: this.#cache.root, cacheKey: meta.id, targets: transferred.remoteTargets });
                 return { saved, previous };
             });
-            if (transferred.remoteTargets.length) {
-                this.#syncQueue.enqueue({ id: meta.id, cacheRoot: this.#cache.root, cacheKey: meta.id, targets: transferred.remoteTargets });
-            }
 
             for (const loc of transferred.locations) {
                 this.#emitLocationEvent('location:add', saved, loc, previous ? { previous } : {});
@@ -819,6 +1263,8 @@ export default class Stored extends EventEmitter2 {
         if (!plan.ok) return plan;
 
         const { meta, sourceLocation, sourceBackend, targets, destKey } = plan;
+        this.#replicas.assertIdleEndpoint(sourceLocation.backend, sourceLocation.key);
+        for (const target of targets) this.#replicas.assertIdleEndpoint(target.name, destKey);
         if (!targets.length) {
             return { ok: true, id: meta.id, state: 'complete', unchanged: true, locations: await this.locations(meta.id) };
         }
@@ -874,15 +1320,17 @@ export default class Stored extends EventEmitter2 {
                 const previous = this.#displaceTargets(targets, destKey, meta.id, options);
                 const current = this.#index.get(meta.id) || meta;
                 const saved = this.#index.put(meta.id, { ...current, locations: this.#mergeLocations(current, transferred.locations) }, { origin: options.origin });
+                if (transferred.remoteTargets.length) {
+                    const pending = this.#pendingMoves.get(meta.id) || [];
+                    pending.push({ sourceLocation, target: target.name, destKey: targetKey });
+                    this.#pendingMoves.putSync(meta.id, pending);
+                    this.#syncQueue.enqueue({ id: meta.id, cacheRoot: this.#cache.root, cacheKey: meta.id, targets: transferred.remoteTargets });
+                }
                 return { saved, previous };
             });
             this.#emitLocationEvent('location:add', saved, location, previous ? { previous } : {});
 
             if (transferred.remoteTargets.length) {
-                const pending = this.#pendingMoves.get(meta.id) || [];
-                pending.push({ sourceLocation, target: target.name, destKey: targetKey });
-                this.#pendingMoves.set(meta.id, pending);
-                this.#syncQueue.enqueue({ id: meta.id, cacheRoot: this.#cache.root, cacheKey: meta.id, targets: transferred.remoteTargets });
                 debug(`MOVE (pending sync) ${sourceLocation.backend}:${sourceLocation.key} → ${target.name}:${targetKey}`);
                 return {
                     ok: true,
@@ -953,7 +1401,10 @@ export default class Stored extends EventEmitter2 {
      * re-hashed. Returns { ok:true, backend, count, files } | { ok:false, reason }.
      */
     async scan(backendName, options = {}) {
-        const { onFile, ...backendOptions } = options;
+        const { onFile, isCancelled, ...backendOptions } = options;
+        const checkCancelled = () => {
+            if (isCancelled?.()) throw Object.assign(new Error('Scan cancelled'), { code: 'RESYNC_CANCELLED' });
+        };
         const list = backendName
             ? [this.#backends.get(backendName)].filter(Boolean)
             : this.#backends.all();
@@ -963,6 +1414,7 @@ export default class Stored extends EventEmitter2 {
         let complete = true;
         let errors = null;
         for (const backend of list) {
+            checkCancelled();
             // Per-file ingest into the stored index — idempotent, guarded so the
             // streaming path (backend onFile) and the returned-rows path don't
             // double-process a key.
@@ -972,12 +1424,19 @@ export default class Stored extends EventEmitter2 {
                 processed.add(file.key);
                 if (!file.checksums) return;
                 const id = formatId(file.checksums, this.#config.primaryChecksum);
+                const occupant = this.#index.get(`${file.backend}:${file.key}`);
+                // Scans must report the same edit provenance as watcher/API
+                // writes. Otherwise consumers see new content as a new file,
+                // lose the document ID, and later mistake the old row for a
+                // deletion. Keep the hint on both streamed and returned rows.
+                const previous = occupant && occupant.id !== id ? occupant : null;
+                if (previous) file.previous = { id: previous.id, checksums: previous.checksums };
                 const existing = this.#index.get(id);
                 const locations = existing?.locations || [];
                 const match = locations.find(l => l.backend === file.backend && l.key === file.key);
                 // Avoid LMDB/index/change-feed churn on warm scans. Still emit
                 // the row to consumers: their document index may need repair.
-                if (match && match.synced === true && match.size === file.size && match.mtime === file.modified
+                if (!previous && match && match.synced === true && match.size === file.size && match.mtime === file.modified
                     && (file.ino == null || (match.ino === file.ino && match.dev === file.dev))
                     && existing.size === file.size && existing.mimeType === file.mimeType) return;
                 if (match) {
@@ -993,14 +1452,22 @@ export default class Stored extends EventEmitter2 {
                         ...(file.ino != null ? { ino: file.ino, dev: file.dev } : {}),
                     }));
                 }
-                this.#index.put(id, { checksums: file.checksums, size: file.size, mimeType: file.mimeType, locations });
+                this.#index.transaction(() => {
+                    if (previous) {
+                        const remaining = previous.locations.filter(l => !(l.backend === file.backend && l.key === file.key));
+                        if (remaining.length) this.#index.put(previous.id, { ...previous, locations: remaining });
+                        else this.#index.delete(previous.id);
+                    }
+                    this.#index.put(id, { checksums: file.checksums, size: file.size, mimeType: file.mimeType, locations });
+                });
             };
 
             // Inode identity snapshot for rename matching: same (dev, ino) at a
             // NEW path with unchanged size+mtime is a move — reuse the indexed
             // checksums instead of rehashing, so a folder rename (thousands of
             // "moves") collapses into cheap URL rewrites.
-            const inodeMap = this.#buildInodeMap(backend.name);
+            const inodeMap = await this.#buildInodeMap(backend.name);
+            checkCancelled();
 
             const result = await backend.scan({
                 algorithms: this.#config.checksums,
@@ -1010,10 +1477,13 @@ export default class Stored extends EventEmitter2 {
                 // Stream-through: index the file, then hand it to the caller so
                 // consumers (workspace doc upserts) see results as the walk runs.
                 onFile: async (file) => {
+                    checkCancelled();
                     ingest(file);
                     if (typeof onFile === 'function') await onFile(file);
+                    if (processed.size % 32 === 0) await yieldToIO();
                 },
             });
+            checkCancelled();
             // Snapshot shape { files, complete, errors } (file driver) or a bare
             // rows array (legacy/simple drivers — treated as a complete walk).
             // Backends whose scan() reports via events instead (non-array, no
@@ -1021,13 +1491,24 @@ export default class Stored extends EventEmitter2 {
             const snapshot = Array.isArray(result)
                 ? { files: result, complete: true, errors: null }
                 : (Array.isArray(result?.files) ? result : null);
-            if (!snapshot) continue;
+            if (!snapshot || result?.ok === false) {
+                complete = false;
+                errors = { ...(errors || {}), [backend.name]: { root: 'scan returned no usable snapshot' } };
+                continue;
+            }
 
             if (snapshot.complete === false) complete = false;
             if (snapshot.errors) errors = { ...(errors || {}), [backend.name]: snapshot.errors };
 
             // Backends that ignore onFile still get their rows indexed here.
-            for (const file of snapshot.files) ingest(file);
+            let visited = 0;
+            for (const file of snapshot.files) {
+                if (++visited % 128 === 0) { await yieldToIO(); checkCancelled(); }
+                ingest(file);
+            }
+            // Index change listeners may request cancellation synchronously on
+            // the last ingested row, without another file callback or I/O turn.
+            checkCancelled();
 
             // Removal only ever runs against a usable snapshot: a dead/absent
             // root (errors.root) means the backend is offline — nothing is
@@ -1036,7 +1517,7 @@ export default class Stored extends EventEmitter2 {
             if (snapshot.errors?.root) continue;
             const presentKeys = new Set(snapshot.files.map(file => file.key));
             const erroredPrefixes = (snapshot.errors?.dirs || []).map(d => d.prefix).filter(Boolean);
-            this.#removeMissingLocations(backend.name, presentKeys, erroredPrefixes);
+            if (snapshot.complete !== false) this.#removeMissingLocations(backend.name, presentKeys, erroredPrefixes);
             files.push(...snapshot.files);
         }
         return { ok: true, backend: backendName ?? null, count: files.length, files, complete, errors };
@@ -1059,8 +1540,14 @@ export default class Stored extends EventEmitter2 {
     // Lifecycle
     // ─────────────────────────────────────────────────────────────────────────
 
-    async stop() {
+    stop() {
+        if (!this.#stopPromise) { this.#closing = true; this.#mutations.close(); this.#stopPromise = this.#stop(); }
+        return this.#stopPromise;
+    }
+    async #stop() {
         if (this.#sweepTimer) { clearInterval(this.#sweepTimer); this.#sweepTimer = null; }
+        await this.#replicas.stop();
+        await this.#mutations.drain();
         await this.#syncQueue.stop();
         await this.#backends.stopAll();
         // Flush held unlinks (watchers are stopped — no add can claim them now)
@@ -1070,7 +1557,11 @@ export default class Stored extends EventEmitter2 {
             this.#pendingUnlinks.delete(pendingKey);
             this.#processUnlink(data);
         }
-        this.#index.close();
+        // No stream writers remain at shutdown. Verify reclaims content whose
+        // staging keys were released without racing an ingress stream.
+        await this.#cache.stop();
+        this.#replicas.releaseExecutor();
+        await this.#index.close();
         debug('Stopped');
     }
 
@@ -1084,13 +1575,14 @@ export default class Stored extends EventEmitter2 {
 
         for (const r of results) {
             if (!r.success) continue;
-            const loc = meta.locations.find(l => l.backend === r.backend);
+            const loc = meta.locations.find(l => l.backend === r.backend && l.key === r.key);
             if (loc) loc.synced = true;
         }
 
         this.#index.put(meta.id, meta);
         this.emit('synced', { id, results });
-        this.#resolvePendingMoves(id, results);
+        // Source retirement is replayed by resumePendingMoves, under the same
+        // executor lock, after the durable destination receipt commits.
     }
 
     // ─────────────────────────────────────────────────────────────────────────
@@ -1383,16 +1875,21 @@ export default class Stored extends EventEmitter2 {
         try {
             if (removeSourceBytes) {
                 const sourceBackend = this.#backends.get(sourceLocation.backend);
-                const deleted = await sourceBackend.delete(sourceLocation.key).catch(() => false);
-                if (!deleted) {
-                    return {
-                        ok: false,
-                        reason: 'source-delete-failed',
-                        degradedToCopy: true,
-                        id,
-                        from: this.#endpoint(sourceLocation),
-                        to: this.#endpoint(newLocation),
-                    };
+                const targetBackend = this.#backends.get(newLocation.backend);
+                if (!sourceBackend || !targetBackend) return { ok: false, reason: 'backend-offline' };
+                const bytes = await targetBackend.get(newLocation.key, { stream: true });
+                if (!bytes || `sha256:${(await checksumStream(Buffer.isBuffer(bytes) ? Readable.from([bytes]) : bytes)).sha256}` !== id) return { ok: false, reason: 'target-changed' };
+                const sourceStat = await sourceBackend.stat(sourceLocation.key);
+                if (sourceStat) {
+                    const source = await sourceBackend.get(sourceLocation.key, { stream: true });
+                    if (!source || `sha256:${(await checksumStream(Buffer.isBuffer(source) ? Readable.from([source]) : source)).sha256}` !== id) return { ok: false, reason: 'source-changed' };
+                    this.#replicas.moveIngress(sourceLocation.backend, sourceLocation.key, newLocation.backend, newLocation.key);
+                    const result = sourceBackend.config.driver === 'cacache'
+                        ? await this.deleteByUrl(`stored://${sourceLocation.backend}/${sourceLocation.key}`)
+                        : (this.#retention && sourceBackend.config.driver === 'file')
+                            ? await this.removeObject(sourceLocation.backend, sourceLocation.key, { ifMatch: id.slice(7), origin, [MOVE_SOURCE]: true })
+                            : { ok: false, reason: 'recovery-unavailable' };
+                    if (!result.ok) return { ...result, degradedToCopy: true };
                 }
             }
 
@@ -1408,6 +1905,7 @@ export default class Stored extends EventEmitter2 {
                 ? { backend: newLocation.backend, from: sourceLocation.key, to: newLocation.key }
                 : null;
             const saved = this.#index.put(id, { ...current, locations }, { origin, rename });
+            this.#replicas.moveIngress(sourceLocation.backend, sourceLocation.key, newLocation.backend, newLocation.key);
 
             this.#emitObject('move', {
                 id,
@@ -1434,36 +1932,35 @@ export default class Stored extends EventEmitter2 {
     }
 
     /** Finish moves that were waiting on a remote destination write. */
-    #resolvePendingMoves(id, results = []) {
-        const pending = this.#pendingMoves.get(id);
-        if (!pending) return;
-
-        const succeeded = new Set(results.filter(r => r.success).map(r => r.backend));
-        const failed = new Set(results.filter(r => !r.success).map(r => r.backend));
-        const remaining = [];
-
-        for (const entry of pending) {
-            if (succeeded.has(entry.target)) {
-                const meta = this.#index.get(id);
-                const location = (meta?.locations || []).find(l => l.backend === entry.target && l.key === entry.destKey);
-                if (location) {
-                    this.#finalizeMove(id, entry.sourceLocation, location, { removeSourceBytes: true })
-                        .catch(err => this.emit('error', err));
+    async resumePendingMoves() {
+        // Snapshot keys only; each record is re-read under the mutation lock.
+        // Holding the lock over the whole backlog delayed interactive byte
+        // operations behind every remote verification. Awaiting resolved
+        // promises also never lets HTTP/timer callbacks run.
+        let processed = 0;
+        for (const id of [...this.#pendingMoves.getKeys()]) {
+            if (this.#closing) break;
+            await this.withStorageMutation(async () => {
+                const pending = this.#pendingMoves.get(id);
+                if (!pending) return;
+                const remaining = [];
+                for (const entry of pending) {
+                    try {
+                        const meta = this.#index.get(id);
+                        const location = meta?.locations?.find(l => l.backend === entry.target && l.key === entry.destKey && l.synced !== false);
+                        if (!location) { remaining.push(entry); continue; }
+                        const result = await this.#finalizeMove(id, entry.sourceLocation, location, { removeSourceBytes: true });
+                        if (!result.ok) remaining.push({ ...entry, error: result.reason });
+                    } catch (error) { remaining.push({ ...entry, error: error.message }); }
                 }
-            } else if (failed.has(entry.target)) {
-                // Destination write failed — the source stays exactly where it
-                // is. The object is unharmed; the move simply did not happen.
-                this.emit('error', Object.assign(
-                    new Error(`Move to ${entry.target} failed; source retained at ${entry.sourceLocation.backend}:${entry.sourceLocation.key}`),
-                    { id, code: 'MOVE_SYNC_FAILED' },
-                ));
-            } else {
-                remaining.push(entry);
-            }
+                // Disabled/offline destinations can leave thousands of moves
+                // pending. Rewriting identical records on every retry caused
+                // one synchronous LMDB commit per item, twice each queue tick.
+                if (!remaining.length) this.#pendingMoves.removeSync(id);
+                else if (!isDeepStrictEqual(pending, remaining)) this.#pendingMoves.putSync(id, remaining);
+            });
+            if (++processed % 32 === 0) await yieldToIO();
         }
-
-        if (remaining.length) this.#pendingMoves.set(id, remaining);
-        else this.#pendingMoves.delete(id);
     }
 
     /**
@@ -1640,6 +2137,10 @@ export default class Stored extends EventEmitter2 {
     // local backend's filesystem, then commit (hardlink/rename) to targets.
     async #ingestStream(blob, targets, key, mimeHint, options = {}) {
         const source = isStream(blob) ? blob : createReadStream(blob);
+        const blobTarget = targets.find(t => typeof t.backend.ingestStream === 'function');
+        if (blobTarget || targets.every(t => t.backend.type !== 'local')) {
+            return this.#ingestBlobStream(source, targets, blobTarget, key, mimeHint, options);
+        }
         const firstLocal = targets.find(t => t.backend.type === 'local')?.backend;
         const tempDir = firstLocal ? firstLocal.tempDir : path.join(this.#paths.cache, '.tmp');
         const tempPath = path.join(tempDir, `${Date.now()}-${crypto.randomUUID()}`);
@@ -1663,6 +2164,94 @@ export default class Stored extends EventEmitter2 {
         return result;
     }
 
+    // Upload directly to the managed blob store. Hash and sniff in-flight;
+    // extraction and additional destinations read the completed immutable blob.
+    // Cacache owns the only temporary payload and atomically publishes it.
+    async #ingestBlobStream(source, targets, target, key, mimeHint, options) {
+        const hashes = this.#config.checksums.map(algo => ({ algo, hash: crypto.createHash(algo) }));
+        const checksums = {};
+        const headChunks = [];
+        let headLen = 0;
+        async function* measured() {
+            for await (const chunk of source) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                for (const { hash } of hashes) hash.update(buf);
+                if (headLen < HEAD_BYTES) {
+                    const slice = buf.subarray(0, HEAD_BYTES - headLen);
+                    headChunks.push(Buffer.from(slice));
+                    headLen += slice.length;
+                }
+                yield buf;
+            }
+            for (const { algo, hash } of hashes) checksums[algo] = hash.digest('hex');
+        }
+        let id, finalKey, mimeType, extracted;
+        const sink = target?.backend || this.#cache;
+        const { file, size } = await sink.ingestStream(measured(), async content => {
+            id = formatId(checksums, this.#config.primaryChecksum);
+            finalKey = key || this.#generateKey(checksums);
+            mimeType = mimeHint || await detectMimeFromHead(Buffer.concat(headChunks), finalKey);
+            extracted = await this.#maybeExtract({ file: content.file }, mimeType, finalKey);
+            return target ? finalKey : { key: id, metadata: { key: finalKey, checksums, size: content.size, mimeType } };
+        });
+        const rest = targets.filter(t => t !== target);
+        const { locations, remoteTargets } = await this.#commit(rest, finalKey, id, { file, cached: !target }, { checksums, size, mimeType }, options);
+        if (target) {
+            const stat = await target.backend.stat(finalKey);
+            const location = this.#buildLocation(target.name, finalKey, true, { size, mtime: stat.modified });
+            locations.splice(targets.indexOf(target), 0, location);
+        }
+        return { id, finalKey, checksums, size, mimeType, locations, remoteTargets, extracted };
+    }
+
+    // A file handed over by the caller: moved into the blob store when a
+    // target can adopt it (one rename, no copy); otherwise ingested as a
+    // stream and removed. Hashing reads the file only without caller checksums.
+    async #ingestAdopted(file, targets, key, mimeHint, options) {
+        const target = targets.find(t => typeof t.backend.adoptFile === 'function');
+        if (!target) {
+            try { return await this.#ingestStream(file, targets, key, mimeHint, options); }
+            finally { await fsp.rm(file, { force: true }); }
+        }
+        const known = options.checksums && this.#config.checksums.every(algo => /^[0-9a-f]+$/.test(options.checksums[algo] || ''));
+        const { checksums, size, head } = known
+            ? { checksums: Object.fromEntries(this.#config.checksums.map(algo => [algo, options.checksums[algo]])), size: (await fsp.stat(file)).size, head: await readHead(file) }
+            : await this.#hashFile(file);
+        const id = formatId(checksums, this.#config.primaryChecksum);
+        const finalKey = key || this.#generateKey(checksums);
+        const mimeType = mimeHint || await detectMimeFromHead(head, finalKey);
+        let extracted;
+        const adopted = await target.backend.adoptFile(file, { sha256: checksums.sha256, size }, async content => {
+            extracted = await this.#maybeExtract({ file: content.file }, mimeType, finalKey);
+            return finalKey;
+        });
+        const rest = targets.filter(t => t !== target);
+        const { locations, remoteTargets } = await this.#commit(rest, finalKey, id, { file: adopted.file, cached: false }, { checksums, size, mimeType }, options);
+        const stat = await target.backend.stat(finalKey);
+        locations.splice(targets.indexOf(target), 0, this.#buildLocation(target.name, finalKey, true, { size, mtime: stat.modified }));
+        return { id, finalKey, checksums, size, mimeType, locations, remoteTargets, extracted };
+    }
+
+    // One read pass over a file: checksums (all algorithms), size and head.
+    async #hashFile(file) {
+        const hashes = this.#config.checksums.map(algo => ({ algo, hash: crypto.createHash(algo) }));
+        let size = 0;
+        const headChunks = [];
+        let headLen = 0;
+        for await (const chunk of createReadStream(file)) {
+            for (const { hash } of hashes) hash.update(chunk);
+            size += chunk.length;
+            if (headLen < HEAD_BYTES) {
+                const slice = chunk.subarray(0, HEAD_BYTES - headLen);
+                headChunks.push(slice);
+                headLen += slice.length;
+            }
+        }
+        const checksums = {};
+        for (const { algo, hash } of hashes) checksums[algo] = hash.digest('hex');
+        return { checksums, size, head: Buffer.concat(headChunks) };
+    }
+
     // Single streaming pass: hash (all algorithms), measure size, peek the head
     // for mime sniffing, and write to `tempPath`. Never buffers the whole blob.
     async #hashToFile(source, tempPath) {
@@ -1686,6 +2275,8 @@ export default class Stored extends EventEmitter2 {
             }
             ws.end();
             await once(ws, 'finish');
+            const handle = await fsp.open(tempPath, 'r');
+            try { await handle.sync(); } finally { await handle.close(); }
         } catch (err) {
             ws.destroy();
             throw err;
@@ -1730,7 +2321,7 @@ export default class Stored extends EventEmitter2 {
             }
         }
 
-        if (remoteTargets.length) {
+        if (remoteTargets.length && !source.cached) {
             const cacheMeta = { key: finalKey, checksums: meta.checksums, size: meta.size, mimeType: meta.mimeType };
             if (source.data) await this.#cache.put(id, source.data, cacheMeta);
             else await pipeline(createReadStream(source.file), this.#cache.putStream(id, cacheMeta));
@@ -1751,9 +2342,11 @@ export default class Stored extends EventEmitter2 {
     // One-shot snapshot of a backend's indexed locations keyed by inode
     // identity, built per scan (the index is LMDB — a per-file reverse lookup
     // would be O(N²)).
-    #buildInodeMap(backendName) {
+    async #buildInodeMap(backendName) {
         const map = new Map();
+        let visited = 0;
         for (const [, meta] of this.#index.entries()) {
+            if (++visited % 128 === 0) await yieldToIO();
             for (const loc of meta.locations || []) {
                 if (loc.backend !== backendName || loc.ino == null) continue;
                 map.set(`${loc.dev}:${loc.ino}`, {
@@ -1859,8 +2452,10 @@ export default class Stored extends EventEmitter2 {
     // Emit a file event under both its typed name (`file:<suffix>`) and the
     // generic `object:<suffix>` (kind:'file') so consumers can bind either.
     #emitObject(suffix, payload) {
-        this.emit(`file:${suffix}`, payload);
-        this.emit(`object:${suffix}`, { kind: 'file', ...payload });
+        this.detachedStorageWork(() => {
+            this.emit(`file:${suffix}`, payload);
+            this.emit(`object:${suffix}`, { kind: 'file', ...payload });
+        });
     }
 
     // `options.force` bypasses the echo suppression — used when stored itself
@@ -2002,8 +2597,13 @@ export default class Stored extends EventEmitter2 {
             // deletion, and consumers never see the transient absence.
             const meta = this.#index.get(pathKey);
             const loc = meta?.locations?.find(l => l.backend === data.backend && l.key === data.key);
-            if (loc?.ino != null) {
-                const pendingKey = `${data.backend}|${loc.dev}:${loc.ino}`;
+            // A driver that names the inode in the event (the canvas driver:
+            // the content digest) is believed over the indexed location, which
+            // a put() created without one.
+            const ino = data.ino ?? loc?.ino ?? null;
+            const dev = data.ino != null ? data.dev : loc?.dev;
+            if (loc && ino != null) {
+                const pendingKey = `${data.backend}|${dev}:${ino}`;
                 // A second unlink for the same inode (hardlink twin) processes
                 // the held one immediately — one hold per inode.
                 const prior = this.#pendingUnlinks.get(pendingKey);
@@ -2032,6 +2632,7 @@ export default class Stored extends EventEmitter2 {
     #recheckUnlink(data) {
         const pathKey = `${data.backend}:${data.key}`;
         const timer = setTimeout(async () => {
+            if (this.#closing) return;
             if (this.#suppressedKeys.has(pathKey)) { this.#recheckUnlink(data); return; }
             const meta = this.#index.get(pathKey);
             if (!meta) return;