@poe-platform/safe-fs 0.1.729 → 0.1.731

package/README.md

@@ -25,6 +25,14 @@ console.log(await fs.readFile("note.txt", "utf8"));
 
 Output: `hello`, then `hello world`. Nothing touches the host filesystem. Raw adapters exchange `Uint8Array` values; the Node bridge adds strings, encodings, `Buffer` results, and stat predicates. Its `cwd` is the relative-path base and, by default, the confinement boundary. Set an explicit `root` to use a different boundary, for example `{ cwd: "/work", root: "/" }` to address a complete provider namespace. The bridge supports `unlink` when the provider offers atomic file removal; unsupported methods fail without host fallback. `createHostFileSystem()` provides trusted, unrestricted native host access when a rooted adapter is not desired.
 
+Under the `workerd` export condition, `@poe-platform/safe-fs/fs/real` reads the
+native request-local filesystem, including retained `/tmp` file bytes.
+The restricted profile refuses generic descriptors, permission/timestamp
+changes, exact creation modes, and owned staging; it promises neither atomic
+rename nor inode/version identity from placeholder native metadata. Retained
+reads remain available, with native seek reporting `ENOTSUP`. Ordinary browser
+bundles cannot import this backend. Node keeps its POSIX host profile.
+
 For host storage, use `await createRealFileSystem({ root: "/absolute/existing/directory" })` instead. The root must already exist; virtual `/` maps to that directory. ZIP creation and updates can use this adapter's private owned staging in an isolated host tree. Unzip extraction requires atomic ancestry verification, currently supported by MemoryFileSystem; the real adapter and mount views refuse it. Its `trustedOwnedStaging` capability checks original entries before publication and cleanup, and preserves foreign staging children. It does not advertise atomic conditional mutations: keep external writers and other in-flight writes away from the tree during these operations. Read the safety boundary below before exposing it to untrusted code.
 
 To create new outputs with Safe Bash's `dos2unix`, `unix2dos`, or compression commands, host adapters need atomic no-replace publication. Supply `createRealFileSystem({ root, renameNoReplace })` only when that callback binds a qualified native primitive such as Linux `renameat2` with `RENAME_NOREPLACE`. It receives resolved absolute host paths and an optional signal in its third argument. Existing destinations must reject `EEXIST` atomically; existence checks followed by rename and copy/delete are insufficient. Without this binding the adapter explicitly refuses those operations. See the [no-replace contract](src/contracts/filesystem.md#atomic-no-replace-rename).
@@ -108,7 +116,7 @@ See the [staging contract](src/contracts/filesystem.md#atomic-owned-staging).
 | Backend or wrapper | Use it for |
 | --- | --- |
 | `createMemoryFileSystem()` | Isolated, nonpersistent storage with links, permissions, timestamps, and streams; each path resolution admits at most 65,536 cumulative UTF-16 code units across the input and followed symlink targets, rejecting excess with `ENAMETOOLONG` before component allocation |
-| `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node only |
+| `createRealFileSystem({ root })` | An existing host directory, with virtual paths rooted inside it; Node or qualified Workerd operations |
 | `new S3FileSystem({ transport, bucket, … })` | Bucket/prefix storage through an explicitly supplied transport; Node only |
 | `new WebDavFileSystem({ baseUrl, fetch, … })` | A WebDAV namespace through an explicitly supplied Fetch implementation |
 | `createReadOnlyFileSystem(filesystem)` | Rejecting writes through one view of an existing filesystem |

package/dist/safe-fs/contracts/filesystem.d.ts

@@ -78,6 +78,7 @@ export interface FileSystemCapabilities {
     readonly atomicFileStaging?: boolean;
     /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
     readonly retainedStagingCleanup?: boolean;
+    readonly retainedStagingWrite?: boolean;
     /** Atomically verifies every supplied root-to-parent directory identity at publication. */
     readonly atomicStagingAncestry?: boolean;
     /** Prepares directory guards that validate without yielding or mutating state. */
@@ -249,6 +250,13 @@ export interface FileStaging {
     readonly directory: FileStagingEntry;
     readonly file: FileStagingEntry;
     readonly cleanup?: FileStagingCleanup;
+    /** Available for retained regular-file staging on qualified backends. Writes
+     * append to the owned entry; finish seals it and returns its publication stat.
+     * Cleanup owns the lifetime and checks the last successfully written revision. */
+    readonly writer?: {
+        write(bytes: Uint8Array, options?: FsOptions): Promise<void>;
+        finish(options?: FsOptions): Promise<FileStat>;
+    };
 }
 export type StagedFileContent = {
     readonly type: "file";

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

@@ -12,7 +12,7 @@ export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
 export * from "./fs/object-publication/index.js";
-export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
+export { retargetScopedFileSystem, scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";

package/dist/safe-fs/core.js

@@ -11,7 +11,7 @@ export * from "./fs/mount/index.js";
 export * from "./fs/overlay/index.js";
 export * from "./fs/quota/index.js";
 export * from "./fs/object-publication/index.js";
-export { scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
+export { retargetScopedFileSystem, scopeFileSystem, retainFileSystemCleanup } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";
 export * from "./python/index.js";

package/dist/safe-fs/fs/capabilities.js

@@ -105,7 +105,7 @@ export function readOnlyCapabilities(capabilities) {
         "symlinks", "streamingRead", "open", "retainedRead", "versionedDescriptors",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
-        ...inspection, retainedStagingCleanup: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        ...inspection, retainedStagingCleanup: false, retainedStagingWrite: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
         synchronousStagingResolution: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
@@ -118,7 +118,7 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, retainedStagingWrite: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
@@ -143,6 +143,8 @@ export function ownedMutationCapabilities(filesystem, capabilities = filesystem.
         (unavailable ??= {}).atomicFileStaging = false;
     if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).retainedStagingCleanup = false;
+    if (capabilities.retainedStagingWrite === true && (capabilities.retainedStagingCleanup !== true || unavailable?.retainedStagingCleanup === false))
+        (unavailable ??= {}).retainedStagingWrite = false;
     if (capabilities.atomicStagingAncestry === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
         (unavailable ??= {}).atomicStagingAncestry = false;
     if (capabilities.synchronousDirectoryValidation === true && typeof filesystem.prepareDirectoryAncestry !== "function")

package/dist/safe-fs/fs/memory/index.d.ts

@@ -69,6 +69,7 @@ export declare class MemoryFileSystem implements FileSystem {
     private openWrite;
     private writeData;
     private writeAt;
+    private writeAtRange;
     writeMemoryFileFast(path: string, data: Uint8Array, append: boolean, mode: number): void;
     writeMemoryFileInDirFast(dirPrefix: string, name: string, data: Uint8Array, append: boolean, mode: number): void;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
@@ -118,13 +119,15 @@ export declare class MemoryFileSystem implements FileSystem {
 }
 export declare function createMemoryFileSystem(options?: MemoryFileSystemOptions | Readonly<Record<string, unknown>>): MemoryFileSystem;
 export declare class MemoryRedirectHandle {
-    readonly fs: MemoryFileSystem;
-    readonly path: string;
-    readonly node: FileNode;
-    readonly append: boolean;
+    fs: MemoryFileSystem;
+    path: string;
+    node: FileNode;
+    append: boolean;
     position: number;
     closed: boolean;
     constructor(fs: MemoryFileSystem, path: string, node: FileNode, append: boolean);
+    reset(fs: MemoryFileSystem, path: string, node: FileNode, append: boolean): void;
+    writeRangeSync(src: Uint8Array, len: number, signal?: AbortSignal): void;
     writeSync(chunk: Uint8Array, signal?: AbortSignal): void;
     close(): void;
 }