@better-fs-tools/pi-durable 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createDurableFsTools } from "./extension.ts";
+export type { DurableFsToolsApplyPatchOptions, DurableFsToolsBashOptions, DurableFsToolsEditOptions, DurableFsToolsOptions, DurableFsToolsReadOptions, DurableFsToolsWriteOptions, } from "./extension.ts";
+export { executionEnvFileSystem } from "./filesystem.ts";
+export type { ExecutionEnvFileSystem, ExecutionEnvFileSystemOptions } from "./filesystem.ts";
+export { durableEnvFileSystem, durableEnvRunner } from "./host.ts";
+export type { DurableCallFactory, DurableEnvFileSystemOptions, DurableEnvRunnerOptions, DurableFsHost, } from "./host.ts";
+export type { EnvSymlinkPolicy } from "./policy.ts";
+export { documentReadStore, ReadStateDoc } from "./read-store.ts";
+export type { ReadStateDocument, ReadStoreApi } from "./read-store.ts";
+export { executionEnvRunner } from "./runner.ts";
+export type { ExecutionEnvRunnerOptions } from "./runner.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createDurableFsTools } from "./extension.js";
+export { executionEnvFileSystem } from "./filesystem.js";
+export { durableEnvFileSystem, durableEnvRunner } from "./host.js";
+export { documentReadStore, ReadStateDoc } from "./read-store.js";
+export { executionEnvRunner } from "./runner.js";

package/dist/policy.d.ts

@@ -0,0 +1,44 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { FileError, FileSystem as EnvFileSystem } from "@earendil-works/pi-durable/env";
+import type { FileSystemError, FileSystemRootOptions, NotAFileError } from "@better-fs-tools/fs";
+export type EnvSymlinkPolicy = "follow-within-roots" | "reject";
+export interface Roots {
+    readonly cwd: string;
+    readonly allowedRoots: readonly string[];
+    readonly denyRoots: readonly string[];
+    readonly symlinks: EnvSymlinkPolicy;
+}
+/** A path after the roots, the deny roots, and the symlink policy accepted it. */
+export interface Located {
+    /** The real path: symbolic links resolved. For a missing file, its real parent and the name. */
+    readonly target: string;
+    readonly displayPath: string;
+    readonly exists: boolean;
+    /** Real paths of missing parent directories, outermost first. Empty when the target exists. */
+    readonly missingDirectories: readonly string[];
+}
+/** The context of one operation: the call's context, also stopped by the operation's signal. */
+export declare function contextFor(base: Context, signal: AbortSignal | undefined): Context;
+export declare function resolveRoots(options: FileSystemRootOptions<EnvSymlinkPolicy, "none">, envCwd: string): Roots;
+/** The real paths of the configured roots, found once for each filesystem. */
+export interface RealRoots {
+    readonly cwd: string;
+    readonly allowedRoots: readonly string[];
+    readonly denyRoots: readonly string[];
+}
+export declare function realRoots(env: EnvFileSystem, roots: Roots, ctx: Context): Promise<RealRoots>;
+/**
+ * Checks the requested path against the configured roots, then resolves its
+ * symbolic links and checks the real path against the real roots.
+ */
+export declare function locate(env: EnvFileSystem, roots: Roots, real: RealRoots, requested: unknown, ctx: Context): Promise<Located>;
+export declare function displayPath(cwd: string, target: string): string;
+export declare function notAFile(kind: NotAFileError["kind"], located: Located): NotAFileError;
+/** Maps an execution environment FileError to a filesystem error. */
+export declare function fromFileError(error: FileError, phase: string): FileSystemError;
+export declare class AdapterRefusal extends Error {
+    readonly error: FileSystemError;
+    constructor(error: FileSystemError);
+}
+export declare function refuse(error: FileSystemError): AdapterRefusal;
+export declare function toFileSystemError(error: unknown): FileSystemError;

package/dist/policy.js

@@ -0,0 +1,201 @@
+import { withAbortSignal } from "@earendil-works/chord/context";
+import { containsPosix, posixPaths, resolvePosix } from "@better-fs-tools/fs";
+/** The context of one operation: the call's context, also stopped by the operation's signal. */
+export function contextFor(base, signal) {
+    return signal === undefined ? base : withAbortSignal(signal, base);
+}
+export function resolveRoots(options, envCwd) {
+    const base = absolutePath(options.cwd ?? envCwd, "cwd");
+    const allowed = options.allowedRoots;
+    if (!Array.isArray(allowed) || allowed.length === 0) {
+        throw new TypeError("allowedRoots must be a non-empty array");
+    }
+    if (options.denyRoots !== undefined && !Array.isArray(options.denyRoots)) {
+        throw new TypeError("denyRoots must be an array");
+    }
+    const symlinks = options.symlinks ?? "follow-within-roots";
+    if (symlinks !== "follow-within-roots" && symlinks !== "reject") {
+        throw new TypeError('symlinks must be "follow-within-roots" or "reject"');
+    }
+    if (options.identity !== undefined && options.identity !== "none") {
+        throw new TypeError('identity must be "none": an execution environment has no file identity');
+    }
+    return {
+        cwd: base,
+        allowedRoots: Object.freeze(allowed.map((root) => configuredRoot(base, root))),
+        denyRoots: Object.freeze((options.denyRoots ?? []).map((root) => configuredRoot(base, root))),
+        symlinks,
+    };
+}
+function absolutePath(value, label) {
+    if (typeof value !== "string" || !value.startsWith("/") || value.includes("\0")) {
+        throw new TypeError(`${label} must be an absolute POSIX path without NUL`);
+    }
+    return resolvePosix("/", value);
+}
+function configuredRoot(base, value) {
+    if (typeof value !== "string" || value === "" || value.includes("\0")) {
+        throw new TypeError("filesystem roots must be non-empty POSIX paths without NUL");
+    }
+    return resolvePosix(base, value);
+}
+export async function realRoots(env, roots, ctx) {
+    const real = async (path) => {
+        const result = await env.canonicalPath(path, ctx);
+        if (result.ok)
+            return resolvePosix("/", result.value);
+        // A root that does not exist yet keeps its configured path.
+        if (result.error.code === "not_found" || result.error.code === "not_supported")
+            return path;
+        throw refuse(fromFileError(result.error, "canonicalPath"));
+    };
+    return {
+        cwd: await real(roots.cwd),
+        allowedRoots: await Promise.all(roots.allowedRoots.map(real)),
+        denyRoots: await Promise.all(roots.denyRoots.map(real)),
+    };
+}
+/**
+ * Checks the requested path against the configured roots, then resolves its
+ * symbolic links and checks the real path against the real roots.
+ */
+export async function locate(env, roots, real, requested, ctx) {
+    if (typeof requested !== "string" || requested === "") {
+        throw refuse({ reason: "io", detail: "the requested path must be a non-empty string" });
+    }
+    if (requested.includes("\0")) {
+        throw refuse({ reason: "dangerous-path", detail: "the path contains NUL" });
+    }
+    const lexical = resolvePosix(roots.cwd, requested);
+    checkRoots(roots.denyRoots, roots.allowedRoots, lexical);
+    const resolved = await resolveReal(env, lexical, ctx);
+    const root = innermost(roots.allowedRoots, lexical);
+    const realRoot = real.allowedRoots[roots.allowedRoots.indexOf(root)];
+    if (roots.symlinks === "reject") {
+        const expected = posixJoin(realRoot, lexical.slice(root === "/" ? 1 : root.length + 1));
+        if (resolved.target !== expected) {
+            throw refuse({
+                reason: "denied",
+                detail: "the path contains a symbolic link and policy rejects symlinks",
+            });
+        }
+    }
+    checkRoots(real.denyRoots, real.allowedRoots, resolved.target);
+    return {
+        target: resolved.target,
+        displayPath: displayPath(real.cwd, resolved.target),
+        exists: resolved.exists,
+        missingDirectories: resolved.missingDirectories,
+    };
+}
+function checkRoots(denyRoots, allowedRoots, path) {
+    const denied = denyRoots.find((root) => containsPosix(root, path));
+    if (denied !== undefined)
+        throw refuse({ reason: "dangerous-path", detail: denied });
+    if (innermost(allowedRoots, path) === null)
+        throw refuse({ reason: "outside-allowed-roots" });
+}
+function innermost(roots, path) {
+    let found = null;
+    for (const root of roots) {
+        if (containsPosix(root, path) && (found === null || root.length > found.length))
+            found = root;
+    }
+    return found;
+}
+function posixJoin(dir, rest) {
+    return rest === "" ? dir : posixPaths.join(dir, rest);
+}
+async function resolveReal(env, lexical, ctx) {
+    const whole = await env.canonicalPath(lexical, ctx);
+    if (whole.ok)
+        return { target: resolvePosix("/", whole.value), exists: true, missingDirectories: [] };
+    if (whole.error.code !== "not_found")
+        throw refuse(fromFileError(whole.error, "canonicalPath"));
+    // Walk up to the nearest existing ancestor and join the missing names to its real path.
+    const missing = [];
+    let current = lexical;
+    for (;;) {
+        const parent = posixPaths.dirname(current);
+        missing.unshift(posixPaths.basename(current));
+        if (parent === current)
+            throw refuse({ reason: "not-found", detail: "no ancestor exists" });
+        const found = await env.canonicalPath(parent, ctx);
+        if (!found.ok) {
+            if (found.error.code !== "not_found")
+                throw refuse(fromFileError(found.error, "canonicalPath"));
+            current = parent;
+            continue;
+        }
+        const realParent = resolvePosix("/", found.value);
+        // A dangling symbolic link has no real path, and a write would follow it.
+        const first = posixJoin(realParent, missing[0]);
+        const entry = await env.fileInfo(first, ctx);
+        if (entry.ok) {
+            throw refuse({ reason: "denied", detail: "a path component is a dangling symbolic link" });
+        }
+        if (entry.error.code !== "not_found")
+            throw refuse(fromFileError(entry.error, "fileInfo"));
+        const paths = [];
+        let path = realParent;
+        for (const name of missing) {
+            path = posixJoin(path, name);
+            paths.push(path);
+        }
+        return { target: paths.at(-1), exists: false, missingDirectories: paths.slice(0, -1) };
+    }
+}
+export function displayPath(cwd, target) {
+    if (!containsPosix(cwd, target))
+        return target;
+    if (target === cwd)
+        return posixPaths.basename(target) || "/";
+    return target.slice(cwd === "/" ? 1 : cwd.length + 1);
+}
+export function notAFile(kind, located) {
+    return {
+        reason: "not-a-file",
+        kind,
+        target: { resolvedPath: located.target, displayPath: located.displayPath },
+    };
+}
+/** Maps an execution environment FileError to a filesystem error. */
+export function fromFileError(error, phase) {
+    const cause = { code: error.code, phase };
+    switch (error.code) {
+        case "aborted":
+            return { reason: "aborted", cause };
+        case "not_found":
+        case "not_directory":
+            return { reason: "not-found", cause };
+        case "permission_denied":
+            return { reason: "permission-denied", cause };
+        case "is_directory":
+            return { reason: "not-a-file", kind: "directory", target: null, cause };
+        case "not_supported":
+            return { reason: "unsupported", cause };
+        case "invalid":
+        case "unknown":
+            return { reason: "io", detail: phase, cause };
+    }
+}
+export class AdapterRefusal extends Error {
+    error;
+    constructor(error) {
+        super(error.reason);
+        this.error = error;
+        this.name = "AdapterRefusal";
+    }
+}
+export function refuse(error) {
+    return new AdapterRefusal(error);
+}
+export function toFileSystemError(error) {
+    if (error instanceof AdapterRefusal)
+        return error.error;
+    return {
+        reason: "io",
+        detail: "the execution environment adapter failed",
+        cause: { code: error instanceof Error ? error.name.slice(0, 40) : "UNKNOWN" },
+    };
+}

package/dist/read-store.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { JsonObject, ToolExecutionApi } from "@earendil-works/pi-durable";
+import type { ReadStateStore } from "@better-fs-tools/read";
+import type { DurableCallFactory } from "./host.ts";
+/** One read record. `record` is null after a delete. A type alias, so it fits JsonObject. */
+export type ReadStateDocument = {
+    record: JsonObject | null;
+};
+/**
+ * The read records of a conversation: one document for each path, keyed by
+ * the environment id and the real path. A fork starts with the records that
+ * its parent had at the fork entry, so a model in the fork can change only
+ * what that history read.
+ */
+export declare const ReadStateDoc: import("@earendil-works/pi-durable").RewindableConversationDocFamilyToken<ReadStateDocument, null>;
+/** The parts of the tool API that the store uses. */
+export type ReadStoreApi = Pick<ToolExecutionApi, "commit" | "snapshot" | "conversationId">;
+/**
+ * A per-call read store in the conversation's ReadStateDoc documents. Pass it
+ * as `state` to createDurableFsTools(). It stays after a restart, so an edit
+ * after a crash needs no new read. The environment id keeps the records of
+ * two environments apart.
+ */
+export declare function documentReadStore(): DurableCallFactory<ReadStateStore>;
+/** The read store of one call, over the tool API of the call. */
+export declare function readStoreOf(api: ReadStoreApi, envId: string, context: Context): ReadStateStore;

package/dist/read-store.js

@@ -0,0 +1,47 @@
+import { defineDocFamily } from "@earendil-works/pi-durable";
+/**
+ * The read records of a conversation: one document for each path, keyed by
+ * the environment id and the real path. A fork starts with the records that
+ * its parent had at the fork entry, so a model in the fork can change only
+ * what that history read.
+ */
+export const ReadStateDoc = defineDocFamily({
+    kind: "better-fs-tools.read-state",
+    version: 1,
+    family: true,
+    scope: "conversation",
+    history: "rewindable",
+    fork: "asOf",
+    initial: () => ({ record: null }),
+});
+/**
+ * A per-call read store in the conversation's ReadStateDoc documents. Pass it
+ * as `state` to createDurableFsTools(). It stays after a restart, so an edit
+ * after a crash needs no new read. The environment id keeps the records of
+ * two environments apart.
+ */
+export function documentReadStore() {
+    return (call) => readStoreOf(call.host.api, call.host.env.id, call.host.context);
+}
+/** The read store of one call, over the tool API of the call. */
+export function readStoreOf(api, envId, context) {
+    const conversationId = api.conversationId;
+    const keyOf = (key) => {
+        if (typeof key !== "string" || key === "") {
+            throw new TypeError("store key must be a non-empty string");
+        }
+        return `${envId}:${key}`;
+    };
+    const write = (key, record) => api.commit(async (tx) => {
+        const doc = await tx.doc(ReadStateDoc, conversationId, keyOf(key), null);
+        doc.record = record;
+    }, context);
+    return Object.freeze({
+        async get(key) {
+            const doc = await api.snapshot(ReadStateDoc, conversationId, keyOf(key), context);
+            return (doc?.record ?? null);
+        },
+        put: (key, record) => write(key, record),
+        delete: (key) => write(key, null),
+    });
+}

package/dist/runner.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { ExecutionEnv } from "@earendil-works/pi-durable/env";
+import type { CommandRunner } from "@better-fs-tools/shell";
+export interface ExecutionEnvRunnerOptions {
+    /** The Chord context of the tool call. Cancelling it stops the command too. */
+    readonly context: Context;
+    /** Default `pi-durable:<env.id>`. The bash tool description shows it. */
+    readonly id?: string;
+    /** Default env.cwd. */
+    readonly cwd?: string;
+    /**
+     * Default true: a command keeps the environment's own variables, such as
+     * PATH and HOME on a remote host, and the request's variables override them.
+     * false: the request's variables are the whole environment of the command.
+     */
+    readonly inheritEnv?: boolean;
+}
+/**
+ * Runs each command with the environment's exec(), through its shell: on the
+ * local machine for a NodeExecutionEnv, over SSH for pi-env's
+ * RemoteExecutionEnv. Output arrives as the environment reports it, stdout and
+ * stderr apart. A stop aborts the exec() call, and the environment kills the
+ * command's processes. By default the command also keeps the environment's
+ * own variables: see `inheritEnv`.
+ */
+export declare function executionEnvRunner(env: ExecutionEnv, options: ExecutionEnvRunnerOptions): CommandRunner;

package/dist/runner.js

@@ -0,0 +1,126 @@
+import { withAbortSignal } from "@earendil-works/chord/context";
+/**
+ * Runs each command with the environment's exec(), through its shell: on the
+ * local machine for a NodeExecutionEnv, over SSH for pi-env's
+ * RemoteExecutionEnv. Output arrives as the environment reports it, stdout and
+ * stderr apart. A stop aborts the exec() call, and the environment kills the
+ * command's processes. By default the command also keeps the environment's
+ * own variables: see `inheritEnv`.
+ */
+export function executionEnvRunner(env, options) {
+    if (env === null || typeof env !== "object" || typeof env.exec !== "function") {
+        throw new TypeError("executionEnvRunner needs a pi-durable ExecutionEnv");
+    }
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("executionEnvRunner options must be an object");
+    }
+    const { context, id = `pi-durable:${env.id}`, cwd = env.cwd, inheritEnv = true } = options;
+    if (context === null || typeof context !== "object" || typeof context.value !== "function") {
+        throw new TypeError("executionEnvRunner needs the Chord context of the call");
+    }
+    if (typeof id !== "string" || id === "")
+        throw new TypeError("id must be a non-empty string");
+    if (typeof inheritEnv !== "boolean")
+        throw new TypeError("inheritEnv must be a boolean");
+    if (typeof cwd !== "string" || !cwd.startsWith("/")) {
+        throw new TypeError("cwd must be an absolute POSIX path");
+    }
+    return Object.freeze({
+        id,
+        cwd,
+        run: (request) => run(env, withAbortSignal(request.signal, context), request, inheritEnv),
+    });
+}
+function run(env, ctx, request, inheritEnv) {
+    const output = new ChunkQueue();
+    const encoder = new TextEncoder();
+    const exit = (async () => {
+        try {
+            const problem = await checkCwd(env, request.cwd, ctx);
+            if (problem !== null)
+                return { code: null, signal: null, error: problem };
+            const result = await env.exec(request.command, {
+                cwd: request.cwd,
+                env: { ...request.env },
+                inheritEnv,
+                onOutput: (text, _context, info) => {
+                    if (text !== "")
+                        output.push({ stream: info.stream, bytes: encoder.encode(text) });
+                },
+            }, ctx);
+            if (result.ok)
+                return { code: result.value.exitCode, signal: null };
+            if (result.error.code === "aborted" || request.signal.aborted) {
+                return { code: null, signal: "SIGTERM" };
+            }
+            if (result.error.code === "timeout")
+                return { code: null, signal: "SIGKILL" };
+            return {
+                code: null,
+                signal: null,
+                error: { reason: "spawn-failed", detail: result.error.code },
+            };
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return { code: null, signal: "SIGTERM" };
+            const detail = error instanceof Error ? error.name : "unknown";
+            return { code: null, signal: null, error: { reason: "spawn-failed", detail } };
+        }
+        finally {
+            output.end();
+        }
+    })();
+    return { output, exit };
+}
+async function checkCwd(env, cwd, ctx) {
+    const info = await env.fileInfo(cwd, ctx);
+    if (info.ok) {
+        if (info.value.kind === "directory")
+            return null;
+        if (info.value.kind === "symlink") {
+            // fileInfo does not follow a link: ask the link's target.
+            const real = await env.canonicalPath(cwd, ctx);
+            if (!real.ok)
+                return { reason: "cwd-not-found" };
+            return checkCwd(env, real.value, ctx);
+        }
+        return { reason: "cwd-not-a-directory" };
+    }
+    return { reason: "cwd-not-found" };
+}
+/** Output chunks in arrival order, for one reader. */
+class ChunkQueue {
+    chunks = [];
+    ended = false;
+    wake = null;
+    push(chunk) {
+        if (this.ended)
+            return;
+        this.chunks.push(chunk);
+        this.notify();
+    }
+    end() {
+        this.ended = true;
+        this.notify();
+    }
+    notify() {
+        const wake = this.wake;
+        this.wake = null;
+        wake?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const next = this.chunks.shift();
+            if (next !== undefined) {
+                yield next;
+                continue;
+            }
+            if (this.ended)
+                return;
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+    }
+}

package/dist/write.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from "@earendil-works/chord/context";
+import type { ExecutionEnv, FileInfo as EnvFileInfo } from "@earendil-works/pi-durable/env";
+import type { MutateOptions, MutationOutcome, OpenOptions, StatOutcome, WriteCapabilities, WriteOptions } from "@better-fs-tools/fs";
+import type { Located } from "./policy.ts";
+/** The weak change token of a file: its size and modification time. */
+export declare function envVersion(info: EnvFileInfo): string;
+export interface EnvWrites {
+    readonly writeCapabilities: WriteCapabilities;
+    stat(path: string, options?: OpenOptions): Promise<StatOutcome>;
+    write(path: string, bytes: Uint8Array, options: WriteOptions): Promise<MutationOutcome>;
+    remove(path: string, options: MutateOptions): Promise<MutationOutcome>;
+}
+export declare function envWrites(env: ExecutionEnv, contextOf: (signal: AbortSignal | undefined) => Context, resolve: (requested: unknown, ctx: Context) => Promise<Located>): EnvWrites;

package/dist/write.js

@@ -0,0 +1,150 @@
+import { fromFileError, notAFile, refuse, toFileSystemError } from "./policy.js";
+const WRITE_CAPABILITIES = Object.freeze({ compareAndSwap: false });
+/** The weak change token of a file: its size and modification time. */
+export function envVersion(info) {
+    return `env:${info.size}:${info.mtimeMs}`;
+}
+export function envWrites(env, contextOf, resolve) {
+    /** The file at a located path, refusing anything that is not a regular file. */
+    const current = async (located, ctx) => {
+        if (!located.exists)
+            return { exists: false };
+        const result = await env.fileInfo(located.target, ctx);
+        if (!result.ok) {
+            if (result.error.code === "not_found")
+                return { exists: false };
+            throw refuse(fromFileError(result.error, "fileInfo"));
+        }
+        if (result.value.kind !== "file") {
+            throw refuse(notAFile(result.value.kind === "directory" ? "directory" : "other", located));
+        }
+        return { exists: true, info: result.value };
+    };
+    const fileStat = (located, file) => file.exists
+        ? {
+            exists: true,
+            resolvedPath: located.target,
+            displayPath: located.displayPath,
+            size: file.info.size,
+            mtimeMs: file.info.mtimeMs,
+            identity: null,
+            version: envVersion(file.info),
+            mode: null,
+            hardLinks: null,
+        }
+        : {
+            exists: false,
+            resolvedPath: located.target,
+            displayPath: located.displayPath,
+            missingDirectories: located.missingDirectories,
+        };
+    const mutated = (located, info, created) => ({
+        resolvedPath: located.target,
+        displayPath: located.displayPath,
+        version: info === null ? null : envVersion(info),
+        identity: null,
+        size: info?.size ?? null,
+        createdDirectories: created,
+    });
+    return {
+        writeCapabilities: WRITE_CAPABILITIES,
+        async stat(requested, options = {}) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const ctx = contextOf(options.signal);
+            try {
+                const located = await resolve(requested, ctx);
+                return { ok: true, stat: fileStat(located, await current(located, ctx)) };
+            }
+            catch (error) {
+                return { ok: false, error: toFileSystemError(error) };
+            }
+        },
+        async write(requested, bytes, options) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const ctx = contextOf(options.signal);
+            try {
+                const located = await resolve(requested, ctx);
+                const file = await current(located, ctx);
+                refuseConflict(file, options.precondition);
+                const missing = file.exists ? [] : located.missingDirectories;
+                if (missing.length > 0 && !options.createParents) {
+                    throw refuse({ reason: "not-found", detail: "the parent directory does not exist" });
+                }
+                const created = [];
+                for (const directory of missing) {
+                    const made = await env.createDir(directory, { recursive: false }, ctx);
+                    if (!made.ok)
+                        throw refuse(fromFileError(made.error, "createDir"));
+                    created.push(directory);
+                }
+                if (ctx.abortSignal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                const written = await env.writeFile(located.target, bytes, ctx);
+                if (!written.ok)
+                    throw refuse(fromFileError(written.error, "writeFile"));
+                const after = await env.fileInfo(located.target, ctx);
+                if (!after.ok || after.value.kind !== "file") {
+                    throw refuse({ reason: "io", detail: "the file was not there after the write" });
+                }
+                return { ok: true, file: mutated(located, after.value, created) };
+            }
+            catch (error) {
+                return { ok: false, error: toMutationError(error) };
+            }
+        },
+        async remove(requested, options) {
+            if (options.signal?.aborted)
+                return { ok: false, error: { reason: "aborted" } };
+            const ctx = contextOf(options.signal);
+            try {
+                const located = await resolve(requested, ctx);
+                const file = await current(located, ctx);
+                refuseConflict(file, options.precondition);
+                if (!file.exists)
+                    throw refuse({ reason: "not-found" });
+                if (ctx.abortSignal?.aborted)
+                    throw refuse({ reason: "aborted" });
+                const removed = await env.remove(located.target, { recursive: false }, ctx);
+                if (!removed.ok)
+                    throw refuse(fromFileError(removed.error, "remove"));
+                return { ok: true, file: mutated(located, null, []) };
+            }
+            catch (error) {
+                return { ok: false, error: toMutationError(error) };
+            }
+        },
+    };
+}
+function refuseConflict(file, precondition) {
+    switch (precondition.kind) {
+        case "absent":
+            if (file.exists)
+                throw new WriteRefusal({ reason: "exists" });
+            return;
+        case "version":
+            if (!file.exists || envVersion(file.info) !== precondition.version) {
+                throw new WriteRefusal({ reason: "changed" });
+            }
+            return;
+        case "any":
+            return;
+        default:
+            throw refuse({ reason: "io", detail: "unknown precondition" });
+    }
+}
+class WriteRefusal extends Error {
+    error;
+    constructor(error) {
+        super(error.reason);
+        this.error = error;
+        this.name = "WriteRefusal";
+    }
+}
+// The environment reports no disk-full or read-only code, so those failures are "io".
+function toMutationError(error) {
+    if (error instanceof WriteRefusal)
+        return error.error;
+    return toFileSystemError(error);
+}