@poe-platform/safe-fs 0.1.815 → 0.1.817

package/README.md

@@ -15,6 +15,9 @@ To bound aggregate pages across multiple live stores, pass the same
 This shares a 256 KiB resident-page budget; `cache.residentBytes` reports current
 page retention. Eviction uses each store's filesystem, and each store still owns
 its `close()` cleanup. The budget excludes caller buffers and backend storage.
+Call `await storage.prepare()` before opening a directory iterator when its
+snapshot includes the scratch directory. It acquires and unlinks the backing
+handle up front, so later spills do not mutate that directory's namespace.
 `IntegerTable.entries()` replays records in unsigned key order with a fixed
 16-level node stack and batches of at most 128 records. It accepts zero-filled
 caller storage with `allocate`, `read` and `write`; mutation during traversal
@@ -317,6 +320,8 @@ Every raw filesystem operation accepts an optional `signal`. Additional fields a
 
 `access` takes a separate mode bitmask from `ACCESS_MODES`. `chmod` takes a mode, `utimes` takes millisecond timestamps, and `truncate` takes a byte length (default 0). For conditional chmod, check `capabilitiesFor(path, { conditionalChmod: true })` (or `capabilities`) and require `conditionalChmod: true`; supply `parent`, `expected`, and complete root-to-parent `ancestors` together. An optional mutation-free `commitGuard` must return literal `true` synchronously. Memory validates at its metadata commit; mount and supported Memory overlays preserve wrapper ancestry. Real uses its existing externally isolated host-tree boundary and does not prevent races with other processes. Backend limits still apply. Node-shaped bridge methods translate their own options rather than accepting these raw option objects; see the [bridge signatures](src/bridge/filesystem.ts).
 
+Cross-mount streamed copies start reading the source before opening the destination for writing. An initial read failure leaves the destination unchanged; later read or write failures can leave partial destination bytes.
+
 Overlay copy-up, copy, stream replacement/append and resize transfer retained ranges in 64 KiB chunks through the injected upper's stream writer. Resize streams the retained prefix and bounded zero chunks. Stream writes stage input before publication; cancellation or transfer failure leaves the destination unchanged and cleans staging. Stock Memory overlays transfer staged storage into existing upper inodes, preserving hardlinks without an additional whole-file buffer. `readFile` and `writeFile` remain buffering convenience APIs; use `readStream`/`writeStream` for large payloads. `maxBufferBytes` retains its existing optional total-byte admission semantics, not a working-memory guarantee.
 
 A streaming overlay needs an upper with `atomicRename`, `streamingWrite`, retained reads (`retainedRead` plus `openReadFile`), exclusive create, directory mutation, permissions and timestamps. Both layers must provide retained, bounded range reads with stable file and directory identities. For example, inject these host-authorized adapters with `createOverlayFileSystem({ upper: externalSpool, lower: retainedSource })`, then use `overlay.writeStream(path, source)`. The upper must await each consumed chunk, keep transport queues bounded, and preserve ownership until publication. Supply bounded chunks at the input boundary; the overlay cannot undo a payload-wide allocation already made by its caller. Whole-file-only uppers explicitly reject transfer operations with `ENOTSUP`; they do not silently collect streams.

package/dist/safe-fs/fs/mount/index.js

@@ -1308,7 +1308,16 @@ export class MountFileSystem {
                 const source = readBytes(reader.readStream(origin.local, options), options.signal);
                 let failed = false;
                 try {
-                    await writer.writeStream(target.local, source, writeOptions);
+                    // Admit lazy reader startup before the writer can truncate its target.
+                    // Later transfer failures retain the backend's partial-write semantics.
+                    const first = await source.next();
+                    await writer.writeStream(target.local, (async function* () {
+                        let item = first;
+                        while (!item.done) {
+                            yield item.value;
+                            item = await source.next();
+                        }
+                    })(), writeOptions);
                 }
                 catch (error) {
                     failed = true;

package/dist/safe-fs/storage.d.ts

@@ -44,6 +44,8 @@ export declare class PagedStorage {
     private closing;
     constructor(context: PagedStorageContext, maxPages?: number, cache?: PagedStorageCache | undefined);
     allocate(length: number): number;
+    /** Acquire and unlink backing storage before observing a directory snapshot. */
+    prepare(): Promise<void>;
     private operation;
     private spill;
     private flush;

package/dist/safe-fs/storage.js

@@ -73,6 +73,11 @@ export class PagedStorage {
         this.end += length;
         return offset;
     }
+    /** Acquire and unlink backing storage before observing a directory snapshot. */
+    async prepare() {
+        await this.operation(async () => { if (!this.descriptor)
+            await this.spill(); });
+    }
     operation(action) {
         this.signal.throwIfAborted();
         const execute = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.815",
+  "version": "0.1.817",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",