@poe-platform/safe-fs 0.1.716 → 0.1.718

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

@@ -8,6 +8,7 @@ declare const descriptions: {
     readonly ECANCELED: "operation canceled";
     readonly EEXIST: "file already exists";
     readonly EFBIG: "file too large";
+    readonly EILSEQ: "invalid or incomplete multibyte or wide character";
     readonly EINTR: "interrupted system call";
     readonly EINVAL: "invalid argument";
     readonly EIO: "input/output error";

package/dist/safe-fs/contracts/errors.js

@@ -7,6 +7,7 @@ const descriptions = {
     ECANCELED: "operation canceled",
     EEXIST: "file already exists",
     EFBIG: "file too large",
+    EILSEQ: "invalid or incomplete multibyte or wide character",
     EINTR: "interrupted system call",
     EINVAL: "invalid argument",
     EIO: "input/output error",

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

@@ -1,3 +1,4 @@
+import type { ExactFileReadHandle, ExactFileResizeHandle, ObjectFileSystem } from "./object.js";
 import type { ByteSource } from "./io.js";
 import type { FileDescriptor, OpenFileOptions } from "./descriptor.js";
 export type { FileDescriptor, FileDescriptorCapabilities, OpenFileOptions } from "./descriptor.js";
@@ -90,6 +91,8 @@ export interface CapabilityQueryOptions extends OpenReadFileOptions {
     readonly create?: boolean;
 }
 export interface FileReadHandle {
+    /** Exact operations on the same retained object; close owns both facets. */
+    readonly exact?: ExactFileReadHandle;
     stat(options?: FsOptions): Promise<FileStat>;
     read(position: number, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
     seekEnd?: ((options?: FsOptions) => Promise<bigint>) | undefined;
@@ -116,6 +119,8 @@ export interface FileResizeOptions extends FsOptions {
     readonly mode?: number;
 }
 export interface FileResizeHandle {
+    /** Exact operations on the same retained object; close owns both facets. */
+    readonly exact?: ExactFileResizeHandle;
     stat(options?: FsOptions): Promise<FileStat>;
     truncate(length: number, options?: FsOptions): Promise<void>;
     seekEnd?: ((options?: FsOptions) => Promise<bigint>) | undefined;
@@ -212,6 +217,8 @@ export interface ConditionalFilePublicationOptions extends FsOptions {
     readonly mtimeMs?: number;
 }
 export interface FileSystem {
+    /** Explicit retained-object capability for qualified byte-path backends. */
+    readonly objects?: ObjectFileSystem;
     /** Consume the complete source privately, then atomically compare/publish.
      * Failures before commit preserve the destination. No stat/write fallback. */
     publishFileConditional?(path: string, source: ByteSource, options: ConditionalFilePublicationOptions): Promise<FileStat>;

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

@@ -2,3 +2,4 @@ export * from "./errors.js";
 export * from "./filesystem.js";
 export * from "./io.js";
 export * from "./path.js";
+export * from "./object.js";

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

@@ -2,3 +2,4 @@ export * from "./errors.js";
 export * from "./filesystem.js";
 export * from "./io.js";
 export * from "./path.js";
+export * from "./object.js";

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

@@ -0,0 +1,134 @@
+import type { FileType, FsOptions, ReadDirectoryOptions } from "./filesystem.js";
+/** Owned Unix path bytes. No decoding, normalization, or namespace authorization. */
+export declare class BytePath {
+    #private;
+    constructor(value: Uint8Array);
+    bytes(): Uint8Array;
+}
+/** JSON representation: octets, never a UTF-8 replacement string. */
+export declare function encodeBytePath(path: BytePath): number[];
+export declare function decodeBytePath(value: unknown): BytePath;
+/** Admit legacy numbers before conversion; native off_t profile is signed 64-bit. */
+export declare function fileOffset(value: number | bigint): bigint;
+export declare function encodeFileOffset(value: bigint): string;
+export declare function decodeFileOffset(value: unknown): bigint;
+export type SpecialFileType = "character" | "fifo" | "socket";
+export type ObjectFileType = FileType | SpecialFileType;
+export interface ExactFileStat {
+    readonly type: ObjectFileType;
+    readonly size: bigint;
+    readonly allocatedBytes?: bigint;
+    /** Observed link count, including zero for an unlinked retained object; not identity. */
+    readonly nlink?: bigint;
+    readonly mode?: number;
+    readonly uid?: number;
+    readonly gid?: number;
+    readonly atimeNs?: bigint;
+    readonly mtimeNs?: bigint;
+    readonly ctimeNs?: bigint;
+}
+/** Metadata updates affect the retained object. No implicit recursive/path fallback. */
+export interface ObjectMetadata {
+    readonly mode?: number;
+    readonly uid?: number;
+    readonly gid?: number;
+    readonly atimeNs?: bigint;
+    readonly mtimeNs?: bigint;
+}
+export interface ExactFileReadHandle {
+    stat(options?: FsOptions): Promise<ExactFileStat>;
+    read(position: bigint, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
+}
+export interface ExactFileResizeHandle {
+    stat(options?: FsOptions): Promise<ExactFileStat>;
+    truncate(length: bigint, options?: FsOptions): Promise<void>;
+}
+/** Cursor operation on the same retained open description. Aliases share its
+ * cursor; close ownership remains with the enclosing handle. No numeric fallback. */
+export interface ExactFileSeekHandle {
+    seek(position: bigint, options?: FsOptions): Promise<void>;
+}
+export interface OpenFileObjectOptions extends FsOptions {
+    /** Default read; retained handle access is independent of hardlink identity. */
+    readonly access?: "read" | "write" | "readwrite";
+    /** Separately authorized native endpoint; omission never admits a special file. */
+    readonly special?: SpecialFileType;
+}
+/** Native creation admission on the same object that is returned. Exclusive
+ * flags refuse every existing entry, including a symlink, without mutation.
+ * w truncates during acquisition; a preserves existing bytes. Failure after a
+ * completed truncation does not roll it back. Backend root/mount/readonly/quota
+ * policy applies before acquisition; no caller-side existence or stat probe. */
+export interface CreateFileObjectOptions extends FsOptions {
+    readonly flag: "w" | "wx" | "a" | "ax";
+    readonly access?: "read" | "write" | "readwrite";
+    readonly mode?: number;
+}
+export interface RetainedFileObject {
+    /** Qualified retained identity: aliases share this token while any retain exists.
+     * Tokens cannot collide across unrelated backend/mount authorities and are never
+     * derived from paths or unqualified stat tuples. They are NOT wire identifiers. */
+    readonly identity: object | symbol;
+    readonly type: ObjectFileType;
+    stat(options?: FsOptions): Promise<ExactFileStat>;
+    read?(position: bigint, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
+    write?(position: bigint, bytes: Uint8Array, options?: FsOptions): Promise<number>;
+    /** Choose EOF and append on this retained object as one backend operation.
+     * Return actual settled byte progress; never implement with caller-side stat/write. */
+    append?(bytes: Uint8Array, options?: FsOptions): Promise<number>;
+    truncate?(length: bigint, options?: FsOptions): Promise<void>;
+    /** Each field requires backend support; unsupported fields reject ENOTSUP. */
+    metadata?(changes: ObjectMetadata, options?: FsOptions): Promise<void>;
+    /** Link the retained object, not its former pathname. Preserve EXDEV/EPERM. */
+    link?(destination: BytePath, options?: FsOptions): Promise<void>;
+    close(): Promise<void>;
+}
+export interface CreatedFileObject extends RetainedFileObject {
+    /** Receipt from acquisition, never inferred from a later pathname probe. */
+    readonly creation: "created" | "opened" | "truncated";
+}
+/** Optional stronger byte namespace. Absence is unsupported, not string fallback.
+ * Implementations retain objects atomically, enforce mount/root permissions and
+ * validate requested endpoint kinds before any potentially blocking acquisition. */
+export interface ObjectFileSystem {
+    readonly specialFiles?: Readonly<Partial<Record<SpecialFileType, boolean>>>;
+    open(path: BytePath, options?: OpenFileObjectOptions): Promise<RetainedFileObject>;
+    /** Optional qualified create/open/truncate primitive. Mode is used for newly
+     * created files only. Defaults for access/mode belong to the backend. a/ax
+     * do not synthesize retained append support or an append cursor. */
+    create?(path: BytePath, options: CreateFileObjectOptions): Promise<CreatedFileObject>;
+    /** A receipt describes this operation's actual namespace effect, not a later
+     * pathname probe. Omission means unknown; identical-object renames may be no-ops. */
+    rename?(source: BytePath, destination: BytePath, options?: FsOptions): Promise<void | {
+        readonly moved: boolean;
+    }>;
+    unlink?(path: BytePath, options?: FsOptions): Promise<void>;
+    readdir?(path: BytePath, options?: ReadDirectoryOptions): Promise<readonly {
+        readonly name: BytePath;
+        readonly type: ObjectFileType;
+    }[]>;
+}
+export interface WireObjectDirectoryEntry {
+    readonly name: readonly number[];
+    readonly type: ObjectFileType;
+}
+export interface WireObjectHandle {
+    readonly handle: string;
+    readonly object: string;
+}
+export type WireExactFileStat = Omit<ExactFileStat, "size" | "allocatedBytes" | "nlink" | "atimeNs" | "mtimeNs" | "ctimeNs"> & {
+    readonly size: string;
+    readonly allocatedBytes?: string;
+    readonly nlink?: string;
+    readonly atimeNs?: string;
+    readonly mtimeNs?: string;
+    readonly ctimeNs?: string;
+};
+export type WireObjectMetadata = Omit<ObjectMetadata, "atimeNs" | "mtimeNs"> & {
+    readonly atimeNs?: string;
+    readonly mtimeNs?: string;
+};
+export declare function encodeObjectMetadata(value: ObjectMetadata): WireObjectMetadata;
+export declare function decodeObjectMetadata(value: unknown): ObjectMetadata;
+/** Signed nanoseconds since Unix epoch; admit exact values before serialization. */
+export declare function encodeFileTimestamp(value: bigint): string;

package/dist/safe-fs/contracts/object.js

@@ -0,0 +1,97 @@
+import { FsError } from "./errors.js";
+/** Owned Unix path bytes. No decoding, normalization, or namespace authorization. */
+export class BytePath {
+    #value;
+    constructor(value) {
+        if (!(value instanceof Uint8Array)) {
+            throw new FsError("EINVAL", { syscall: "bytePath" });
+        }
+        this.#value = new Uint8Array(value);
+        if (this.#value.length === 0 || this.#value.includes(0)) {
+            throw new FsError("EINVAL", { syscall: "bytePath" });
+        }
+    }
+    bytes() { return this.#value.slice(); }
+}
+/** JSON representation: octets, never a UTF-8 replacement string. */
+export function encodeBytePath(path) {
+    return Array.from(BytePath.prototype.bytes.call(path));
+}
+export function decodeBytePath(value) {
+    if (!Array.isArray(value))
+        throw new FsError("EINVAL", { syscall: "bytePath" });
+    const octets = Array.from({ length: value.length }, (_, index) => {
+        if (!Object.hasOwn(value, index))
+            throw new FsError("EINVAL", { syscall: "bytePath" });
+        return value[index];
+    });
+    if (octets.some(byte => !Number.isInteger(byte) || byte < 0 || byte > 255)) {
+        throw new FsError("EINVAL", { syscall: "bytePath" });
+    }
+    return new BytePath(Uint8Array.from(octets));
+}
+/** Admit legacy numbers before conversion; native off_t profile is signed 64-bit. */
+export function fileOffset(value) {
+    if (typeof value !== "bigint" && (typeof value !== "number" || !Number.isSafeInteger(value))) {
+        throw new FsError("EINVAL", { syscall: "offset" });
+    }
+    const exact = BigInt(value);
+    if (exact < 0n || exact > 9223372036854775807n)
+        throw new FsError("EINVAL", { syscall: "offset" });
+    return exact;
+}
+export function encodeFileOffset(value) {
+    if (typeof value !== "bigint")
+        throw new FsError("EINVAL", { syscall: "offset" });
+    return fileOffset(value).toString();
+}
+export function decodeFileOffset(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 19 ||
+        (value.length > 1 && value[0] === "0") || [...value].some(char => char < "0" || char > "9")) {
+        throw new FsError("EINVAL", { syscall: "offset" });
+    }
+    return fileOffset(BigInt(value));
+}
+export function encodeObjectMetadata(value) {
+    const { atimeNs, mtimeNs, ...rest } = value;
+    const wire = {
+        ...rest,
+        ...(atimeNs === undefined ? {} : { atimeNs: encodeFileTimestamp(atimeNs) }),
+        ...(mtimeNs === undefined ? {} : { mtimeNs: encodeFileTimestamp(mtimeNs) }),
+    };
+    decodeObjectMetadata(wire);
+    return wire;
+}
+export function decodeObjectMetadata(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new FsError("EINVAL");
+    const result = {};
+    for (const [key, field] of Object.entries(value)) {
+        if (key === "atimeNs" || key === "mtimeNs") {
+            if (typeof field !== "string" || field.length === 0 || field.length > 20)
+                throw new FsError("EINVAL");
+            const digits = field.startsWith("-") ? field.slice(1) : field;
+            if (digits.length === 0 || [...digits].some(char => char < "0" || char > "9"))
+                throw new FsError("EINVAL");
+            const exact = BigInt(field);
+            if (exact.toString() !== field || exact < -9223372036854775808n || exact > 9223372036854775807n)
+                throw new FsError("EINVAL");
+            result[key] = exact;
+        }
+        else if (key === "mode" || key === "uid" || key === "gid") {
+            if (typeof field !== "number" || !Number.isSafeInteger(field) || field < 0 || field > (key === "mode" ? 0o7777 : 4294967294))
+                throw new FsError("EINVAL");
+            result[key] = field;
+        }
+        else {
+            throw new FsError("ENOTSUP");
+        }
+    }
+    return result;
+}
+/** Signed nanoseconds since Unix epoch; admit exact values before serialization. */
+export function encodeFileTimestamp(value) {
+    if (typeof value !== "bigint" || value < -9223372036854775808n || value > 9223372036854775807n)
+        throw new FsError("EINVAL");
+    return value.toString();
+}

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

@@ -20,3 +20,5 @@ export * from "./python/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
 export type { XmlName, XmlAttribute, XmlContent, XmlElement, XmlLimits } from "./xml.js";
+export * from "./contracts/object.js";
+export { ObjectAuthority } from "./fs/object-authority.js";

package/dist/safe-fs/core.js

@@ -17,3 +17,5 @@ export * from "./bridge/index.js";
 export * from "./python/index.js";
 export { compareEntries } from "./fs/mount/comparison.js";
 export { parseXml, parseXmlSteps, XmlLimitError } from "./xml.js";
+export * from "./contracts/object.js";
+export { ObjectAuthority } from "./fs/object-authority.js";

package/dist/safe-fs/fs/object-authority.d.ts

@@ -0,0 +1,27 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+import { BytePath } from "../contracts/object.js";
+import type { WireObjectMetadata, OpenFileObjectOptions, WireExactFileStat, WireObjectHandle, WireObjectDirectoryEntry } from "../contracts/object.js";
+/** One authenticated job/epoch owns one authority. IDs are routing identifiers,
+ * not bearer authorization. All admitted operations drain before disposal. */
+export declare class ObjectAuthority {
+    #private;
+    constructor(filesystem: FileSystem | Pick<FileSystem, "objects">, options: {
+        readonly maxHandles: number;
+        readonly maxIoBytes?: number;
+    });
+    open(path: BytePath, options?: OpenFileObjectOptions): Promise<WireObjectHandle>;
+    read(handle: string, position: string, maxBytes: number): Promise<Uint8Array>;
+    write(handle: string, position: string, bytes: Uint8Array): Promise<number>;
+    append(handle: string, bytes: Uint8Array): Promise<number>;
+    truncate(handle: string, length: string): Promise<void>;
+    metadata(handle: string, changes: WireObjectMetadata): Promise<void>;
+    link(handle: string, destination: BytePath): Promise<void>;
+    stat(handle: string): Promise<WireExactFileStat>;
+    rename(source: BytePath, destination: BytePath): Promise<void | {
+        readonly moved: boolean;
+    }>;
+    unlink(path: BytePath): Promise<void>;
+    readdir(path: BytePath, maxEntries: number): Promise<readonly WireObjectDirectoryEntry[]>;
+    close(handle: string): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/safe-fs/fs/object-authority.js

@@ -0,0 +1,286 @@
+import { platform } from "#safe-fs-platform";
+import { FsError } from "../contracts/errors.js";
+import { BytePath, decodeFileOffset, encodeFileOffset, decodeObjectMetadata, encodeFileTimestamp } from "../contracts/object.js";
+/** One authenticated job/epoch owns one authority. IDs are routing identifiers,
+ * not bearer authorization. All admitted operations drain before disposal. */
+export class ObjectAuthority {
+    #backend;
+    #maxHandles;
+    #maxIoBytes;
+    #prefix = platform.randomUUID();
+    #handles = new Map();
+    #identities = new Map();
+    #sequence = 0;
+    #tail = Promise.resolve();
+    #disposal;
+    constructor(filesystem, options) {
+        const backend = filesystem.objects;
+        // One issued authority keeps its qualified namespace. Bound operations
+        // observe live backend state without accepting replacement capabilities.
+        if (backend !== undefined) {
+            const { open, rename, unlink, readdir, specialFiles } = backend;
+            this.#backend = Object.freeze({
+                open: open.bind(backend),
+                ...(rename === undefined ? {} : { rename: rename.bind(backend) }),
+                ...(unlink === undefined ? {} : { unlink: unlink.bind(backend) }),
+                ...(readdir === undefined ? {} : { readdir: readdir.bind(backend) }),
+                specialFiles: Object.freeze({ ...specialFiles }),
+            });
+        }
+        this.#maxHandles = options.maxHandles;
+        this.#maxIoBytes = options.maxIoBytes ?? 1048576;
+        if (!Number.isSafeInteger(this.#maxHandles) || this.#maxHandles < 1 ||
+            !Number.isSafeInteger(this.#maxIoBytes) || this.#maxIoBytes < 1)
+            throw new FsError("EINVAL");
+    }
+    #run(operation) {
+        if (this.#disposal)
+            return Promise.reject(new FsError("EBADF"));
+        const result = this.#tail.then(operation);
+        this.#tail = result.catch(() => { });
+        return result;
+    }
+    #lookup(handle, access) {
+        const retained = this.#handles.get(handle);
+        if (!retained || (access && retained.access !== access && retained.access !== "readwrite"))
+            throw new FsError("EBADF");
+        return retained.object;
+    }
+    async open(path, options = {}) {
+        const ownedPath = new BytePath(BytePath.prototype.bytes.call(path));
+        const admission = Object.freeze({ ...options });
+        return this.#run(async () => {
+            if ((admission.access !== undefined && !["read", "write", "readwrite"].includes(admission.access)) ||
+                (admission.special !== undefined && !["character", "fifo", "socket"].includes(admission.special)))
+                throw new FsError("EINVAL");
+            const backend = this.#backend;
+            if (!backend || (admission.special && backend.specialFiles?.[admission.special] !== true))
+                throw new FsError("ENOTSUP");
+            if (this.#handles.size >= this.#maxHandles)
+                throw new FsError("EMFILE");
+            const acquired = await backend.open(ownedPath, admission);
+            // Own cleanup before inspecting admission properties. Keep the acquired
+            // receiver and operations even if its public method table later changes.
+            const close = acquired.close.bind(acquired);
+            try {
+                const token = acquired.identity;
+                const type = acquired.type;
+                if ((typeof token !== "object" && typeof token !== "symbol") || token === null)
+                    throw new FsError("ENOTSUP");
+                if (admission.special ? type !== admission.special : !["file", "directory", "symlink"].includes(type))
+                    throw new FsError("ENOTSUP");
+                const { read, write, append, truncate, metadata, link } = acquired;
+                const object = Object.freeze({
+                    identity: token, type, close,
+                    stat: acquired.stat.bind(acquired),
+                    ...(read === undefined ? {} : { read: read.bind(acquired) }),
+                    ...(write === undefined ? {} : { write: write.bind(acquired) }),
+                    ...(append === undefined ? {} : { append: append.bind(acquired) }),
+                    ...(truncate === undefined ? {} : { truncate: truncate.bind(acquired) }),
+                    ...(metadata === undefined ? {} : { metadata: metadata.bind(acquired) }),
+                    ...(link === undefined ? {} : { link: link.bind(acquired) }),
+                });
+                let identity = this.#identities.get(token);
+                if (!identity) {
+                    identity = { id: `${this.#prefix}:o${++this.#sequence}`, references: 0 };
+                    this.#identities.set(token, identity);
+                }
+                identity.references++;
+                const handle = `${this.#prefix}:h${++this.#sequence}`;
+                this.#handles.set(handle, { object, identity: token, type, access: admission.access ?? "read" });
+                return { handle, object: identity.id };
+            }
+            catch (error) {
+                try {
+                    await close();
+                }
+                catch (closeError) {
+                    throw new AggregateError([error, closeError]);
+                }
+                throw error;
+            }
+        });
+    }
+    read(handle, position, maxBytes) {
+        return this.#run(async () => {
+            const object = this.#lookup(handle, "read");
+            const offset = decodeFileOffset(position);
+            if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > this.#maxIoBytes)
+                throw new FsError("EINVAL");
+            if (!object.read)
+                throw new FsError("ENOTSUP");
+            const bytes = await object.read(offset, maxBytes);
+            if (!(bytes instanceof Uint8Array))
+                throw new FsError("EIO");
+            const length = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get.call(bytes);
+            if (length > maxBytes)
+                throw new FsError("EIO");
+            return new Uint8Array(bytes);
+        });
+    }
+    #ownedWriteBytes(bytes) {
+        if (!(bytes instanceof Uint8Array))
+            throw new FsError("EINVAL");
+        // Caller properties cannot redefine the span admitted before allocation.
+        const length = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get.call(bytes);
+        if (length > this.#maxIoBytes)
+            throw new FsError("EINVAL");
+        return new Uint8Array(bytes);
+    }
+    async write(handle, position, bytes) {
+        const owned = this.#ownedWriteBytes(bytes);
+        return this.#run(async () => {
+            const object = this.#lookup(handle, "write");
+            const offset = decodeFileOffset(position);
+            if (!object.write)
+                throw new FsError("ENOTSUP");
+            const count = await object.write(offset, owned);
+            if (!Number.isSafeInteger(count) || count < 0 || count > owned.byteLength)
+                throw new FsError("EIO");
+            return count;
+        });
+    }
+    async append(handle, bytes) {
+        const owned = this.#ownedWriteBytes(bytes);
+        return this.#run(async () => {
+            const object = this.#lookup(handle, "write");
+            if (!object.append)
+                throw new FsError("ENOTSUP", { syscall: "append" });
+            const count = await object.append(owned);
+            if (!Number.isSafeInteger(count) || count < 0 || count > owned.byteLength)
+                throw new FsError("EIO");
+            return count;
+        });
+    }
+    truncate(handle, length) {
+        return this.#run(async () => {
+            const object = this.#lookup(handle, "write");
+            const size = decodeFileOffset(length);
+            if (!object.truncate)
+                throw new FsError("ENOTSUP");
+            await object.truncate(size);
+        });
+    }
+    metadata(handle, changes) {
+        if (typeof changes !== "object" || changes === null || Array.isArray(changes))
+            return Promise.reject(new FsError("EINVAL"));
+        const owned = { ...changes };
+        return this.#run(async () => {
+            const object = this.#lookup(handle);
+            if (!object.metadata)
+                throw new FsError("ENOTSUP");
+            await object.metadata(decodeObjectMetadata(owned));
+        });
+    }
+    async link(handle, destination) {
+        const ownedDestination = new BytePath(BytePath.prototype.bytes.call(destination));
+        return this.#run(async () => {
+            const object = this.#lookup(handle);
+            if (!object.link)
+                throw new FsError("ENOTSUP");
+            await object.link(ownedDestination);
+        });
+    }
+    stat(handle) {
+        return this.#run(async () => {
+            const object = this.#lookup(handle);
+            const value = await object.stat();
+            const { type, size, allocatedBytes, nlink, atimeNs, mtimeNs, ctimeNs, mode, uid, gid } = value;
+            if (type !== this.#handles.get(handle).type)
+                throw new FsError("EIO");
+            for (const [field, maximum] of [[mode, 65535], [uid, 4294967295], [gid, 4294967295]]) {
+                if (field !== undefined && (!Number.isSafeInteger(field) || field < 0 || field > maximum))
+                    throw new FsError("EINVAL");
+            }
+            return {
+                type, size: encodeFileOffset(size),
+                ...(mode === undefined ? {} : { mode }),
+                ...(uid === undefined ? {} : { uid }),
+                ...(gid === undefined ? {} : { gid }),
+                ...(allocatedBytes === undefined ? {} : { allocatedBytes: encodeFileOffset(allocatedBytes) }),
+                ...(nlink === undefined ? {} : { nlink: encodeFileOffset(nlink) }),
+                ...(atimeNs === undefined ? {} : { atimeNs: encodeFileTimestamp(atimeNs) }),
+                ...(mtimeNs === undefined ? {} : { mtimeNs: encodeFileTimestamp(mtimeNs) }),
+                ...(ctimeNs === undefined ? {} : { ctimeNs: encodeFileTimestamp(ctimeNs) }),
+            };
+        });
+    }
+    async rename(source, destination) {
+        const ownedSource = new BytePath(BytePath.prototype.bytes.call(source));
+        const ownedDestination = new BytePath(BytePath.prototype.bytes.call(destination));
+        return this.#run(async () => {
+            const backend = this.#backend;
+            if (!backend?.rename)
+                throw new FsError("ENOTSUP");
+            return await backend.rename(ownedSource, ownedDestination);
+        });
+    }
+    async unlink(path) {
+        const ownedPath = new BytePath(BytePath.prototype.bytes.call(path));
+        return this.#run(async () => {
+            const backend = this.#backend;
+            if (!backend?.unlink)
+                throw new FsError("ENOTSUP");
+            await backend.unlink(ownedPath);
+        });
+    }
+    async readdir(path, maxEntries) {
+        const ownedPath = new BytePath(BytePath.prototype.bytes.call(path));
+        return this.#run(async () => {
+            if (!Number.isSafeInteger(maxEntries) || maxEntries < 0)
+                throw new FsError("EINVAL");
+            const backend = this.#backend;
+            if (!backend?.readdir)
+                throw new FsError("ENOTSUP");
+            const entries = await backend.readdir(ownedPath, { maxEntries });
+            if (!Array.isArray(entries))
+                throw new FsError("EIO");
+            const length = entries.length;
+            if (length > maxEntries)
+                throw new FsError("EFBIG");
+            return Array.from({ length }, (_, index) => {
+                if (!Object.hasOwn(entries, index))
+                    throw new FsError("EIO");
+                const entry = entries[index];
+                if (!entry)
+                    throw new FsError("EIO");
+                const { name: component, type } = entry;
+                if (typeof component?.bytes !== "function" ||
+                    !["file", "directory", "symlink", "character", "fifo", "socket"].includes(type))
+                    throw new FsError("EIO");
+                const carrier = component.bytes();
+                if (!(carrier instanceof Uint8Array))
+                    throw new FsError("EIO");
+                const bytes = new Uint8Array(carrier);
+                if (!bytes.length || bytes.includes(0) || bytes.includes(47) ||
+                    (bytes[0] === 46 && (bytes.length === 1 || (bytes.length === 2 && bytes[1] === 46))))
+                    throw new FsError("EIO");
+                const name = Array.from(bytes);
+                return { name, type };
+            });
+        });
+    }
+    close(handle) {
+        return this.#run(async () => {
+            const object = this.#lookup(handle);
+            const token = this.#handles.get(handle).identity;
+            this.#handles.delete(handle);
+            const identity = this.#identities.get(token);
+            if (--identity.references === 0)
+                this.#identities.delete(token);
+            await object.close();
+        });
+    }
+    dispose() {
+        this.#disposal ??= this.#tail.then(async () => {
+            const objects = [...this.#handles.values()].map(retained => retained.object);
+            this.#handles.clear();
+            this.#identities.clear();
+            const results = await Promise.allSettled(objects.map(async (object) => { await object.close(); }));
+            const failures = results.filter(result => result.status === "rejected");
+            if (failures.length)
+                throw new AggregateError(failures.map(result => result.reason), "Object cleanup failed");
+        });
+        return this.#disposal;
+    }
+}

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

@@ -1,5 +1,7 @@
 import type { FileSystem, FsOptions } from "../contracts/filesystem.js";
-export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void): FileSystem;
+export declare function scopeFileSystem(filesystem: FileSystem, charge: () => void, signal: AbortSignal, cleanupCharge?: () => void, options?: {
+    readonly preserveDescriptorWriteReceipt?: boolean;
+}): FileSystem;
 export interface RetainedFileSystemCleanupView {
     readonly removeFileConditional?: NonNullable<FileSystem["removeFileConditional"]>;
     readonly removeStagedFile?: NonNullable<FileSystem["removeStagedFile"]>;

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

@@ -10,7 +10,7 @@ const operations = new Set([
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
-export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge) {
+export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = charge, options = {}) {
     const original = originals.get(filesystem)?.filesystem ?? filesystem;
     const methods = new Map();
     const assertOpen = (options) => {
@@ -115,7 +115,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
     };
     const wrapDescriptor = (descriptor) => {
         let closing;
-        const invoke = async (options, action) => {
+        const invoke = async (options, action, preserveReceipt = false) => {
             assertOpen(options);
             if (closing)
                 throw new FsError("EBADF");
@@ -125,7 +125,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                 throw new FsError("EBADF");
             try {
                 const result = await action(resizeOptions(options));
-                assertOpen(options);
+                if (!preserveReceipt)
+                    assertOpen(options);
                 return result;
             }
             catch (error) {
@@ -141,7 +142,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             ...(probeRead === undefined ? {} : { probeRead: (options = {}) => invoke(options, scoped => probeRead.call(descriptor, scoped)) }),
             stat: (options = {}) => invoke(options, scoped => descriptor.stat(scoped)),
             read: (buffer, position, options = {}) => invoke(options, scoped => descriptor.read(buffer, position, scoped)),
-            write: (buffer, position, options = {}) => invoke(options, scoped => descriptor.write(buffer, position, scoped)),
+            write: (buffer, position, forwarded = {}) => invoke(forwarded, scoped => descriptor.write(buffer, position, scoped), options.preserveDescriptorWriteReceipt === true),
             truncate: (length, options = {}) => invoke(options, scoped => descriptor.truncate(length, scoped)),
             sync: (dataOnly, options = {}) => invoke(options, scoped => descriptor.sync(dataOnly, scoped)),
             close: () => closing ??= Promise.resolve().then(() => descriptor.close()),

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

@@ -1,4 +1,5 @@
 export * from "./contracts/index.js";
+export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./python/index.js";
 export { openFileDescriptor } from "./fs/descriptor.js";
 export type { DescriptorBackend, DescriptorOpenOptions } from "./fs/descriptor.js";

package/dist/safe-fs/index.js

@@ -1,4 +1,5 @@
 export * from "./contracts/index.js";
+export { ObjectAuthority } from "./fs/object-authority.js";
 export * from "./python/index.js";
 export { openFileDescriptor } from "./fs/descriptor.js";
 export * from "./fs/memory/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.716",
+  "version": "0.1.718",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -110,6 +110,14 @@
     "./fs/quota": {
       "types": "./dist/safe-fs/fs/quota/index.d.ts",
       "import": "./dist/safe-fs/fs/quota/index.js"
+    },
+    "./contracts/object": {
+      "types": "./dist/safe-fs/contracts/object.d.ts",
+      "import": "./dist/safe-fs/contracts/object.js"
+    },
+    "./contracts/errors": {
+      "types": "./dist/safe-fs/contracts/errors.d.ts",
+      "import": "./dist/safe-fs/contracts/errors.js"
     }
   },
   "repository": {