@poe-platform/safe-fs 0.1.660 → 0.1.661

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

@@ -8,6 +8,7 @@ export interface OpenFileOptions extends FsOptions {
     readonly synchronization?: "data" | "all";
 }
 export interface FileDescriptorCapabilities {
+    readonly publication?: "conditional";
     readonly position?: boolean;
     readonly readObservation?: boolean;
     readonly openTruncate?: boolean;

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

@@ -30,6 +30,7 @@ export interface DirectoryEntry {
 }
 export interface FileSystemCapabilities {
     readonly open?: boolean;
+    readonly versionedDescriptors?: boolean;
     readonly readOnly?: boolean;
     readonly read?: boolean;
     readonly stat?: boolean;

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

@@ -11,6 +11,7 @@ export * from "./fs/readonly/index.js";
 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 type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./fs/webdav/index.js";

package/dist/safe-fs/core.js

@@ -10,6 +10,7 @@ export * from "./fs/readonly/index.js";
 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 * from "./fs/webdav/index.js";
 export * from "./bridge/index.js";

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

@@ -101,7 +101,7 @@ export async function openRetainedResizeFile(filesystem, path, options) {
 export function readOnlyCapabilities(capabilities) {
     const inspection = Object.fromEntries([
         "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories",
-        "symlinks", "streamingRead", "open", "retainedRead",
+        "symlinks", "streamingRead", "open", "retainedRead", "versionedDescriptors",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
         ...inspection, readOnly: true, write: false, append: false, exclusiveCreate: false,

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

@@ -2,6 +2,7 @@ import { FsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
 function admitCapabilities(path, options, capabilities) {
     if (![capabilities.positionedRead, capabilities.positionedWrite, capabilities.truncate].every(value => typeof value === "boolean")
+        || capabilities.publication !== undefined && capabilities.publication !== "conditional"
         || capabilities.position !== undefined && typeof capabilities.position !== "boolean"
         || capabilities.readObservation !== undefined && typeof capabilities.readObservation !== "boolean"
         || capabilities.openTruncate !== undefined && typeof capabilities.openTruncate !== "boolean"
@@ -67,6 +68,7 @@ class ManagedFileDescriptor {
         this.#backend = backend;
         const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && options.access !== "read";
         this.capabilities = Object.freeze({
+            ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
             ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
             ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
             ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),

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

@@ -102,7 +102,7 @@ export class MountFileSystem {
             };
             const values = mounts.map(({ backend }) => {
                 if (backend.capabilities.readOnly === true
-                    && !["open", "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
+                    && !["open", "versionedDescriptors", "read", "stat", "readdir", "realpath", "access", "readlink", "explicitDirectories", "implicitDirectories"].includes(capability))
                     return false;
                 const declared = backend.capabilities[capability];
                 if (capability === "descriptorWriteStream" && backend.capabilities.streamingWrite === false)
@@ -114,7 +114,7 @@ export class MountFileSystem {
             return values.every(value => value === true) ? true : values.every(value => value === false) ? false : undefined;
         };
         const semantics = Object.fromEntries([
-            "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open",
+            "atomicEntryRemoval", "atomicTreeRemoval", "atomicFileMutation", "atomicFileStaging", "atomicDirectoryMetadata", "read", "stat", "readdir", "realpath", "access", "open", "versionedDescriptors",
             "write", "append", "exclusiveCreate", "explicitDirectories", "implicitDirectories", "mkdir", "recursiveMkdir",
             "remove", "removeDirectory", "recursiveRemove", "rename", "atomicRenameNoReplace", "copy", "exclusiveCopy", "readlink", "truncate",
             "streamingAppend", "randomAccessWrite", "descriptorWriteStream", "retainedResize", "atomicResize", "symlinks", "hardlinks", "permissions", "timestamps",

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

@@ -0,0 +1,27 @@
+import type { FileStat, FileSystem, FsOptions, OpenFileOptions } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+export interface ObjectFileVersion {
+    readonly revision: string;
+    readonly stat: FileStat;
+    read(position: number, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+export interface ObjectFilePublicationOptions extends FsOptions {
+    readonly size: number;
+    readonly mode: number;
+}
+export interface ObjectFileAcquireOptions extends FsOptions {
+    readonly access: OpenFileOptions["access"];
+}
+export interface ObjectFilePublicationStore {
+    acquire(path: string, options: ObjectFileAcquireOptions): Promise<ObjectFileVersion | undefined>;
+    publish?(path: string, expectedRevision: string | null, source: ByteSource, options: ObjectFilePublicationOptions): Promise<ObjectFileVersion>;
+}
+export interface ObjectFileDescriptorOptions {
+    readonly chunkBytes?: number;
+    readonly maxStagedBytes?: number;
+    readonly maxStagedPages?: number;
+    readonly maxFileBytes?: number;
+    readonly maxOpenFiles?: number;
+}
+export declare function withObjectFileDescriptors(filesystem: FileSystem, store: ObjectFilePublicationStore, options?: ObjectFileDescriptorOptions): FileSystem;

package/dist/safe-fs/fs/object-publication/index.js

@@ -0,0 +1,324 @@
+import { composeAbortSignals } from "../../contracts/abort.js";
+import { finishCleanup } from "../../contracts/cleanup.js";
+import { FsError } from "../../contracts/errors.js";
+import { validatePath } from "../../contracts/virtual-path.js";
+import { openFileDescriptor } from "../descriptor.js";
+export function withObjectFileDescriptors(filesystem, store, options = {}) {
+    const chunkBytes = options.chunkBytes ?? 65536;
+    const maxStagedBytes = options.maxStagedBytes ?? 8 * 1024 * 1024;
+    const maxStagedPages = options.maxStagedPages ?? 4096;
+    const maxFileBytes = options.maxFileBytes ?? 256 * 1024 * 1024;
+    const maxOpenFiles = options.maxOpenFiles ?? 64;
+    if (![chunkBytes, maxStagedBytes, maxStagedPages, maxFileBytes, maxOpenFiles].every(value => Number.isSafeInteger(value) && value > 0)
+        || chunkBytes > 1048576 || typeof store.acquire !== "function"
+        || store.publish !== undefined && typeof store.publish !== "function")
+        throw new TypeError("Invalid object descriptor configuration");
+    let stagedBytes = 0;
+    let openFiles = 0;
+    const version = (value) => {
+        if (!value || typeof value.revision !== "string" || value.revision.length === 0 || value.revision.length > 4096
+            || !value.stat || value.stat.type !== "file" || !Number.isSafeInteger(value.stat.size) || value.stat.size < 0
+            || !Number.isSafeInteger(value.stat.mode) || value.stat.mode < 0 || value.stat.mode > 0o177777
+            || ![value.stat.mtimeMs, value.stat.atimeMs, value.stat.ctimeMs].every(Number.isFinite)
+            || typeof value.read !== "function" || typeof value.close !== "function")
+            throw new FsError("EIO", { message: "Invalid immutable object version" });
+        if (value.stat.size > maxFileBytes)
+            throw new FsError("EFBIG", { message: "Object descriptor file limit exceeded" });
+        return Object.freeze({ revision: value.revision, stat: Object.freeze({ ...value.stat }), read: value.read.bind(value), close: value.close.bind(value) });
+    };
+    const clearPages = (state) => {
+        stagedBytes -= state.pages.size * chunkBytes;
+        state.pages.clear();
+    };
+    const open = (path, openOptions) => openFileDescriptor(path, openOptions, {
+        publication: "conditional", position: true, positionedRead: true, positionedWrite: true,
+        truncate: true, synchronization: "storage",
+    }, async (admitted) => {
+        validatePath(path);
+        if (path.length === 0)
+            throw new FsError("ENOENT", { path });
+        if (openFiles >= maxOpenFiles)
+            throw new FsError("EMFILE", { path });
+        openFiles++;
+        let acquiring = true;
+        const state = { head: undefined, position: 0, size: 0, inheritedSize: 0, modifiedAt: Date.now(), dirty: false, pages: new Map(), failure: undefined };
+        const check = (forwarded) => {
+            if (acquiring)
+                admitted.signal?.throwIfAborted();
+            forwarded.signal?.throwIfAborted();
+            if (state.failure)
+                throw state.failure.reason;
+        };
+        const perform = async (forwarded, action) => {
+            check(forwarded);
+            const scope = composeAbortSignals([...(acquiring && admitted.signal ? [admitted.signal] : []), ...(forwarded.signal ? [forwarded.signal] : [])]);
+            try {
+                const result = await action({ signal: scope.signal });
+                scope.signal.throwIfAborted();
+                return result;
+            }
+            catch (error) {
+                scope.signal.throwIfAborted();
+                throw error;
+            }
+            finally {
+                scope.dispose();
+            }
+        };
+        const readBase = async (position, length, forwarded) => {
+            const count = Math.min(length, Math.max(0, state.inheritedSize - position));
+            if (count === 0 || !state.head)
+                return new Uint8Array();
+            const data = await perform(forwarded, selected => state.head.read(position, count, selected));
+            if (!(data instanceof Uint8Array) || data.byteLength !== count)
+                throw new FsError("EIO", { path, message: "Immutable range read returned an invalid byte count" });
+            return Uint8Array.from(data);
+        };
+        const read = async (buffer, position, forwarded) => {
+            check(forwarded);
+            const count = Math.min(buffer.byteLength, Math.max(0, state.size - position));
+            let copied = 0;
+            while (copied < count) {
+                const offset = position + copied;
+                const page = Math.floor(offset / chunkBytes);
+                const within = offset % chunkBytes;
+                const length = Math.min(count - copied, chunkBytes - within);
+                const staged = state.pages.get(page);
+                if (staged)
+                    buffer.set(staged.subarray(within, within + length), copied);
+                else {
+                    buffer.fill(0, copied, copied + length);
+                    buffer.set(await readBase(offset, length, forwarded), copied);
+                }
+                copied += length;
+            }
+            return count;
+        };
+        const flush = async (forwarded) => {
+            check(forwarded);
+            if (!state.dirty)
+                return;
+            if (!store.publish)
+                throw new FsError("ENOTSUP", { path, message: "Object writes require authoritative conditional publication" });
+            const expected = state.head?.revision ?? null;
+            let emitted = 0;
+            let active = true;
+            let received;
+            let source;
+            const streamAbort = new AbortController();
+            let streamScope;
+            try {
+                await perform(forwarded, async (selected) => {
+                    streamScope = composeAbortSignals([...(selected.signal ? [selected.signal] : []), streamAbort.signal]);
+                    const bodyOptions = { signal: streamScope.signal };
+                    source = (async function* () {
+                        for (let position = 0; position < state.size; position += chunkBytes) {
+                            if (!active)
+                                throw new FsError("EBADF", { path });
+                            const bytes = new Uint8Array(Math.min(chunkBytes, state.size - position));
+                            await read(bytes, position, bodyOptions);
+                            emitted += bytes.length;
+                            yield bytes;
+                        }
+                    })();
+                    received = await store.publish(path, expected, source, { ...selected, size: state.size, mode: (state.head?.stat.mode ?? admitted.mode) & 0o7777 });
+                });
+                const published = version(received);
+                if (emitted !== state.size || published.stat.size !== state.size || published.revision === expected)
+                    throw new FsError("EIO", { path, message: "Invalid conditional publication acknowledgement" });
+                const previous = state.head;
+                state.head = published;
+                received = undefined;
+                state.inheritedSize = state.size;
+                state.modifiedAt = published.stat.mtimeMs;
+                state.dirty = false;
+                clearPages(state);
+                await previous?.close();
+            }
+            catch (reason) {
+                state.failure = { reason };
+                if (received)
+                    await finishCleanup(() => received.close(), true);
+                throw reason;
+            }
+            finally {
+                active = false;
+                streamAbort.abort(new FsError("ECANCELED", { path, syscall: "object publication stream" }));
+                try {
+                    await finishCleanup(() => source?.return(undefined), state.failure !== undefined);
+                }
+                finally {
+                    streamScope?.dispose();
+                }
+            }
+        };
+        try {
+            const capabilities = await filesystem.capabilitiesFor?.(path, admitted) ?? filesystem.capabilities;
+            check(admitted);
+            const mutating = admitted.access !== "read" || admitted.creation !== "never" || admitted.truncate;
+            if (mutating && capabilities.readOnly === true)
+                throw new FsError("EROFS", { path });
+            if (mutating && (!store.publish || capabilities.write === false))
+                throw new FsError("ENOTSUP", { path, message: "Object writes require authoritative conditional publication" });
+            if (admitted.access !== "write" && capabilities.read === false)
+                throw new FsError("EACCES", { path });
+            const acquired = await store.acquire(path, { access: admitted.access, ...(admitted.signal ? { signal: admitted.signal } : {}) });
+            if (acquired) {
+                try {
+                    state.head = version(acquired);
+                }
+                catch (error) {
+                    await finishCleanup(() => acquired.close(), true);
+                    throw error;
+                }
+            }
+            check(admitted);
+            if (state.head && admitted.creation === "exclusive")
+                throw new FsError("EEXIST", { path });
+            if (!state.head && admitted.creation === "never")
+                throw new FsError("ENOENT", { path });
+            state.size = state.head?.stat.size ?? 0;
+            state.inheritedSize = state.size;
+            state.modifiedAt = state.head?.stat.mtimeMs ?? Date.now();
+            if (!state.head || admitted.truncate) {
+                state.size = 0;
+                state.inheritedSize = 0;
+                state.dirty = true;
+                await flush(admitted);
+            }
+            acquiring = false;
+            return {
+                resource: state,
+                getPosition: async () => state.position,
+                stat: async (_state, forwarded) => {
+                    check(forwarded);
+                    const { allocatedBytes: ignoredAllocated, ...metadata } = state.head.stat;
+                    return { ...metadata, size: state.size, mtimeMs: state.modifiedAt };
+                },
+                read: async (_state, buffer, position, forwarded) => {
+                    const count = await read(buffer, position ?? state.position, forwarded);
+                    if (position === null)
+                        state.position += count;
+                    return count;
+                },
+                write: async (_state, buffer, position, forwarded) => {
+                    check(forwarded);
+                    const start = admitted.append ? state.size : position ?? state.position;
+                    const end = start + buffer.byteLength;
+                    if (!Number.isSafeInteger(end) || end > maxFileBytes)
+                        throw new FsError("EFBIG", { path, message: "Object descriptor file limit exceeded" });
+                    const first = Math.floor(start / chunkBytes);
+                    const last = Math.floor((end - 1) / chunkBytes);
+                    const missing = [];
+                    const available = Math.min(Math.floor((maxStagedBytes - stagedBytes) / chunkBytes), maxStagedPages - stagedBytes / chunkBytes);
+                    for (let page = first; page <= last; page++)
+                        if (!state.pages.has(page)) {
+                            if (missing.length >= available)
+                                throw new FsError("ENOSPC", { path, message: "Object descriptor staging budget exceeded; flush staged writes or increase maxStagedBytes/maxStagedPages" });
+                            missing.push(page);
+                        }
+                    const additional = missing.length * chunkBytes;
+                    stagedBytes += additional;
+                    const prepared = new Map();
+                    try {
+                        for (const page of missing) {
+                            const bytes = new Uint8Array(chunkBytes);
+                            bytes.set(await readBase(page * chunkBytes, chunkBytes, forwarded));
+                            prepared.set(page, bytes);
+                        }
+                        check(forwarded);
+                    }
+                    catch (error) {
+                        stagedBytes -= additional;
+                        throw error;
+                    }
+                    for (const [page, bytes] of prepared)
+                        state.pages.set(page, bytes);
+                    let copied = 0;
+                    while (copied < buffer.byteLength) {
+                        const offset = start + copied;
+                        const length = Math.min(buffer.byteLength - copied, chunkBytes - offset % chunkBytes);
+                        state.pages.get(Math.floor(offset / chunkBytes)).set(buffer.subarray(copied, copied + length), offset % chunkBytes);
+                        copied += length;
+                    }
+                    state.size = Math.max(state.size, end);
+                    state.modifiedAt = Date.now();
+                    state.dirty = true;
+                    if (position === null)
+                        state.position = end;
+                    if (admitted.synchronization !== undefined)
+                        await flush(forwarded);
+                    return buffer.byteLength;
+                },
+                truncate: async (_state, length, forwarded) => {
+                    check(forwarded);
+                    if (length > maxFileBytes)
+                        throw new FsError("EFBIG", { path });
+                    for (const [page, bytes] of state.pages) {
+                        if (page * chunkBytes >= length) {
+                            state.pages.delete(page);
+                            stagedBytes -= chunkBytes;
+                        }
+                        else if ((page + 1) * chunkBytes > length)
+                            bytes.fill(0, length % chunkBytes);
+                    }
+                    state.inheritedSize = Math.min(state.inheritedSize, length);
+                    state.size = length;
+                    state.modifiedAt = Date.now();
+                    state.dirty = true;
+                    if (admitted.synchronization !== undefined)
+                        await flush(forwarded);
+                },
+                sync: async (_state, _dataOnly, forwarded) => { await flush(forwarded); },
+                close: async () => {
+                    let failed = false;
+                    try {
+                        if (state.dirty || state.failure)
+                            await flush({});
+                    }
+                    catch (error) {
+                        failed = true;
+                        throw error;
+                    }
+                    finally {
+                        clearPages(state);
+                        const retained = state.head;
+                        state.head = undefined;
+                        try {
+                            await finishCleanup(() => retained?.close(), failed);
+                        }
+                        finally {
+                            openFiles--;
+                        }
+                    }
+                },
+            };
+        }
+        catch (error) {
+            clearPages(state);
+            try {
+                await finishCleanup(() => state.head?.close(), true);
+            }
+            finally {
+                openFiles--;
+            }
+            throw error;
+        }
+    });
+    return new Proxy(Object.create(filesystem), {
+        get(_target, property) {
+            if (property === "open")
+                return open;
+            if (property === "capabilities")
+                return { ...filesystem.capabilities, open: true, versionedDescriptors: true };
+            if (property === "capabilitiesFor")
+                return async (path, query) => {
+                    const capabilities = await filesystem.capabilitiesFor?.(path, query) ?? filesystem.capabilities;
+                    query?.signal?.throwIfAborted();
+                    return { ...capabilities, open: true, versionedDescriptors: true };
+                };
+            const value = Reflect.get(filesystem, property, filesystem);
+            return typeof value === "function" ? value.bind(filesystem) : value;
+        },
+    });
+}

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

@@ -27,7 +27,7 @@ function namespaceMetadata(metadata, signal) {
             abort();
     });
 }
-async function usedBytes(fs, limits, options, change, retained = change?.retained === true) {
+async function scanUsedBytes(fs, limits, options, change, retained = change?.retained === true) {
     let total = 0;
     let retainedTotal = 0n;
     let shrinkCredited = false;
@@ -144,6 +144,8 @@ export function withFileSystemQuota(fs, options) {
             throw new RangeError(`${name} must be a nonnegative safe integer`);
     }
     let queue = Promise.resolve();
+    let reservedBytes = 0;
+    const usedBytes = async (...args) => await scanUsedBytes(...args) + reservedBytes;
     const mutate = (operation) => {
         const result = queue.then(operation);
         queue = result.catch(() => undefined);
@@ -200,6 +202,14 @@ export function withFileSystemQuota(fs, options) {
                 try {
                     admitted.signal?.throwIfAborted();
                     const pinned = admitted.access === "read" ? undefined : { ...await descriptor.stat(admitted) };
+                    const conditional = descriptor.capabilities.publication === "conditional" && pinned !== undefined;
+                    let publishedSize = pinned?.size ?? 0;
+                    let reserved = 0;
+                    const reserve = (size) => {
+                        const next = Math.max(0, size - publishedSize);
+                        reservedBytes += next - reserved;
+                        reserved = next;
+                    };
                     admitted.signal?.throwIfAborted();
                     if (pinned && (pinned.type !== "file" || !completeIdentity(pinned))) {
                         throw new FsError("ENOTSUP", { syscall: "open", path, message: "quota requires complete retained file identity" });
@@ -211,7 +221,7 @@ export function withFileSystemQuota(fs, options) {
                         const stat = { ...await descriptor.stat(operationOptions) };
                         operationOptions.signal?.throwIfAborted();
                         if (!pinned || stat.type !== "file" || !completeIdentity(stat)
-                            || stat.identityScope !== pinned.identityScope || stat.dev !== pinned.dev || stat.ino !== pinned.ino
+                            || !conditional && (stat.identityScope !== pinned.identityScope || stat.dev !== pinned.dev || stat.ino !== pinned.ino)
                             || !Number.isSafeInteger(stat.size) || stat.size < 0) {
                             throw new FsError("EIO", { syscall: "fstat", path, message: "invalid retained quota identity or size" });
                         }
@@ -220,14 +230,31 @@ export function withFileSystemQuota(fs, options) {
                     const admitSize = async (stat, nextBytes, operationOptions) => {
                         if (!Number.isSafeInteger(nextBytes) || nextBytes < 0)
                             throw new FsError("EFBIG", { syscall: "write", path });
-                        const projected = await usedBytes(fs, scanLimits, operationOptions, { path, stat, delta: nextBytes - stat.size, retained: true });
+                        const projected = conditional
+                            ? await usedBytes(fs, scanLimits, operationOptions) - reserved + Math.max(0, nextBytes - publishedSize)
+                            : await usedBytes(fs, scanLimits, operationOptions, { path, stat, delta: nextBytes - stat.size, retained: true });
                         operationOptions.signal?.throwIfAborted();
                         if (projected > options.maxBytes)
                             throw new FileSystemQuotaError(options.maxBytes);
+                        if (conditional)
+                            reserve(Math.max(nextBytes, publishedSize + reserved));
                     };
-                    const forwarded = forwardFileDescriptor(descriptor, (syscall, operationOptions, action) => syscall === "close" ? action() : mutate(async () => {
-                        operationOptions.signal?.throwIfAborted();
-                        return action();
+                    const forwarded = forwardFileDescriptor(descriptor, (syscall, operationOptions, action) => syscall === "close" && !conditional ? action() : mutate(async () => {
+                        try {
+                            operationOptions.signal?.throwIfAborted();
+                            const result = await action();
+                            if (conditional && (syscall === "fsync" || syscall === "fdatasync")) {
+                                publishedSize = (await current(operationOptions)).size;
+                                reserve(publishedSize);
+                            }
+                            return result;
+                        }
+                        finally {
+                            if (syscall === "close") {
+                                reservedBytes -= reserved;
+                                reserved = 0;
+                            }
+                        }
                     }));
                     return {
                         ...forwarded,
@@ -251,12 +278,24 @@ export function withFileSystemQuota(fs, options) {
                             if (!Number.isSafeInteger(offset) || offset < 0)
                                 throw new FsError("EIO", { syscall: "getPosition", path });
                             await admitSize(stat, Math.max(stat.size, offset + buffer.byteLength), operationOptions);
-                            return retained.write(buffer, position, operationOptions);
+                            const count = await retained.write(buffer, position, operationOptions);
+                            if (conditional) {
+                                const size = (await current(operationOptions)).size;
+                                if (admitted.synchronization !== undefined)
+                                    publishedSize = size;
+                                reserve(size);
+                            }
+                            return count;
                         }),
                         truncate: (retained, length, operationOptions) => mutate(async () => {
                             operationOptions.signal?.throwIfAborted();
                             await admitSize(await current(operationOptions), length, operationOptions);
                             await retained.truncate(length, operationOptions);
+                            if (conditional) {
+                                if (admitted.synchronization !== undefined)
+                                    publishedSize = length;
+                                reserve(length);
+                            }
                         }),
                     };
                 }

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

@@ -13,6 +13,7 @@ export * from "./fs/readonly/index.js";
 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 type { RetainedFileSystemCleanupView, RetainedFileSystemCleanupOptions } from "./fs/scoped.js";
 export * from "./node/index.js";

package/dist/safe-fs/index.js

@@ -11,6 +11,7 @@ export * from "./fs/readonly/index.js";
 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 * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";

package/dist/safe-fs/testing/object-publication.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystem } from "../contracts/filesystem.js";
+import type { ObjectFilePublicationStore } from "../fs/object-publication/index.js";
+export interface ObjectFilePublicationConformanceFixture {
+    readonly fs: FileSystem;
+    readonly store: ObjectFilePublicationStore;
+    readonly root: string;
+    dispose(): void | Promise<void>;
+}
+export interface ObjectFilePublicationConformanceOptions {
+    readonly createFixture: () => ObjectFilePublicationConformanceFixture | Promise<ObjectFilePublicationConformanceFixture>;
+}
+export interface ObjectFilePublicationConformanceCase {
+    readonly name: string;
+    run(): Promise<void>;
+}
+export declare function createObjectFilePublicationConformanceCases(options: ObjectFilePublicationConformanceOptions): ObjectFilePublicationConformanceCase[];

package/dist/safe-fs/testing/object-publication.js

@@ -0,0 +1,145 @@
+import { finishCleanup } from "../contracts/cleanup.js";
+import { toByteSource } from "../contracts/io.js";
+import { validatePath } from "../contracts/virtual-path.js";
+import { withObjectFileDescriptors } from "../fs/object-publication/index.js";
+function check(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function bytes(actual, expected) {
+    check(actual instanceof Uint8Array && actual.length === expected.length
+        && actual.every((value, index) => value === expected[index]), "object publication returned incorrect bytes");
+}
+function conflict(reason) {
+    check(typeof reason === "object" && reason !== null && "code" in reason
+        && (reason.code === "EAGAIN" || reason.code === "EEXIST"), "conditional publication must report a version/create conflict");
+}
+export function createObjectFilePublicationConformanceCases(options) {
+    const cases = [
+        {
+            name: "object publication: immutable reads survive replacement",
+            async run({ fixture, path, track, publish }) {
+                const name = path("pinned");
+                const initial = await publish(name, null, new Uint8Array([1, 2, 3, 4]));
+                const acquired = await fixture.store.acquire(name, { access: "read" });
+                check(acquired, "published file could not be acquired");
+                track(acquired);
+                check(acquired.revision === initial.revision, "acquisition did not observe the published namespace revision");
+                const replacement = await publish(name, initial.revision, new Uint8Array([5, 6, 7]));
+                check(replacement.revision !== initial.revision, "namespace revisions must change on publication");
+                bytes(await acquired.read(1, 2), new Uint8Array([2, 3]));
+                const mutable = await acquired.read(0, 4);
+                mutable.fill(0);
+                bytes(await acquired.read(0, 4), new Uint8Array([1, 2, 3, 4]));
+                bytes(await fixture.fs.readFile(name), new Uint8Array([5, 6, 7]));
+            },
+        },
+        {
+            name: "object publication: exclusive create has exactly one winner",
+            async run({ fixture, path, publish }) {
+                const name = path("exclusive");
+                const results = await Promise.allSettled([
+                    publish(name, null, new Uint8Array([1])), publish(name, null, new Uint8Array([2])),
+                ]);
+                const winners = results.filter(result => result.status === "fulfilled");
+                const failures = results.filter(result => result.status === "rejected");
+                check(winners.length === 1 && failures.length === 1, "atomic creation must admit exactly one concurrent writer");
+                conflict(failures[0].reason);
+                bytes(await fixture.fs.readFile(name), new Uint8Array([results[0].status === "fulfilled" ? 1 : 2]));
+            },
+        },
+        {
+            name: "object publication: stale updates cannot replace an acknowledged generation",
+            async run({ fixture, path, publish }) {
+                const name = path("conditional");
+                const initial = await publish(name, null, new Uint8Array([0]));
+                const results = await Promise.allSettled([
+                    publish(name, initial.revision, new Uint8Array([1])),
+                    publish(name, initial.revision, new Uint8Array([2])),
+                ]);
+                const failures = results.filter(result => result.status === "rejected");
+                check(results.filter(result => result.status === "fulfilled").length === 1 && failures.length === 1, "conditional publication admitted conflicting revisions");
+                conflict(failures[0].reason);
+                bytes(await fixture.fs.readFile(name), new Uint8Array([results[0].status === "fulfilled" ? 1 : 2]));
+            },
+        },
+        {
+            name: "object publication: cancelled creation does not publish",
+            async run({ fixture, path, track }) {
+                const name = path("cancelled");
+                const controller = new AbortController();
+                const reason = new Error("conformance cancellation");
+                controller.abort(reason);
+                let rejected = false;
+                try {
+                    track(await fixture.store.publish(name, null, toByteSource(new Uint8Array([1])), {
+                        signal: controller.signal, size: 1, mode: 0o600,
+                    }));
+                }
+                catch (error) {
+                    check(error === reason, "publication must preserve cancellation identity");
+                    rejected = true;
+                }
+                check(rejected, "cancelled publication succeeded");
+                const visible = await fixture.store.acquire(name, { access: "read" });
+                if (visible)
+                    track(visible);
+                check(visible === undefined, "cancelled creation left a published key");
+            },
+        },
+        {
+            name: "object publication: descriptor updates flush conditionally",
+            async run({ fixture, path, track, publish }) {
+                const name = path("descriptor");
+                await publish(name, null, new Uint8Array([1, 2, 3, 4]));
+                const fs = withObjectFileDescriptors(fixture.fs, fixture.store, { chunkBytes: 4, maxStagedBytes: 16 });
+                const descriptor = track(await fs.open(name, { access: "readwrite" }));
+                check(descriptor.capabilities.publication === "conditional", "descriptor publication profile was lost");
+                await descriptor.write(new Uint8Array([7]), 1);
+                bytes(await fixture.fs.readFile(name), new Uint8Array([1, 2, 3, 4]));
+                await descriptor.sync(false);
+                bytes(await fixture.fs.readFile(name), new Uint8Array([1, 7, 3, 4]));
+                await descriptor.truncate(2);
+                await descriptor.truncate(4);
+                await descriptor.sync(false);
+                bytes(await fixture.fs.readFile(name), new Uint8Array([1, 7, 0, 0]));
+            },
+        },
+    ];
+    return cases.map(entry => ({
+        name: entry.name,
+        async run() {
+            const fixture = await options.createFixture();
+            const resources = [];
+            let failed = false;
+            try {
+                validatePath(fixture.root);
+                check(fixture.root.startsWith("/"), "conformance fixture root must be absolute");
+                check(typeof fixture.store.publish === "function", "conformance requires authoritative conditional publication");
+                const root = fixture.root.endsWith("/") ? fixture.root.slice(0, -1) : fixture.root;
+                const track = (value) => {
+                    resources.push(value);
+                    return value;
+                };
+                await entry.run({ fixture, path: name => `${root}/${name}`, track,
+                    async publish(path, revision, data) {
+                        return track(await fixture.store.publish(path, revision, toByteSource(data), { size: data.length, mode: 0o600 }));
+                    },
+                });
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                await finishCleanup(async () => {
+                    const closed = await Promise.allSettled(resources.map(resource => resource.close()));
+                    const rejected = closed.find(result => result.status === "rejected");
+                    await finishCleanup(() => fixture.dispose(), rejected !== undefined);
+                    if (rejected?.status === "rejected")
+                        throw rejected.reason;
+                }, failed);
+            }
+        },
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.660",
+  "version": "0.1.661",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -41,6 +41,12 @@
       "browser": "./dist/safe-fs/testing/atomic-filesystem.js",
       "import": "./dist/safe-fs/testing/atomic-filesystem.js"
     },
+    "./testing/object-publication": {
+      "types": "./dist/safe-fs/testing/object-publication.d.ts",
+      "workerd": "./dist/safe-fs/testing/object-publication.js",
+      "browser": "./dist/safe-fs/testing/object-publication.js",
+      "import": "./dist/safe-fs/testing/object-publication.js"
+    },
     "./node": {
       "types": {
         "browser": "./dist/safe-fs/node-unavailable.d.ts",