@augmentd-labs/canvas-edge 0.6.3 → 0.7.0

package/node_modules/canvas-stored/README.md

@@ -4,6 +4,71 @@
 
 # StoreD
 
+## Managed blob uploads and maintenance
+
+Stream/path uploads through `put()` with a cacache destination (or only remote
+destinations, using the transient cache) write directly through cacache's atomic
+content writer. Checksums and MIME sniffing run during
+that stream; extraction reads the completed blob. There is no separate Stored
+staging copy. Cacache still uses its own temporary file until the digest is
+known, then publishes it under the content hash. Additional destinations require
+their own copies; keyed filesystem edits and transfers retain their staging and
+precondition checks.
+
+Deleting a cache key releases its reference; unused bytes remain until explicit
+maintenance. Neither the managed backend nor the transient cache scans on a
+timer or during shutdown. `collectGarbage()` on either object walks the index
+and removes unreferenced blobs without reading payloads, rewriting the index,
+or clearing temporary files. It still holds live digest paths in memory and
+excludes writes for that root: schedule it as maintenance, not per deletion.
+Only one writer/maintenance owner may operate on a cache root at a time.
+
+`compact()` trims obsolete index history for each live key, preserving its newest
+digest and metadata. It neither reads blob contents nor reclaims unused blobs.
+
+`stored.cache.verify()` remains an explicitly requested, expensive integrity
+scrub. It reads all retained bytes and can discard corrupted content; it is
+not routine garbage collection. Preserve recovery copies before scrubbing.
+
+## File backend readiness
+
+`addBackend()` returns the backend immediately. Since 1.13, managed file roots
+are prepared asynchronously so a slow NAS `mkdir`/`stat` cannot block Node's
+event loop. Backend operations await this preparation. Code that accesses a
+new root directly through `fs` must first `await backend.ready()`. Initialization
+errors reject that promise. `createRoot: false` never creates a missing mount.
+
+`mutationDiagnostics` reports the active physical operation and queue length.
+An optional `onStall(report)` callback receives reports while an operation is
+still pending; it never releases a lock or abandons a write. Cancellation of
+`scan(name, { isCancelled })` throws `RESYNC_CANCELLED` before absence cleanup,
+including scans that return no files.
+
+## Backend Trash
+
+With `retention: { days: 30 }`, file backend deletions record each original path
+in durable Trash metadata. `listTrash(backend, { cursor, limit })` returns
+`{ items, cursor, retention }`; `restoreTrash(backend, id)` restores the recorded
+path without overwriting an occupied destination. Identical bytes can back
+multiple independent trash items, and overwritten versions are not listed as
+new deletions. Legacy retained entries with missing original paths are imported
+when listing Trash; recovery is limited to the path metadata still available.
+
+`trashDirectory(backend, key)` moves an entire folder to the backend staging
+directory's `trash/<id>`, preserving hidden/unindexed files and empty folders.
+After folder restoration, callers must scan and project that backend into their
+index (canvas-server does this automatically). Retention expiry removes Trash
+records and their recovery data. Retention errors stop destructive mutations.
+
+`discardTrash(backend, id)` permanently removes one Trash item without touching
+its original live path. Directory contents are removed from private trash;
+file blobs are released only after their last Trash/retained-version reference.
+Deletion intent is durable, retries are idempotent, and discard serializes with
+restore. A failed discard remains listed for retry and cannot be restored after
+deletion has started.
+
+## Overview
+
 Cache-first blob storage with a content-addressable local cache, LMDB metadata index and pluggable backends. Local backends write immediately; remote backends are fed from the cache by a sync queue (disk copies on a worker thread, network drivers such as Google Drive committed in-process).
 
 Used with canvas-server/synapsd to build virtual context trees over indexed data: checksum-based identity, multi-location replication, and `stored://` URLs as the canonical fetch form.
@@ -15,19 +80,38 @@ get(id)    → cacache → synced backend location → cache on read (buffers on
 
 Paths and streams are ingested without buffering the whole blob in memory (safe for 10GB+ files). Local-only puts never touch the cache; the cache + sync queue are used only when a remote backend is targeted.
 
+## Index recovery
+
+`Stored.open()` verifies an existing LMDB index before opening it. An unreadable
+index or a native verifier crash quarantines the complete environment in a unique
+sibling directory, `<index>.quarantine-<timestamp>-<suffix>/index`. The sibling
+also contains `recovery.json` recording the original path, time and failure.
+Startup logs the quarantine location and creates a fresh index. No quarantined
+files are deleted automatically. Backend files and the separate cache stay in place.
+
+Rescan each backend to rebuild byte metadata and location mappings. Verification
+timeouts, permission errors and verifier-launch failures do not trigger quarantine.
+If preserving the original environment fails, startup fails instead of replacing it.
+
+The environment also holds operational sub-databases (pending moves, replica
+ownership, sync state and trash records). These remain in quarantine; scanning
+reconstructs the byte inventory, not pending operations or their history. Retain
+the quarantined directory for recovery. Do not merge or replay its operations
+against the fresh index automatically.
+
 ## Quick start
 
 ### Simple example
 ```js
 import Stored from './src/index.js';
 
-const stored = new Stored({ root: './.stored' });
+const stored = await Stored.open({ root: './.stored' });
 stored.addBackend('fs:data', { driver: 'file', root: stored.dataPath });
 ```
 
 ### Backend configuration
 ```js
-const stored = new Stored({
+const stored = await Stored.open({
   root: './.stored',                    // → ./.stored/{index,cache,data}
   checksums: ['sha256'],                // sha256 is the default and the id/cache algorithm
   primaryChecksum: 'sha256',
@@ -59,10 +143,25 @@ await stored.stop();
 | `cacache` | local | Content-addressable blob store (managed; opaque keys) |
 | `gdrive` | remote | Google Drive folder subtree over OAuth refresh token — see below |
 | `canvas` | remote | One backend of a workspace on a canvas hub, over the objects/sync protocol — see *Sync engine* below |
-| `s3`, `http` | remote | Skeletons: URL parsing only (`http` has a read-only `get`) |
+| `s3` | remote | S3-compatible bucket/prefix: reads, indexing, polling and conditional create-only uploads |
+| `http` | remote | Read-only `get` / `stat` |
 
 Register additional drivers at runtime with `BackendManager.register(name, Class)` (`import BackendManager from 'canvas-stored/src/backends/BackendManager.js'`).
 
+Drivers declare their features through `static getCapabilities(config)`. Use
+`getBackendCapabilities(config)` (a named export from `canvas-stored`) to inspect
+a stopped/unconfigured backend without opening it, or
+`stored.getBackendCapabilities(name)` for the live instance, including runtime
+mount detection. Unknown drivers report no supported operations.
+
+`paths` means objects can keep a chosen folder/filename, including sub-folder
+paths: file, Google Drive, S3 key prefixes and Canvas hub backends support it;
+the content-addressed blob store and HTTP source do not. `mutableContainers`
+separately reports real folder creation/rename/deletion, including empty folders
+(file and Google Drive). `upload` reports create-only keyed uploads. Write
+features honor `readOnly`. These are driver features; safe replication/retirement
+capabilities remain available through `stored.replicas.capabilities(name)`.
+
 ### Google Drive backend
 
 ```js
@@ -83,6 +182,76 @@ stored.addBackend('gdrive:work', {
 - `watch()` emits `file:add|change|unlink` from the changes feed; renames/moves carry `ino = fileId`, so Stored's rename window rewrites the location in place instead of orphaning the document.
 - `verifyRoot()` → `{ ok, reason: 'unauthorized' | 'root-missing' | 'unreachable' }` is the liveness gate (credentials + root folder).
 
+### S3-compatible backend
+
+```js
+stored.addBackend('s3:accounting', {
+  driver: 's3',
+  bucket: 'accounting',                       // existing bucket; never created by the driver
+  prefix: 'Augmentd/Accounting',               // optional scope within the bucket
+  endpoint: 'https://s3.example.com',          // omit for Amazon S3
+  region: 'us-east-1',                        // use the region configured by your provider
+  forcePathStyle: true,                       // default true with a custom endpoint
+  accessKeyId: process.env.S3_ACCESS_KEY_ID,
+  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+  // sessionToken: process.env.S3_SESSION_TOKEN, // optional temporary credentials
+  readOnly: false,
+  watch: false,                              // opt in to full-list polling
+  pollInterval: 60000,                        // milliseconds, minimum 5000
+});
+```
+
+Uses the AWS SDK v3 with Signature V4. Amazon S3 uses its regional endpoint;
+MinIO, Garage, RustFS and Ceph RGW use their HTTP(S) endpoint, configured region
+and usually path-style addressing. The driver requires explicit credentials;
+it never falls back to the server's ambient IAM credentials. Canvas workspace
+settings expose the same connection fields and redact stored secrets. Rotating
+credentials is supported; changing a workspace backend's bucket, prefix or
+endpoint requires a new backend to preserve existing locations and pending plans.
+
+- `get`, streaming/ranged reads, `stat`, paginated `list`, `shape`, `scan`, and
+  optional `watch`/`poll` are implemented. Directory nodes come from object keys;
+  empty directory markers and folder mutations are not supported.
+- `put` and streaming `createFrom`/`commit` use conditional `If-None-Match: *`
+  writes with a content MD5. Existing keys are never overwritten. Single PUT
+  uploads are limited to **5 GiB**; larger uploads fail before publication.
+  Multipart/resumable upload is deferred.
+- Before allowing writes, each new driver instance tests conditional creation
+  on a random key under `<prefix>/.canvas-probe/`, checks the original bytes,
+  and deletes its probe. The key needs ListBucket scoped to the prefix, GetObject
+  and PutObject, plus DeleteObject on the probe prefix (DeleteObjectVersion on
+  versioned buckets). An endpoint that ignores preconditions is rejected before
+  writing user keys. Read-only connections do not probe writes.
+- ETags are observation tokens, **never content checksums or rename identity**.
+  Initial scans download bytes to hash them; subsequent scans reuse only hashes
+  matching the current ETag/version/size/time. Polling lists the prefix and checks
+  metadata, so budget remote requests and downloads. Failed/incomplete scans
+  never infer deletions. Remote renames are not inferred as user move intents.
+- Workspace `kind: "filing"` policies support automated copies with `error` or
+  `rename` conflicts. The existing durable replica executor verifies each exact
+  destination before releasing staging. Full mirrors, overwrite and automated
+  removal are refused. `delete()` is disabled unless `permanentDelete: true` is
+  explicitly configured; this manual opt-in does not enable mirror capabilities.
+
+`tests/s3.test.js` covers collision protection, incompatible endpoints, failed
+enumeration, mid-read changes and replica recovery. Run the live test against an
+isolated service with test credentials and permission to create/delete buckets:
+
+```sh
+CANVAS_S3_TEST_ENDPOINT=http://127.0.0.1:32768 node --test tests/s3-live.test.js
+```
+
+It creates and removes only a uniquely named test bucket. Optional variables are
+`CANVAS_S3_TEST_REGION`, `CANVAS_S3_TEST_ACCESS_KEY`, and
+`CANVAS_S3_TEST_SECRET_KEY`; the default test keys are `canvas-test` and
+`canvas-test-password`. Host port 32768 is an example, not a required port.
+Live validation used RustFS image digest
+`sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c`;
+other providers/versions still need qualification. See [TODO.md](TODO.md).
+
+Protocol references: [AWS conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)
+and [SDK checksum behavior](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/s3-checksums.html).
+
 ### Canvas hub backend
 
 ```js
@@ -105,6 +274,17 @@ Speaks `canvas-server/docs/sync-protocol.md`: `stat` = `HEAD`, `get`/`getRange`
 
 `copy()`/`move()` onto a `canvas` target stream straight to the hub (no temp file, cache or SyncQueue) and forward `ifMatch`/`ifNoneMatch`/`origin`/`mtime`/conflict headers; a `412` comes back as `{ ok:false, reason:'precondition-failed', current }`. A same-backend `move()`/`renameObject()` on the hub is one server-side rename.
 
+`renameDirectory(backend, from, to, { operationId, origin })` moves a complete
+directory on a writable local file backend with one native rename and an
+atomic index update. It preserves content identities and inodes, carries
+empty subdirectories, and does not stream or rehash the files. The destination
+must be absent; cross-filesystem moves fail without copying. Persist the
+unique `operationId` before the first request and reuse it on retry: a durable
+receipt recovers an interrupted index commit or acknowledges an already
+completed move without moving a recreated source. Different directory
+operations on the same backend are serialized; API callers must also
+serialize writes to either subtree (WorkspaceStoredIndex does this).
+
 ---
 
 ## Sync engine (device mirror)
@@ -112,7 +292,7 @@ Speaks `canvas-server/docs/sync-protocol.md`: `stat` = `HEAD`, `get`/`getRange`
 ```js
 import Stored, { Mirror } from 'canvas-stored';
 
-const stored = new Stored({ root: '~/Workspaces/notes/.workspace/db/stored' });
+const stored = await Stored.open({ root: '~/Workspaces/notes/.workspace/db/stored' });
 stored.addBackend('local',     { driver: 'file', root: '~/Workspaces/notes', watch: true, ignored: ['.workspace/**'] });
 stored.addBackend('trash',     { driver: 'file', root: '~/Workspaces/notes/.workspace/trash' });
 stored.addBackend('conflicts', { driver: 'file', root: '~/Workspaces/notes/.workspace/conflicts' });
@@ -124,7 +304,7 @@ const mirror = new Mirror(stored, {
   prefixes: [],                 // selective sync (prefixes / globs), applied on both sides
   ignore: [],                   // on top of MIRROR_IGNORE_DEFAULTS (+ the hub's exclusions you pass here)
   deletes: 'propagate',         // | 'keep'  — local deletes reach the hub, or only drop the base
-  conflictMode: 'prompt',       // | 'rename' — inbox upload, or Dropbox-style conflict copy on the hub
+  conflictMode: 'rename',       // default: conflict copy on the hub; 'prompt' opts into the inbox
   debounceMs: 1500, fullReconcileEvery: 6 * 3600e3,
 });
 await mirror.start();           // scan local → list/poll hub → reconcile → watch → worker
@@ -137,9 +317,9 @@ await mirror.stop();            // drains running jobs
 
 - **View**: Stored's index holds both sides — local keys through the file watcher/scan, hub keys through the `canvas` driver's feed poller. **Base ledger** (`Ledger`, LMDB sub-db `mirror`): `base/<mirror>/<key>` → `{ sha256, size, mtime, remoteSeq }`, `cursor/<mirror>`, `skip/<mirror>/<key>`, `state/<mirror>`. Keys + digests are the identity; hub document ids are never stored.
 - **Decision**: per dirty key, the protocol's three-way table (`decide(L, B, R)`, exported from `src/sync/Mirror.js`); R is confirmed with `HEAD` before a push or a conflict.
-- **Jobs** (`JobQueue`, LMDB sub-dbs `jobs` + `jobs.dedupe`): `push`, `pull`, `delete-remote`, `trash-local`, `rename-remote`, `rename-local`, `conflict`; dedupe per `<kind>|<key>`, backoff `min(60s·2^n, 1h)`, running→pending recovery on open, one job per key in flight, concurrency 4 (a brand-new key skips the pre-push HEAD; the PUT's If-None-Match:* guards it). Hub requests abort after `requestTimeoutMs` (60 s) plus an upload allowance (`minUploadBytesPerSec`, 50 kB/s) so a dropped connection never pins a worker. Every byte move goes through `stored.copy`/`move`/`renameObject`/`removeObject`, so locations, succession and echo suppression are the ordinary ones. Base is written only after the operation succeeded; the feed cursor after a whole batch reconciled.
+- **Jobs** (`JobQueue`, LMDB sub-dbs `jobs` + `jobs.dedupe`): `push`, `pull`, `delete-remote`, `trash-local`, `rename-remote`, `rename-remote-dir`, `rename-local`, `conflict`; dedupe per `<kind>|<key>`, backoff `min(60s·2^n, 1h)`, running→pending recovery on open, one job per key in flight, concurrency 4 (a brand-new key skips the pre-push HEAD; the PUT's If-None-Match:* guards it). Hub requests abort after `requestTimeoutMs` (60 s) plus an upload allowance (`minUploadBytesPerSec`, 50 kB/s) so a dropped connection never pins a worker. Every byte move goes through `stored.copy`/`move`/`renameObject`/`removeObject`, so locations, succession and echo suppression are the ordinary ones. Base is written only after the operation succeeded; the feed cursor after a whole batch reconciled.
 - **Conflicts** (`prompt`): the device version is copied to the `conflicts` backend as `<stem> (conflict from <device> <YYYY-MM-DD HHmm>).<ext>`, uploaded with `X-Canvas-Conflict-Of` (inbox), the hub version is pulled into place, base := R. `rename`: the upload is an ordinary object at the conflict-copy key (the hub tags it); the copy then arrives on every device like any other object.
-- **Renames**: a local `mv` (paired by Stored's inode window) → `POST objects/rename`; a hub rename → local `rename(2)` when the local copy is clean. **Hub delete** → local copy to the `trash` backend. **Offline** is a state: jobs stay queued, the engine retries with backoff and catches up (`poll`, or a full listing after `410`).
+- **Renames**: a local `mv` (paired by Stored's inode window, or by content after downtime) → `POST objects/rename`. Renames are collected for `moveSettleMs` (1.5 s); when a whole folder went (the source folder is gone from the device, the target is new to the hub) they are sent as one request with `directory: true`, whatever the number of files. An inferred local deletion waits `deleteDelayMs` (5 s) before it is sent, so the second half of a move can still claim it. A hub rename → local `rename(2)` when the local copy is clean. **Hub delete** → local copy to the `trash` backend. **Offline** is a state: jobs stay queued, the engine retries with backoff and catches up (`poll`, or a full listing after `410`).
 - **Keys**: `src/sync/keys.js` — `normalizeKey` (NFC, `/`), `validateKey` (traversal, NUL, Windows reserved names, `<>:"|?*`, trailing dot/space, length) → skipped visibly (`skip` event, `status().skips`), `isIgnored(key, patterns)` (picomatch, `dot:true`), `matchesPrefixes`, `conflictKey`, `MIRROR_IGNORE_DEFAULTS`.
 
 `JobQueue`, `Ledger`, `Mirror`, `BackendManager` and `Index` are named exports next to the default `Stored`.
@@ -179,7 +359,7 @@ The constructor extends **eventemitter2** with `wildcard: true` and `delimiter:
 | `index` | `Index` | LMDB metadata store |
 | `backends` | `BackendManager` | Registered backend instances |
 
-The `cache` wrapper exposes cacache maintenance helpers directly: `stats()` (entry count + total size, streamed so large stores are never held in memory), `clear()`, `verify()`, and `list()` / `listStream()`.
+The `cache` wrapper exposes cacache maintenance helpers directly: `stats()` (entry count + total size, streamed so large stores are never held in memory), `clear()`, `collectGarbage()`, `compact()`, `verify()`, and `list()` / `listStream()`.
 
 ---
 
@@ -356,7 +536,7 @@ Registered in `BackendManager` via `DRIVERS`:
 | `file` | `local` | complete | CRUD, chokidar `watch`, `scan` |
 | `cacache` | `local` | complete | Content-addressable blob store (cacache); CRUD, no `watch`/`scan` |
 | `http` | `remote` | partial | Read-only `get` / `stat` via `fetch`; `config.baseUrl`, `headers` |
-| `s3` | `remote` | skeleton | Registered for URL parsing; CRUD not implemented |
+| `s3` | `remote` | filing/read support | Conditional creates, streaming reads, scan/poll; mirrors and overwrite disabled |
 
 Each backend implements `StorageBackend`: `put`, `get`, `delete`, `stat`, `list`; optional `commit` (local, for streaming put), `watch`, `scan`, `stop`.
 

package/node_modules/canvas-stored/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-stored",
-  "version": "1.9.3",
+  "version": "1.18.0",
   "description": "",
   "main": "./src/index.js",
   "type": "module",
@@ -8,6 +8,6 @@
   "license": "AGPL-3.0-or-later",
   "dependencies": {},
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   }
 }

package/node_modules/canvas-stored/src/backends/BackendManager.js

@@ -8,7 +8,7 @@ import CanvasBackend from './canvas/index.js';
 
 const debug = Debug('stored:backends');
 
-// `s3`/`http` are skeletons (see their index.js). `smb`/`webdav` are reserved
+// `http` is a skeleton (see its index.js). S3 supports conditional filing copies. `smb`/`webdav` are reserved
 // scheme names with no driver yet — register a driver class here (or at
 // runtime via BackendManager.register) when implemented. `gdrive` is the first
 // real remote driver; `canvas` mirrors one backend of a workspace on another
@@ -27,6 +27,14 @@ export default class BackendManager {
 
     static drivers() { return Object.keys(DRIVERS); }
 
+    /** Driver-owned features, without credentials, I/O or starting a backend. */
+    static capabilities(config = {}) {
+        return DRIVERS[config.driver || 'file']?.getCapabilities?.(config) || {
+            read: false, write: false, delete: false, canEnumerate: false,
+            remote: false, paths: false, mutableContainers: false, upload: false,
+        };
+    }
+
     get(name) { return this.#backends.get(name); }
     has(name) { return this.#backends.has(name); }
     list() { return [...this.#backends.keys()]; }
@@ -58,3 +66,5 @@ export default class BackendManager {
         }
     }
 }
+
+export const getBackendCapabilities = (config) => BackendManager.capabilities(config);

package/node_modules/canvas-stored/src/backends/StorageBackend.js

@@ -20,11 +20,23 @@ export default class StorageBackend extends EventEmitter {
      * reference — its bytes cannot be removed by us.
      * `canEnumerate:true` means the backend implements the async-generator
      * `list()` (and usually `scan()`) so callers can mirror its whole tree;
-     * drivers without real enumeration (http, s3 skeleton) leave it false.
+     * drivers without real enumeration (http) leave it false.
      * `remote` mirrors the getter below — carried here so a single capabilities
      * snapshot is enough for consumers deciding how expensive an op will be.
      */
-    get capabilities() { return { read: true, write: true, delete: true, canEnumerate: false, remote: this.remote }; }
+    // Available without opening a backend (settings also list stopped mounts).
+    // paths: accepts a chosen folder/filename, including nested path segments.
+    // mutableContainers: can create/rename/delete actual folders, including
+    // empty ones. S3 prefixes support paths without supporting container ops.
+    // upload: supports create-only keyed uploads via createFrom().
+    static getCapabilities(config = {}) {
+        return {
+            read: true, write: config.readOnly !== true, delete: config.readOnly !== true,
+            canEnumerate: false, remote: config.remote === true,
+            paths: false, mutableContainers: false, upload: false,
+        };
+    }
+    get capabilities() { return { ...this.constructor.getCapabilities(this.config), remote: this.remote }; }
     get canDelete() { return this.capabilities.delete !== false; }
     get canWrite() { return this.capabilities.write !== false; }
     get canRead() { return this.capabilities.read !== false; }
@@ -46,17 +58,17 @@ export default class StorageBackend extends EventEmitter {
     // The real, protocol-native URL for `key` (e.g. https://…, s3://…, smb://…,
     // file://…), used for provenance/UI. `stored://<backend>/<key>` remains the
     // canonical fetch form. Returns null when the backend has no meaningful one.
-    nativeUrl(key) { return null; }
+    nativeUrl(_key) { return null; }
 
     // Required methods - must be implemented by subclasses
-    async put(key, data) { throw new Error('Not implemented'); }
+    async put(_key, _data) { throw new Error('Not implemented'); }
     // Place an already-written file at `key` (streaming put commit). Local
     // backends implement this; remote backends are fed via the cache + SyncQueue.
-    async commit(key, srcPath) { throw new Error('Not implemented'); }
-    async get(key, options = {}) { throw new Error('Not implemented'); }
-    async delete(key) { throw new Error('Not implemented'); }
-    async stat(key) { throw new Error('Not implemented'); }
-    async *list(options = {}) { throw new Error('Not implemented'); }
+    async commit(_key, _srcPath) { throw new Error('Not implemented'); }
+    async get(_key, _options = {}) { throw new Error('Not implemented'); }
+    async delete(_key) { throw new Error('Not implemented'); }
+    async stat(_key) { throw new Error('Not implemented'); }
+    list(_options = {}) { throw new Error('Not implemented'); }
 
     // Optional methods
     async watch() { return false; }
@@ -66,7 +78,7 @@ export default class StorageBackend extends EventEmitter {
     // Optional container (directory/folder) mutation — only backends with a real
     // hierarchical namespace (the file driver) implement these. Advertised via
     // the Workspace `mutableContainers` capability; callers must gate on it.
-    async createContainer(key) { throw new Error('Container ops not supported by this backend'); }
-    async deleteContainer(key) { throw new Error('Container ops not supported by this backend'); }
-    async renameContainer(fromKey, toKey) { throw new Error('Container ops not supported by this backend'); }
+    async createContainer(_key) { throw new Error('Container ops not supported by this backend'); }
+    async deleteContainer(_key) { throw new Error('Container ops not supported by this backend'); }
+    async renameContainer(_fromKey, _toKey) { throw new Error('Container ops not supported by this backend'); }
 }

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

@@ -4,6 +4,9 @@ import { createReadStream } from 'fs';
 import { pipeline } from 'stream/promises';
 import cacache from 'cacache';
 import contentPath from 'cacache/lib/content/path.js';
+import collectGarbage from '../../cache/collect-garbage.js';
+import ingestStream, { adoptFile } from '../../cache/ingest-stream.js';
+import compactIndex from '../../cache/compact-index.js';
 import Debug from 'debug';
 import StorageBackend from '../StorageBackend.js';
 
@@ -33,6 +36,7 @@ const CACHE_OPTS = { memoize: false };
 export default class CacacheBackend extends StorageBackend {
     #root;
     #algorithms;
+    #mutations = Promise.resolve();
 
     constructor(name, config = {}) {
         super(name, config);
@@ -41,19 +45,25 @@ export default class CacacheBackend extends StorageBackend {
         this.#algorithms = config.algorithms || ['sha256'];
         this.type = 'local';
         fs.ensureDirSync(this.#root);
+        // Explicit collection must never race an unpublished content write.
+        // All mutations and maintenance share this queue.
+        for (const method of ['put', 'commit', 'ingestStream', 'delete', 'clear']) {
+            const run = this[method].bind(this);
+            this[method] = (...args) => this.#serialize(() => run(...args));
+        }
         debug(`CacacheBackend "${name}" initialized at ${this.#root}`);
     }
 
     get root() { return this.#root; }
     // list() streams the cacache index, so full-key enumeration works even
     // though the store is opaque byte-wise.
-    get capabilities() { return { ...super.capabilities, canEnumerate: true }; }
-    // Staging dir for the Stored streaming-ingest hash pass (shares a filesystem
-    // with the store so the temp file is cheap to read back on commit).
-    get tempDir() { return path.join(this.#root, 'tmp'); }
+    static getCapabilities(config = {}) { return { ...super.getCapabilities(config), canEnumerate: true }; }
+    // Legacy keyed writes/transfers still stage before checking preconditions.
+    // Keep these outside cacache's tmp, which explicit verify() can remove.
+    get tempDir() { return path.join(this.#root, '.stored-tmp'); }
 
     // Internal blob store: no protocol-native URL to surface.
-    nativeUrl(key) { return null; }
+    nativeUrl(_key) { return null; }
 
     // ─────────────────────────────────────────────────────────────────────────
     // CRUD Operations
@@ -69,13 +79,28 @@ export default class CacacheBackend extends StorageBackend {
     // Commit an already-written file (the Stored streaming-ingest temp) at `key`
     // by streaming it into the content store.
     async commit(key, srcPath) {
-        await pipeline(createReadStream(srcPath), cacache.put.stream(this.#root, key, { algorithms: this.#algorithms, ...CACHE_OPTS }));
+        const output = cacache.put.stream(this.#root, key, { algorithms: this.#algorithms, ...CACHE_OPTS });
+        // An empty file emits no chunks; initialize cacache's content writer.
+        output.write(Buffer.alloc(0));
+        await pipeline(createReadStream(srcPath), output);
         const info = await cacache.get.info(this.#root, key);
         const size = info?.size ?? 0;
         debug(`COMMIT ${key} (${size} bytes)`);
         return { key, size };
     }
 
+    // Write bytes once using cacache's atomic content writer. A generated key
+    // is only known after EOF; resolveKey can inspect the completed blob before
+    // publication. Failed/aborted uploads never replace an existing key.
+    async ingestStream(source, resolveKey) {
+        return ingestStream(this.#root, source, async content => ({ key: await resolveKey(content) }), this.#algorithms);
+    }
+
+    // Move a finished file in instead of copying it (see adoptFile).
+    async adoptFile(file, digest, resolveKey) {
+        return adoptFile(this.#root, file, digest, async content => ({ key: await resolveKey(content) }), this.#algorithms);
+    }
+
     // Ranged read for HTTP Range/streaming: cacache has no ranged API, so read a
     // byte window straight off the content-addressed blob file. `end` is
     // inclusive (matches HTTP Range and fs.createReadStream). Returns null on a
@@ -125,6 +150,24 @@ export default class CacacheBackend extends StorageBackend {
         }
     }
 
+    #serialize(fn) {
+        const next = this.#mutations.catch(() => {}).then(fn);
+        this.#mutations = next;
+        return next;
+    }
+
+    collectGarbage() {
+        return this.#serialize(() => collectGarbage(this.#root));
+    }
+
+    // Explicit integrity scrub only: reads all bytes and may discard corruption.
+    verify() { return this.#serialize(() => cacache.verify(this.#root)); }
+    compact() { return this.#serialize(() => compactIndex(this.#root)); }
+
+    async stop() {
+        await this.#mutations;
+    }
+
     // Drop the whole content store (index + content). Used by Destroy/reset paths.
     async clear() { return cacache.rm.all(this.#root); }
 }

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

@@ -129,7 +129,9 @@ export default class CanvasBackend extends StorageBackend {
         debug(`CanvasBackend "${name}" initialized (${this.#url} ws=${this.#workspaceId} backend=${this.#backend})`);
     }
 
-    get capabilities() { return { read: true, write: true, delete: true, canEnumerate: true, remote: true }; }
+    static getCapabilities(config = {}) {
+        return { ...super.getCapabilities(config), canEnumerate: true, remote: true, paths: true };
+    }
     get remote() { return true; }
     /** Own writes never come back as events (origin-filtered) — Stored need not hold keys. */
     get suppressEchoes() { return false; }
@@ -198,7 +200,7 @@ export default class CanvasBackend extends StorageBackend {
         const { body: bodySpec, ...rest } = init;
         const streaming = bodySpec != null && typeof bodySpec !== 'function' && !Buffer.isBuffer(bodySpec) && typeof bodySpec !== 'string';
         const timeoutMs = this.#requestTimeoutMs + (uploadBytes > 0 ? Math.ceil(uploadBytes / this.#minUploadBytesPerSec) * 1000 : 0);
-        let last = null;
+        let last;
         for (let attempt = 0; ; attempt += 1) {
             const body = typeof bodySpec === 'function' ? bodySpec() : bodySpec;
             const options = { ...rest, headers: { ...this.#authHeaders(), ...(rest.headers || {}) } };
@@ -375,7 +377,12 @@ export default class CanvasBackend extends StorageBackend {
         if (cursor) u.searchParams.set('cursor', cursor);
         u.searchParams.set('limit', String(limit));
         const { payload } = await this.#json(u.toString());
-        const objects = (payload?.objects || []).map((o) => this.#row(normalizeKey(o.key), o));
+        // Anything but a real listing (a proxy error page, a captive portal
+        // answering 200) must not read as "the hub is empty".
+        if (!Array.isArray(payload?.objects) || !Number.isFinite(Number(payload?.head))) {
+            throw Object.assign(new Error('hub listing response is not a listing'), { code: 'BAD_LISTING' });
+        }
+        const objects = payload.objects.map((o) => this.#row(normalizeKey(o.key), o));
         const head = num(payload?.head, this.#head) ?? 0;
         this.#head = Math.max(this.#head, head);
         return { objects, cursor: payload?.cursor || null, head };
@@ -559,6 +566,36 @@ export default class CanvasBackend extends StorageBackend {
         return { from: fromKey, to: toKey, sha256: lower(payload?.sha256) || row?.checksums?.sha256 || null, seq, docId, version, size: row?.size ?? null, modified: row?.modified ?? null };
     }
 
+    /**
+     * `POST objects/rename` with `directory: true`: the hub moves the folder
+     * and everything under it in one operation. `operationId` makes a retry
+     * after a lost response return the first result.
+     */
+    async renameDirectory(from, to, { operationId, origin = null } = {}) {
+        const fromKey = normalizeKey(from);
+        const toKey = normalizeKey(to);
+        if (!fromKey || !toKey || !operationId) throw new CanvasHubError('canvas directory rename: from, to and operationId are required', { code: 'REFUSED' });
+        const body = { from: fromKey, to: toKey, directory: true, operationId };
+        if (origin || this.#deviceId) body.origin = origin || this.#deviceId;
+        const { payload } = await this.#json(`${this.#backendUrl()}/objects/rename`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        }, { key: fromKey });
+        if (payload?.directory !== true) throw new CanvasHubError('the hub did not acknowledge a directory rename', { code: 'REFUSED', hubCode: 'NOT_IMPLEMENTED', key: fromKey });
+        const prefix = `${fromKey}/`;
+        for (const [key, row] of [...this.#files]) {
+            if (!key.startsWith(prefix)) continue;
+            const next = `${toKey}/${key.slice(prefix.length)}`;
+            this.#files.delete(key);
+            this.#files.set(next, { ...row, key: next });
+        }
+        const seq = num(payload?.seq, 0);
+        if (seq) this.#head = Math.max(this.#head, seq);
+        debug(`RENAME ${fromKey}/ -> ${toKey}/ (seq ${seq})`);
+        return { from: fromKey, to: toKey, seq };
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // Change feed
     // ─────────────────────────────────────────────────────────────────────────
@@ -605,7 +642,7 @@ export default class CanvasBackend extends StorageBackend {
         if (this.#cursor == null) return { ok: false, reason: 'no-cursor' };
         let since = this.#cursor;
         let applied = 0;
-        let head = this.#head;
+        let head;
         try {
             for (;;) {
                 const page = await this.changes(since, CHANGES_PAGE);