@statewalker/webrun-files-composite 0.10.5 → 0.11.0

package/README.md

@@ -206,6 +206,39 @@ const draft = cow(templateFiles, new MemFilesApi());
 await draft.remove("/obsolete.md"); // recorded as /.wh.obsolete.md in the writable layer
 ```
 
+### Exclusive create through a composite
+
+```ts
+const fs = new CompositeFilesApi(nodeFiles).mount("/cache", memFiles);
+
+if (fs.createExclusive) {
+  await fs.createExclusive("/repo/.git/index.lock", [lockBytes]); // nodeFiles: O_EXCL
+  await fs.createExclusive("/cache/job.lock", [lockBytes]);       // memFiles: in-instance
+}
+
+fs.mount("/remote", httpFiles); // a backend without createExclusive...
+fs.createExclusive;             // ...hides it: undefined
+"createExclusive" in fs;        // false
+```
+
+`CompositeFilesApi` has `createExclusive` only while every backend, the root and each mount,
+has its own. A call goes to the backend that owns the path, so the exclusion reaches exactly as
+far as that backend's does. Defining the method and then refusing it for some paths would make
+feature detection lie, so a composite with one incapable mount has no method at all, and callers
+take their fallback. A mount point, and a directory that exists only because a mount lies under
+it, count as existing.
+
+Whether the method is there is decided at each access, `in` and `typeof` included: the
+composite is a proxy that asks its mounts, and `createExclusive` itself is a prototype method,
+so a subclass overrides it as usual. A reference to the method taken before a `mount()` of an
+incapable backend still calls, and throws for paths on that backend.
+
+`GuardedFilesApi` and `FilteredFilesApi` have the method while what they wrap has it, checked
+the same way at each access, so a guard or filter over a composite loses it when the composite
+does. A guard checks it as a `write`, and a filter refuses a hidden path with
+`"Path is hidden"`, as for `write`. So `readOnly()` throws. `overlay` (read-only) and `cow` do not offer it: a create in
+the writable layer of `cow` could not also exclude what the base and the whiteouts say.
+
 ## Internals
 
 ### How the decorators stack
@@ -253,6 +286,7 @@ filter to that mount only).
 | ------------ | --------------------------------------------------- |
 | `read`       | `read`                                              |
 | `write`      | `write`                                             |
+| `createExclusive` | `write`                                        |
 | `mkdir`      | `mkdir`                                             |
 | `remove`     | `remove`                                            |
 | `list`       | `list` on the path AND on each directory entry      |
@@ -274,13 +308,23 @@ multiple operation lists.
 | `exists`            | `false`                  |
 | `remove`            | `false`                  |
 | `move` / `copy`     | `false` (no side effect) |
-| `write` / `mkdir`   | throws `"Path is hidden"` (silent drop would lose data) |
+| `write` / `mkdir` / `createExclusive` | throws `"Path is hidden"` (silent drop would lose data) |
 
 ### What it refuses, and what is not atomic
 
 - The root mount (`/`) is fixed at construction; you cannot remount it.
 - Mount points are immutable — `remove()` on a mount point throws.
-- Cross-mount `move` is copy + delete; not atomic.
+- Cross-mount `move` is copy + delete; not atomic: while it runs the content exists in both
+  places. If the copy succeeds but the source cannot be removed, the removal is retried once,
+  then `move` throws a `MoveIncompleteError` (the target holds the new content, the source still
+  exists) instead of returning `false`. A move within one mount is delegated, and is as atomic
+  as that backend's.
+- `cow` `move` is copy + delete too, and not atomic: the composite view of the source is copied
+  into the writable layer, then the source is removed (or hidden behind a whiteout). A source
+  that cannot be removed is retried once, then throws `MoveIncompleteError`. An existing target
+  is treated as `rename(2)` treats it, like `MemFilesApi`: a file replaces a file and a directory
+  an empty directory; a file onto a directory, a directory onto a file or a non-empty directory,
+  a directory into its own subtree, or a target below a file returns `false` and changes nothing.
 - `newPathFilter()` (no args) hides nothing; entries that normalize to
   `"/"` (empty string, `"/"`) are dropped because they would otherwise hide
   the whole tree.

package/dist/cjs/index.cjs

@@ -122,6 +122,46 @@ var PathHeap = class {
 	}
 };
 /**
+* Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+* could not be removed, even on a second attempt. The move is half done: the target
+* already holds the moved content (an existing target was replaced), and the source
+* still exists. A `false` would wrongly say that nothing happened, so this is thrown
+* instead.
+*
+* @example
+* try {
+*   await files.move("/repo/index.lock", "/repo/index");
+* } catch (error) {
+*   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+*   else throw error;
+* }
+*/
+var MoveIncompleteError = class extends Error {
+	source;
+	target;
+	name = "MoveIncompleteError";
+	constructor(source, target, options) {
+		super(`move ${source} -> ${target}: the target was replaced, but the source could not be removed`, options);
+		this.source = source;
+		this.target = target;
+	}
+};
+/**
+* The second half of a copy-then-delete `move`: remove `source` after it has been copied
+* to `target`. A failed removal (an error, or `false` while the source still exists) is
+* retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+* last error as its cause. A source that is already gone counts as removed.
+*/
+async function removeMovedSource(files, source, target) {
+	let cause;
+	for (let attempt = 0; attempt < 2; attempt++) try {
+		if (await files.remove(source) || !await files.exists(source)) return;
+	} catch (error) {
+		cause = error;
+	}
+	throw new MoveIncompleteError(source, target, { cause });
+}
+/**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
 */
@@ -162,6 +202,29 @@ function basename(path, ext) {
 	if (ext && name.endsWith(ext)) return name.substring(0, name.length - ext.length);
 	return name;
 }
+// src/follow-create-exclusive.ts
+/**
+* Wrap `target` so that its `createExclusive` exists only while `isAvailable()` says so,
+* checked on every access: both `"createExclusive" in api` and
+* `typeof api.createExclusive` then follow the backend(s) the object delegates to, even
+* as those change (a `mount()` of a backend without the method, say), and a subclass
+* that overrides the method is hidden or shown the same way.
+*
+* Constructors return the result, so the object every caller holds is the proxy; `this`
+* inside methods is the proxy too, and every other property passes straight through.
+*/
+function followCreateExclusive(target, isAvailable) {
+	return new Proxy(target, {
+		has(object, key) {
+			if (key === "createExclusive" && !isAvailable()) return false;
+			return Reflect.has(object, key);
+		},
+		get(object, key, receiver) {
+			if (key === "createExclusive" && !isAvailable()) return void 0;
+			return Reflect.get(object, key, receiver);
+		}
+	});
+}
 // src/composite-files-api.ts
 /**
 * Composite `FilesApi` that routes calls to one of several backends based
@@ -173,7 +236,7 @@ function basename(path, ext) {
 * Each backend can use a sub-directory of its own filesystem as the mount
 * root via `fsPath` (constructor `rootPath` for the implicit root mount,
 * `fsPath` argument for additional mounts). Cross-mount `move` is
-* implemented as copy-then-delete; there is no atomicity guarantee.
+* implemented as copy-then-delete; there is no atomicity guarantee (see `move`).
 *
 * Access control and visibility filtering are intentionally **not** part of
 * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
@@ -205,6 +268,27 @@ var CompositeFilesApi = class {
 			api: root,
 			basePath: normalizePath(rootPath ?? "/")
 		}];
+		return followCreateExclusive(this, () => this.mounts.every((m) => typeof m.api.createExclusive === "function"));
+	}
+	/**
+	* Present only while EVERY backend — the root and each mount — has its own
+	* `createExclusive`, so feature detection on the composite tells the truth for
+	* any path: `"createExclusive" in composite` and `typeof composite.createExclusive`
+	* are checked against the mounts at each access. Mounting a backend without it hides
+	* the method; it is never shown and then refused for some paths. (A reference taken
+	* before such a mount still calls; it throws for paths on a backend without it.)
+	* It is a prototype method, so a subclass overrides it as usual.
+	*
+	* A call goes to the backend owning the path, so the exclusion reaches as far
+	* as that backend's does. A mount point, and a directory that exists only
+	* because a mount lies under it, count as existing.
+	*/
+	async createExclusive(path, content) {
+		const normalized = normalizePath(path);
+		if (this.mounts.some((m) => m.prefix !== "/" && isInsideOrSame(m.prefix, normalized))) return false;
+		const { api, resolvedPath } = this.resolve(normalized);
+		if (!api.createExclusive) throw new Error(`createExclusive is not supported by the backend for ${normalized}`);
+		return api.createExclusive(resolvedPath, content);
 	}
 	/**
 	* Attaches a backend to handle every composite path under `path`. The
@@ -354,13 +438,27 @@ var CompositeFilesApi = class {
 		const { api, resolvedPath } = this.resolve(path);
 		return api.remove(resolvedPath);
 	}
+	/**
+	* Within one mount the move is delegated, so it is exactly as atomic as that
+	* backend's `move` (and treats an existing target as that backend does).
+	*
+	* Across mounts it can only be a copy, then a delete, and is NOT atomic: while it
+	* runs, the content exists in both places, and a directory appears in the target
+	* file by file. A failed copy throws and keeps the source. If the copy succeeds but
+	* the source cannot be removed, the removal is retried once, then a
+	* `MoveIncompleteError` is thrown: the target holds the new content and the source
+	* still exists. False is never returned for a half-done move.
+	*/
 	async move(source, target) {
 		const src = this.resolve(source);
 		const tgt = this.resolve(target);
 		if (src.api === tgt.api) return src.api.move(src.resolvedPath, tgt.resolvedPath);
-		const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
-		if (copied) await src.api.remove(src.resolvedPath);
-		return copied;
+		if (!await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath)) return false;
+		await removeMovedSource({
+			remove: () => src.api.remove(src.resolvedPath),
+			exists: () => src.api.exists(src.resolvedPath)
+		}, normalizePath(source), normalizePath(target));
+		return true;
 	}
 	async copy(source, target) {
 		const src = this.resolve(source);
@@ -410,6 +508,9 @@ function translateAfter(after, from, to) {
 	if (comparePaths(after, `${fromPrefix}/`) < 0) return void 0;
 	return SKIP;
 }
+function isInsideOrSame(path, ancestor) {
+	return path === ancestor || isStrictlyInside(path, ancestor);
+}
 function isStrictlyInside(path, ancestor) {
 	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
 }
@@ -537,11 +638,41 @@ var CowFilesApi = class {
 		}
 		return true;
 	}
+	/**
+	* NOT atomic: the composite view of the source is copied into the writable layer,
+	* then the source is removed (deleted from the writable layer and/or hidden behind
+	* a whiteout). While it runs the content exists in both places, and a directory
+	* appears in the target file by file. A failed copy throws and keeps the source. If
+	* the copy succeeds but the source cannot be removed, the removal is retried once,
+	* then a `MoveIncompleteError` is thrown: the target holds the new content and the
+	* source still exists. False is never returned for a half-done move.
+	*
+	* An existing target (as the composite view shows it) is treated as POSIX
+	* `rename(2)` treats it, like `MemFilesApi` and `NodeFilesApi`: a file replaces a
+	* file, and a directory replaces an empty directory. Everything else returns false
+	* and changes nothing: a file onto a directory, a directory onto a file or onto a
+	* non-empty directory, a directory into its own subtree, a target below a file, and
+	* a missing source. A move onto itself is a successful no-op.
+	*/
 	async move(source, target) {
-		const stats = await this.stats(source);
+		const from = normalizePath(source);
+		const to = normalizePath(target);
+		const stats = await this.stats(from);
 		if (!stats) return false;
-		await this.copyInto(source, target, stats);
-		await this.remove(source);
+		if (from === to) return true;
+		if (from === "/" || to.startsWith(`${from}/`)) return false;
+		for (let dir = dirname(to); dir !== "/"; dir = dirname(dir)) {
+			const kind = (await this.stats(dir))?.kind;
+			if (kind === "file") return false;
+			if (kind === "directory") break;
+		}
+		const targetStats = await this.stats(to);
+		if (targetStats) {
+			if (targetStats.kind !== stats.kind) return false;
+			if (targetStats.kind === "directory") for await (const _ of this.list(to)) return false;
+		}
+		await this.copyInto(from, to, stats);
+		await removeMovedSource(this, from, to);
 		return true;
 	}
 	async copy(source, target) {
@@ -777,7 +908,8 @@ function newGlobPathFilter(...pathGlobs) {
 * - `remove` returns `false` (no error, nothing changed).
 * - `move` / `copy` return `false` if either endpoint is hidden.
 * - `write` / `mkdir` reject with an `Error` (since silently dropping a
-*   write would lose data).
+*   write would lose data), and so does `createExclusive`, which the
+*   decorator has only when the source has it.
 * - `list` recursively skips entries whose paths are hidden, so iterating a
 *   visible parent never reveals a hidden child.
 *
@@ -827,6 +959,17 @@ var FilteredFilesApi = class {
 	constructor(source, pathFilter) {
 		this.source = source;
 		this.pathFilter = pathFilter;
+		return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+	}
+	/**
+	* Present only while the source has it, checked at each access (`in` and `typeof`
+	* included), so it follows a source whose methods change, such as a
+	* `CompositeFilesApi` after `mount()`. The exclusion is the source's own.
+	*/
+	async createExclusive(path, content) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		if (!this.source.createExclusive) throw new Error(`createExclusive is not supported by the source for ${path}`);
+		return this.source.createExclusive(path, content);
 	}
 	async isHidden(path) {
 		return await this.pathFilter(normalizePath(path)) === false;
@@ -886,6 +1029,7 @@ var FilteredFilesApi = class {
 * | ------------- | --------------------------------------------------- |
 * | `read`        | `read`                                              |
 * | `write`       | `write`                                             |
+* | `createExclusive` | `write`                                         |
 * | `mkdir`       | `mkdir`                                             |
 * | `remove`      | `remove`                                            |
 * | `list`        | `list` on the path AND on each directory entry      |
@@ -924,6 +1068,18 @@ var GuardedFilesApi = class {
 	constructor(source, guards) {
 		this.source = source;
 		this.guards = [...guards];
+		return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+	}
+	/**
+	* Present only while the source has it, checked at each access (`in` and `typeof`
+	* included), so it follows a source whose methods change, such as a
+	* `CompositeFilesApi` after `mount()`. A `write`-guarded pass-through, so the
+	* exclusion is the source's own.
+	*/
+	async createExclusive(path, content) {
+		this.checkGuard(path, "write");
+		if (!this.source.createExclusive) throw new Error(`createExclusive is not supported by the source for ${path}`);
+		return this.source.createExclusive(path, content);
 	}
 	checkGuard(path, ...operations) {
 		const normalized = normalizePath(path);

package/dist/composite-files-api.d.ts

@@ -9,7 +9,7 @@ import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@s
  * Each backend can use a sub-directory of its own filesystem as the mount
  * root via `fsPath` (constructor `rootPath` for the implicit root mount,
  * `fsPath` argument for additional mounts). Cross-mount `move` is
- * implemented as copy-then-delete; there is no atomicity guarantee.
+ * implemented as copy-then-delete; there is no atomicity guarantee (see `move`).
  *
  * Access control and visibility filtering are intentionally **not** part of
  * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
@@ -36,6 +36,20 @@ export declare class CompositeFilesApi implements FilesApi {
      *   in the root backend. Defaults to `"/"` (no remapping).
      */
     constructor(root: FilesApi, rootPath?: string);
+    /**
+     * Present only while EVERY backend — the root and each mount — has its own
+     * `createExclusive`, so feature detection on the composite tells the truth for
+     * any path: `"createExclusive" in composite` and `typeof composite.createExclusive`
+     * are checked against the mounts at each access. Mounting a backend without it hides
+     * the method; it is never shown and then refused for some paths. (A reference taken
+     * before such a mount still calls; it throws for paths on a backend without it.)
+     * It is a prototype method, so a subclass overrides it as usual.
+     *
+     * A call goes to the backend owning the path, so the exclusion reaches as far
+     * as that backend's does. A mount point, and a directory that exists only
+     * because a mount lies under it, count as existing.
+     */
+    createExclusive?(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     /**
      * Attaches a backend to handle every composite path under `path`. The
      * mount prefix is normalized; paths under it are resolved against the
@@ -80,6 +94,17 @@ export declare class CompositeFilesApi implements FilesApi {
     stats(path: string): Promise<FileStats | undefined>;
     exists(path: string): Promise<boolean>;
     remove(path: string): Promise<boolean>;
+    /**
+     * Within one mount the move is delegated, so it is exactly as atomic as that
+     * backend's `move` (and treats an existing target as that backend does).
+     *
+     * Across mounts it can only be a copy, then a delete, and is NOT atomic: while it
+     * runs, the content exists in both places, and a directory appears in the target
+     * file by file. A failed copy throws and keeps the source. If the copy succeeds but
+     * the source cannot be removed, the removal is retried once, then a
+     * `MoveIncompleteError` is thrown: the target holds the new content and the source
+     * still exists. False is never returned for a half-done move.
+     */
     move(source: string, target: string): Promise<boolean>;
     copy(source: string, target: string): Promise<boolean>;
     private crossCopy;

package/dist/composite-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AASnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAE5C;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED;;;;;;;;OAQG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAoDxE;IAED;;;OAGG;YACY,YAAY;IAiB3B,qFAAqF;IACrF,OAAO,CAAC,OAAO;IAaT,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3D;YAIa,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}
+{"version":3,"file":"composite-files-api.d.ts","sourceRoot":"","sources":["../src/composite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAgBnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAAe;IAE7B;;;;;;;;OAQG;IACH,YAAY,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,EAM5C;IAED;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAUlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CASxD;IAID,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,YAAY;IAKpB,yEAAyE;IACzE,OAAO,CAAC,kBAAkB;IAkB1B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED;;;;;;;;OAQG;IACI,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAoDxE;IAED;;;OAGG;YACY,YAAY;IAiB3B,qFAAqF;IACrF,OAAO,CAAC,OAAO;IAaT,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAOxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3C;IAED;;;;;;;;;;OAUG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAW3D;YAIa,SAAS;IA4BvB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/cow-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AASnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}
+{"version":3,"file":"cow-files-api.d.ts","sourceRoot":"","sources":["../src/cow-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,QAAQ,EAGT,MAAM,2BAA2B,CAAC;AAUnC,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,CAEnF"}

package/dist/esm/index.js

@@ -121,6 +121,46 @@ var PathHeap = class {
 	}
 };
 /**
+* Thrown by a `move` done as copy-then-delete when the copy succeeded but the source
+* could not be removed, even on a second attempt. The move is half done: the target
+* already holds the moved content (an existing target was replaced), and the source
+* still exists. A `false` would wrongly say that nothing happened, so this is thrown
+* instead.
+*
+* @example
+* try {
+*   await files.move("/repo/index.lock", "/repo/index");
+* } catch (error) {
+*   if (error instanceof MoveIncompleteError) await files.remove(error.source);
+*   else throw error;
+* }
+*/
+var MoveIncompleteError = class extends Error {
+	source;
+	target;
+	name = "MoveIncompleteError";
+	constructor(source, target, options) {
+		super(`move ${source} -> ${target}: the target was replaced, but the source could not be removed`, options);
+		this.source = source;
+		this.target = target;
+	}
+};
+/**
+* The second half of a copy-then-delete `move`: remove `source` after it has been copied
+* to `target`. A failed removal (an error, or `false` while the source still exists) is
+* retried once; should that fail too, {@link MoveIncompleteError} is thrown, carrying the
+* last error as its cause. A source that is already gone counts as removed.
+*/
+async function removeMovedSource(files, source, target) {
+	let cause;
+	for (let attempt = 0; attempt < 2; attempt++) try {
+		if (await files.remove(source) || !await files.exists(source)) return;
+	} catch (error) {
+		cause = error;
+	}
+	throw new MoveIncompleteError(source, target, { cause });
+}
+/**
 * Path manipulation utilities for virtual filesystem paths.
 * All paths use forward slashes and start with "/".
 */
@@ -161,6 +201,29 @@ function basename(path, ext) {
 	if (ext && name.endsWith(ext)) return name.substring(0, name.length - ext.length);
 	return name;
 }
+// src/follow-create-exclusive.ts
+/**
+* Wrap `target` so that its `createExclusive` exists only while `isAvailable()` says so,
+* checked on every access: both `"createExclusive" in api` and
+* `typeof api.createExclusive` then follow the backend(s) the object delegates to, even
+* as those change (a `mount()` of a backend without the method, say), and a subclass
+* that overrides the method is hidden or shown the same way.
+*
+* Constructors return the result, so the object every caller holds is the proxy; `this`
+* inside methods is the proxy too, and every other property passes straight through.
+*/
+function followCreateExclusive(target, isAvailable) {
+	return new Proxy(target, {
+		has(object, key) {
+			if (key === "createExclusive" && !isAvailable()) return false;
+			return Reflect.has(object, key);
+		},
+		get(object, key, receiver) {
+			if (key === "createExclusive" && !isAvailable()) return void 0;
+			return Reflect.get(object, key, receiver);
+		}
+	});
+}
 // src/composite-files-api.ts
 /**
 * Composite `FilesApi` that routes calls to one of several backends based
@@ -172,7 +235,7 @@ function basename(path, ext) {
 * Each backend can use a sub-directory of its own filesystem as the mount
 * root via `fsPath` (constructor `rootPath` for the implicit root mount,
 * `fsPath` argument for additional mounts). Cross-mount `move` is
-* implemented as copy-then-delete; there is no atomicity guarantee.
+* implemented as copy-then-delete; there is no atomicity guarantee (see `move`).
 *
 * Access control and visibility filtering are intentionally **not** part of
 * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
@@ -204,6 +267,27 @@ var CompositeFilesApi = class {
 			api: root,
 			basePath: normalizePath(rootPath ?? "/")
 		}];
+		return followCreateExclusive(this, () => this.mounts.every((m) => typeof m.api.createExclusive === "function"));
+	}
+	/**
+	* Present only while EVERY backend — the root and each mount — has its own
+	* `createExclusive`, so feature detection on the composite tells the truth for
+	* any path: `"createExclusive" in composite` and `typeof composite.createExclusive`
+	* are checked against the mounts at each access. Mounting a backend without it hides
+	* the method; it is never shown and then refused for some paths. (A reference taken
+	* before such a mount still calls; it throws for paths on a backend without it.)
+	* It is a prototype method, so a subclass overrides it as usual.
+	*
+	* A call goes to the backend owning the path, so the exclusion reaches as far
+	* as that backend's does. A mount point, and a directory that exists only
+	* because a mount lies under it, count as existing.
+	*/
+	async createExclusive(path, content) {
+		const normalized = normalizePath(path);
+		if (this.mounts.some((m) => m.prefix !== "/" && isInsideOrSame(m.prefix, normalized))) return false;
+		const { api, resolvedPath } = this.resolve(normalized);
+		if (!api.createExclusive) throw new Error(`createExclusive is not supported by the backend for ${normalized}`);
+		return api.createExclusive(resolvedPath, content);
 	}
 	/**
 	* Attaches a backend to handle every composite path under `path`. The
@@ -353,13 +437,27 @@ var CompositeFilesApi = class {
 		const { api, resolvedPath } = this.resolve(path);
 		return api.remove(resolvedPath);
 	}
+	/**
+	* Within one mount the move is delegated, so it is exactly as atomic as that
+	* backend's `move` (and treats an existing target as that backend does).
+	*
+	* Across mounts it can only be a copy, then a delete, and is NOT atomic: while it
+	* runs, the content exists in both places, and a directory appears in the target
+	* file by file. A failed copy throws and keeps the source. If the copy succeeds but
+	* the source cannot be removed, the removal is retried once, then a
+	* `MoveIncompleteError` is thrown: the target holds the new content and the source
+	* still exists. False is never returned for a half-done move.
+	*/
 	async move(source, target) {
 		const src = this.resolve(source);
 		const tgt = this.resolve(target);
 		if (src.api === tgt.api) return src.api.move(src.resolvedPath, tgt.resolvedPath);
-		const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
-		if (copied) await src.api.remove(src.resolvedPath);
-		return copied;
+		if (!await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath)) return false;
+		await removeMovedSource({
+			remove: () => src.api.remove(src.resolvedPath),
+			exists: () => src.api.exists(src.resolvedPath)
+		}, normalizePath(source), normalizePath(target));
+		return true;
 	}
 	async copy(source, target) {
 		const src = this.resolve(source);
@@ -409,6 +507,9 @@ function translateAfter(after, from, to) {
 	if (comparePaths(after, `${fromPrefix}/`) < 0) return void 0;
 	return SKIP;
 }
+function isInsideOrSame(path, ancestor) {
+	return path === ancestor || isStrictlyInside(path, ancestor);
+}
 function isStrictlyInside(path, ancestor) {
 	return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
 }
@@ -536,11 +637,41 @@ var CowFilesApi = class {
 		}
 		return true;
 	}
+	/**
+	* NOT atomic: the composite view of the source is copied into the writable layer,
+	* then the source is removed (deleted from the writable layer and/or hidden behind
+	* a whiteout). While it runs the content exists in both places, and a directory
+	* appears in the target file by file. A failed copy throws and keeps the source. If
+	* the copy succeeds but the source cannot be removed, the removal is retried once,
+	* then a `MoveIncompleteError` is thrown: the target holds the new content and the
+	* source still exists. False is never returned for a half-done move.
+	*
+	* An existing target (as the composite view shows it) is treated as POSIX
+	* `rename(2)` treats it, like `MemFilesApi` and `NodeFilesApi`: a file replaces a
+	* file, and a directory replaces an empty directory. Everything else returns false
+	* and changes nothing: a file onto a directory, a directory onto a file or onto a
+	* non-empty directory, a directory into its own subtree, a target below a file, and
+	* a missing source. A move onto itself is a successful no-op.
+	*/
 	async move(source, target) {
-		const stats = await this.stats(source);
+		const from = normalizePath(source);
+		const to = normalizePath(target);
+		const stats = await this.stats(from);
 		if (!stats) return false;
-		await this.copyInto(source, target, stats);
-		await this.remove(source);
+		if (from === to) return true;
+		if (from === "/" || to.startsWith(`${from}/`)) return false;
+		for (let dir = dirname(to); dir !== "/"; dir = dirname(dir)) {
+			const kind = (await this.stats(dir))?.kind;
+			if (kind === "file") return false;
+			if (kind === "directory") break;
+		}
+		const targetStats = await this.stats(to);
+		if (targetStats) {
+			if (targetStats.kind !== stats.kind) return false;
+			if (targetStats.kind === "directory") for await (const _ of this.list(to)) return false;
+		}
+		await this.copyInto(from, to, stats);
+		await removeMovedSource(this, from, to);
 		return true;
 	}
 	async copy(source, target) {
@@ -776,7 +907,8 @@ function newGlobPathFilter(...pathGlobs) {
 * - `remove` returns `false` (no error, nothing changed).
 * - `move` / `copy` return `false` if either endpoint is hidden.
 * - `write` / `mkdir` reject with an `Error` (since silently dropping a
-*   write would lose data).
+*   write would lose data), and so does `createExclusive`, which the
+*   decorator has only when the source has it.
 * - `list` recursively skips entries whose paths are hidden, so iterating a
 *   visible parent never reveals a hidden child.
 *
@@ -826,6 +958,17 @@ var FilteredFilesApi = class {
 	constructor(source, pathFilter) {
 		this.source = source;
 		this.pathFilter = pathFilter;
+		return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+	}
+	/**
+	* Present only while the source has it, checked at each access (`in` and `typeof`
+	* included), so it follows a source whose methods change, such as a
+	* `CompositeFilesApi` after `mount()`. The exclusion is the source's own.
+	*/
+	async createExclusive(path, content) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		if (!this.source.createExclusive) throw new Error(`createExclusive is not supported by the source for ${path}`);
+		return this.source.createExclusive(path, content);
 	}
 	async isHidden(path) {
 		return await this.pathFilter(normalizePath(path)) === false;
@@ -885,6 +1028,7 @@ var FilteredFilesApi = class {
 * | ------------- | --------------------------------------------------- |
 * | `read`        | `read`                                              |
 * | `write`       | `write`                                             |
+* | `createExclusive` | `write`                                         |
 * | `mkdir`       | `mkdir`                                             |
 * | `remove`      | `remove`                                            |
 * | `list`        | `list` on the path AND on each directory entry      |
@@ -923,6 +1067,18 @@ var GuardedFilesApi = class {
 	constructor(source, guards) {
 		this.source = source;
 		this.guards = [...guards];
+		return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+	}
+	/**
+	* Present only while the source has it, checked at each access (`in` and `typeof`
+	* included), so it follows a source whose methods change, such as a
+	* `CompositeFilesApi` after `mount()`. A `write`-guarded pass-through, so the
+	* exclusion is the source's own.
+	*/
+	async createExclusive(path, content) {
+		this.checkGuard(path, "write");
+		if (!this.source.createExclusive) throw new Error(`createExclusive is not supported by the source for ${path}`);
+		return this.source.createExclusive(path, content);
 	}
 	checkGuard(path, ...operations) {
 		const normalized = normalizePath(path);

package/dist/filtered-files-api.d.ts

@@ -105,7 +105,8 @@ export declare function newGlobPathFilter(...pathGlobs: string[]): PathFilter;
  * - `remove` returns `false` (no error, nothing changed).
  * - `move` / `copy` return `false` if either endpoint is hidden.
  * - `write` / `mkdir` reject with an `Error` (since silently dropping a
- *   write would lose data).
+ *   write would lose data), and so does `createExclusive`, which the
+ *   decorator has only when the source has it.
  * - `list` recursively skips entries whose paths are hidden, so iterating a
  *   visible parent never reveals a hidden child.
  *
@@ -153,6 +154,12 @@ export declare class FilteredFilesApi implements FilesApi {
      *   path is visible. See {@link PathFilter}.
      */
     constructor(source: FilesApi, pathFilter: PathFilter);
+    /**
+     * Present only while the source has it, checked at each access (`in` and `typeof`
+     * included), so it follows a source whose methods change, such as a
+     * `CompositeFilesApi` after `mount()`. The exclusion is the source's own.
+     */
+    createExclusive?(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     protected isHidden(path: string): Promise<boolean>;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;

package/dist/filtered-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-files-api.d.ts","sourceRoot":"","sources":["../src/filtered-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAGnD;IAED,UAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEvD;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAG1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAKf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAMxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;CACF"}
+{"version":3,"file":"filtered-files-api.d.ts","sourceRoot":"","sources":["../src/filtered-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAKnC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,UAAU,CAUnE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,UAAU,CAQxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,UAAU,CAGpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAKnD;IAED;;;;OAIG;IACG,eAAe,CAAC,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAQlB;IAED,UAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEvD;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAG1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAKf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAMxE;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3D;CACF"}

package/dist/follow-create-exclusive.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wrap `target` so that its `createExclusive` exists only while `isAvailable()` says so,
+ * checked on every access: both `"createExclusive" in api` and
+ * `typeof api.createExclusive` then follow the backend(s) the object delegates to, even
+ * as those change (a `mount()` of a backend without the method, say), and a subclass
+ * that overrides the method is hidden or shown the same way.
+ *
+ * Constructors return the result, so the object every caller holds is the proxy; `this`
+ * inside methods is the proxy too, and every other property passes straight through.
+ */
+export declare function followCreateExclusive<T extends object>(target: T, isAvailable: () => boolean): T;
+//# sourceMappingURL=follow-create-exclusive.d.ts.map

package/dist/follow-create-exclusive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow-create-exclusive.d.ts","sourceRoot":"","sources":["../src/follow-create-exclusive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,OAAO,GAAG,CAAC,CAWhG"}

package/dist/guarded-files-api.d.ts

@@ -14,6 +14,7 @@ import type { FileGuard } from "./types.js";
  * | ------------- | --------------------------------------------------- |
  * | `read`        | `read`                                              |
  * | `write`       | `write`                                             |
+ * | `createExclusive` | `write`                                         |
  * | `mkdir`       | `mkdir`                                             |
  * | `remove`      | `remove`                                            |
  * | `list`        | `list` on the path AND on each directory entry      |
@@ -50,6 +51,13 @@ export declare class GuardedFilesApi implements FilesApi {
      *   An empty list disables every check (the wrapper becomes a passthrough).
      */
     constructor(source: FilesApi, guards: FileGuard[]);
+    /**
+     * Present only while the source has it, checked at each access (`in` and `typeof`
+     * included), so it follows a source whose methods change, such as a
+     * `CompositeFilesApi` after `mount()`. A `write`-guarded pass-through, so the
+     * exclusion is the source's own.
+     */
+    createExclusive?(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<boolean>;
     private checkGuard;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;

package/dist/guarded-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guarded-files-api.d.ts","sourceRoot":"","sources":["../src/guarded-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAGhD;IAED,OAAO,CAAC,UAAU;IAWlB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAQxE;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGlD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGrC;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;CACF"}
+{"version":3,"file":"guarded-files-api.d.ts","sourceRoot":"","sources":["../src/guarded-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;;;OAMG;IACH,YAAY,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAKhD;IAED;;;;;OAKG;IACG,eAAe,CAAC,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,OAAO,CAAC,CAMlB;IAED,OAAO,CAAC,UAAU;IAWlB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAGnE;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAGf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAQxE;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAGlD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGrC;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3D;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-composite",
-  "version": "0.10.5",
+  "version": "0.11.0",
   "private": false,
   "type": "module",
   "description": "Composite FilesApi with mount points and access guards",
@@ -34,7 +34,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.5"
+    "@statewalker/webrun-files": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
@@ -42,8 +42,8 @@
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.4 || ^5.0.3",
-    "@statewalker/webrun-files-tests": "^3.0.0",
-    "@statewalker/webrun-files-mem": "^0.10.5"
+    "@statewalker/webrun-files-mem": "^0.11.0",
+    "@statewalker/webrun-files-tests": "^3.0.0"
   },
   "sideEffects": false,
   "publishConfig": {

package/src/composite-files-api.ts

@@ -5,7 +5,14 @@ import type {
   ListOptions,
   ReadOptions,
 } from "@statewalker/webrun-files";
-import { comparePaths, joinPath, mergeInPathOrder, normalizePath } from "@statewalker/webrun-files";
+import {
+  comparePaths,
+  joinPath,
+  mergeInPathOrder,
+  normalizePath,
+  removeMovedSource,
+} from "@statewalker/webrun-files";
+import { followCreateExclusive } from "./follow-create-exclusive.js";
 
 interface MountEntry {
   prefix: string;
@@ -23,7 +30,7 @@ interface MountEntry {
  * Each backend can use a sub-directory of its own filesystem as the mount
  * root via `fsPath` (constructor `rootPath` for the implicit root mount,
  * `fsPath` argument for additional mounts). Cross-mount `move` is
- * implemented as copy-then-delete; there is no atomicity guarantee.
+ * implemented as copy-then-delete; there is no atomicity guarantee (see `move`).
  *
  * Access control and visibility filtering are intentionally **not** part of
  * this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
@@ -52,6 +59,38 @@ export class CompositeFilesApi implements FilesApi {
    */
   constructor(root: FilesApi, rootPath?: string) {
     this.mounts = [{ prefix: "/", api: root, basePath: normalizePath(rootPath ?? "/") }];
+    // biome-ignore lint/correctness/noConstructorReturn: the proxy shows `createExclusive` only while every backend has it
+    return followCreateExclusive(this, () =>
+      this.mounts.every((m) => typeof m.api.createExclusive === "function"),
+    );
+  }
+
+  /**
+   * Present only while EVERY backend — the root and each mount — has its own
+   * `createExclusive`, so feature detection on the composite tells the truth for
+   * any path: `"createExclusive" in composite` and `typeof composite.createExclusive`
+   * are checked against the mounts at each access. Mounting a backend without it hides
+   * the method; it is never shown and then refused for some paths. (A reference taken
+   * before such a mount still calls; it throws for paths on a backend without it.)
+   * It is a prototype method, so a subclass overrides it as usual.
+   *
+   * A call goes to the backend owning the path, so the exclusion reaches as far
+   * as that backend's does. A mount point, and a directory that exists only
+   * because a mount lies under it, count as existing.
+   */
+  async createExclusive?(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
+    const normalized = normalizePath(path);
+    if (this.mounts.some((m) => m.prefix !== "/" && isInsideOrSame(m.prefix, normalized))) {
+      return false;
+    }
+    const { api, resolvedPath } = this.resolve(normalized);
+    if (!api.createExclusive) {
+      throw new Error(`createExclusive is not supported by the backend for ${normalized}`);
+    }
+    return api.createExclusive(resolvedPath, content);
   }
 
   /**
@@ -266,6 +305,17 @@ export class CompositeFilesApi implements FilesApi {
     return api.remove(resolvedPath);
   }
 
+  /**
+   * Within one mount the move is delegated, so it is exactly as atomic as that
+   * backend's `move` (and treats an existing target as that backend does).
+   *
+   * Across mounts it can only be a copy, then a delete, and is NOT atomic: while it
+   * runs, the content exists in both places, and a directory appears in the target
+   * file by file. A failed copy throws and keeps the source. If the copy succeeds but
+   * the source cannot be removed, the removal is retried once, then a
+   * `MoveIncompleteError` is thrown: the target holds the new content and the source
+   * still exists. False is never returned for a half-done move.
+   */
   async move(source: string, target: string): Promise<boolean> {
     const src = this.resolve(source);
     const tgt = this.resolve(target);
@@ -277,10 +327,14 @@ export class CompositeFilesApi implements FilesApi {
 
     // Cross-mount: copy then remove
     const copied = await this.crossCopy(src.api, src.resolvedPath, tgt.api, tgt.resolvedPath);
-    if (copied) {
-      await src.api.remove(src.resolvedPath);
-    }
-    return copied;
+    if (!copied) return false;
+    // Reported with the composite's paths, not the backend's.
+    const backend = {
+      remove: () => src.api.remove(src.resolvedPath),
+      exists: () => src.api.exists(src.resolvedPath),
+    };
+    await removeMovedSource(backend, normalizePath(source), normalizePath(target));
+    return true;
   }
 
   async copy(source: string, target: string): Promise<boolean> {
@@ -374,6 +428,10 @@ function translateAfter(
   return SKIP;
 }
 
+function isInsideOrSame(path: string, ancestor: string): boolean {
+  return path === ancestor || isStrictlyInside(path, ancestor);
+}
+
 function isStrictlyInside(path: string, ancestor: string): boolean {
   return ancestor === "/" ? path !== "/" : path.startsWith(`${ancestor}/`);
 }

package/src/cow-files-api.ts

@@ -11,6 +11,7 @@ import {
   joinPath,
   listInPathOrder,
   normalizePath,
+  removeMovedSource,
 } from "@statewalker/webrun-files";
 
 /** Options for {@link cow}. */
@@ -190,11 +191,43 @@ class CowFilesApi implements FilesApi {
     return true;
   }
 
+  /**
+   * NOT atomic: the composite view of the source is copied into the writable layer,
+   * then the source is removed (deleted from the writable layer and/or hidden behind
+   * a whiteout). While it runs the content exists in both places, and a directory
+   * appears in the target file by file. A failed copy throws and keeps the source. If
+   * the copy succeeds but the source cannot be removed, the removal is retried once,
+   * then a `MoveIncompleteError` is thrown: the target holds the new content and the
+   * source still exists. False is never returned for a half-done move.
+   *
+   * An existing target (as the composite view shows it) is treated as POSIX
+   * `rename(2)` treats it, like `MemFilesApi` and `NodeFilesApi`: a file replaces a
+   * file, and a directory replaces an empty directory. Everything else returns false
+   * and changes nothing: a file onto a directory, a directory onto a file or onto a
+   * non-empty directory, a directory into its own subtree, a target below a file, and
+   * a missing source. A move onto itself is a successful no-op.
+   */
   async move(source: string, target: string): Promise<boolean> {
-    const stats = await this.stats(source);
+    const from = normalizePath(source);
+    const to = normalizePath(target);
+    const stats = await this.stats(from);
     if (!stats) return false;
-    await this.copyInto(source, target, stats);
-    await this.remove(source);
+    if (from === to) return true;
+    if (from === "/" || to.startsWith(`${from}/`)) return false;
+    for (let dir = dirname(to); dir !== "/"; dir = dirname(dir)) {
+      const kind = (await this.stats(dir))?.kind;
+      if (kind === "file") return false;
+      if (kind === "directory") break;
+    }
+    const targetStats = await this.stats(to);
+    if (targetStats) {
+      if (targetStats.kind !== stats.kind) return false;
+      if (targetStats.kind === "directory") {
+        for await (const _ of this.list(to)) return false;
+      }
+    }
+    await this.copyInto(from, to, stats);
+    await removeMovedSource(this, from, to);
     return true;
   }
 

package/src/filtered-files-api.ts

@@ -6,6 +6,7 @@ import type {
   ReadOptions,
 } from "@statewalker/webrun-files";
 import { normalizePath } from "@statewalker/webrun-files";
+import { followCreateExclusive } from "./follow-create-exclusive.js";
 import { globToRegExp } from "./glob-to-regexp.js";
 
 /**
@@ -139,7 +140,8 @@ export function newGlobPathFilter(...pathGlobs: string[]): PathFilter {
  * - `remove` returns `false` (no error, nothing changed).
  * - `move` / `copy` return `false` if either endpoint is hidden.
  * - `write` / `mkdir` reject with an `Error` (since silently dropping a
- *   write would lose data).
+ *   write would lose data), and so does `createExclusive`, which the
+ *   decorator has only when the source has it.
  * - `list` recursively skips entries whose paths are hidden, so iterating a
  *   visible parent never reveals a hidden child.
  *
@@ -190,6 +192,26 @@ export class FilteredFilesApi implements FilesApi {
   constructor(source: FilesApi, pathFilter: PathFilter) {
     this.source = source;
     this.pathFilter = pathFilter;
+    // biome-ignore lint/correctness/noConstructorReturn: the proxy shows `createExclusive` only while the source has it
+    return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+  }
+
+  /**
+   * Present only while the source has it, checked at each access (`in` and `typeof`
+   * included), so it follows a source whose methods change, such as a
+   * `CompositeFilesApi` after `mount()`. The exclusion is the source's own.
+   */
+  async createExclusive?(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
+    if (await this.isHidden(path)) {
+      throw new Error(`Path is hidden: ${path}`);
+    }
+    if (!this.source.createExclusive) {
+      throw new Error(`createExclusive is not supported by the source for ${path}`);
+    }
+    return this.source.createExclusive(path, content);
   }
 
   protected async isHidden(path: string): Promise<boolean> {

package/src/follow-create-exclusive.ts

@@ -0,0 +1,22 @@
+/**
+ * Wrap `target` so that its `createExclusive` exists only while `isAvailable()` says so,
+ * checked on every access: both `"createExclusive" in api` and
+ * `typeof api.createExclusive` then follow the backend(s) the object delegates to, even
+ * as those change (a `mount()` of a backend without the method, say), and a subclass
+ * that overrides the method is hidden or shown the same way.
+ *
+ * Constructors return the result, so the object every caller holds is the proxy; `this`
+ * inside methods is the proxy too, and every other property passes straight through.
+ */
+export function followCreateExclusive<T extends object>(target: T, isAvailable: () => boolean): T {
+  return new Proxy(target, {
+    has(object, key) {
+      if (key === "createExclusive" && !isAvailable()) return false;
+      return Reflect.has(object, key);
+    },
+    get(object, key, receiver) {
+      if (key === "createExclusive" && !isAvailable()) return undefined;
+      return Reflect.get(object, key, receiver);
+    },
+  });
+}

package/src/guarded-files-api.ts

@@ -6,6 +6,7 @@ import type {
   ReadOptions,
 } from "@statewalker/webrun-files";
 import { normalizePath } from "@statewalker/webrun-files";
+import { followCreateExclusive } from "./follow-create-exclusive.js";
 import type { FileGuard, FileOperation } from "./types.js";
 
 /**
@@ -22,6 +23,7 @@ import type { FileGuard, FileOperation } from "./types.js";
  * | ------------- | --------------------------------------------------- |
  * | `read`        | `read`                                              |
  * | `write`       | `write`                                             |
+ * | `createExclusive` | `write`                                         |
  * | `mkdir`       | `mkdir`                                             |
  * | `remove`      | `remove`                                            |
  * | `list`        | `list` on the path AND on each directory entry      |
@@ -61,6 +63,25 @@ export class GuardedFilesApi implements FilesApi {
   constructor(source: FilesApi, guards: FileGuard[]) {
     this.source = source;
     this.guards = [...guards];
+    // biome-ignore lint/correctness/noConstructorReturn: the proxy shows `createExclusive` only while the source has it
+    return followCreateExclusive(this, () => typeof source.createExclusive === "function");
+  }
+
+  /**
+   * Present only while the source has it, checked at each access (`in` and `typeof`
+   * included), so it follows a source whose methods change, such as a
+   * `CompositeFilesApi` after `mount()`. A `write`-guarded pass-through, so the
+   * exclusion is the source's own.
+   */
+  async createExclusive?(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<boolean> {
+    this.checkGuard(path, "write");
+    if (!this.source.createExclusive) {
+      throw new Error(`createExclusive is not supported by the source for ${path}`);
+    }
+    return this.source.createExclusive(path, content);
   }
 
   private checkGuard(path: string, ...operations: FileOperation[]): void {