@struktoai/mirage-node 0.0.7-alpha.1 → 0.0.7-alpha.3

package/dist/mount/core.js

@@ -0,0 +1,915 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { constants as fsConstants } from 'node:fs';
+import { posix } from 'node:path';
+import { readerOf } from '@struktoai/mirage-core/workspace/files';
+import { ChunkedHandle, FileTable, overlaid, writeRuns, } from '@struktoai/mirage-core/runtime/handles/index';
+import { READ_CHUNK } from '@struktoai/mirage-core/runtime/handles/constants';
+import { classify } from '@struktoai/mirage-core/errors/index';
+import { FileStat, FileType, LIVE_KEY } from '@struktoai/mirage-core/types';
+import { rstripSlash } from '@struktoai/mirage-core/utils/slash';
+import { compareCodePoints } from '@struktoai/mirage-core/utils/sort';
+import { DIR_MODE, DIR_SIZE, atimeMs, contentSize, deviceRdev, isDir, isLink, mtimeMs, posixMode, } from '@struktoai/mirage-core/utils/stat_view';
+import { callsAs, currentCaller, runWithSession, } from '@struktoai/mirage-core/context/session_context';
+import { skippedAtDispatch } from '@struktoai/mirage-core/policy/match/rule';
+import { enoent } from '@struktoai/mirage-core/errors/fs';
+import { isMacosMetadata } from "./platform/macos.js";
+/**
+ * Protocol-neutral mount logic shared by every kernel adapter.
+ *
+ * Everything here is expressed in POSIX terms (attribute records, ordinary
+ * thrown errors) and imports nothing from `@zkochan/fuse-native`, so it is
+ * reusable by a non-FUSE adapter and unit-testable without a kernel.
+ *
+ * The division of labour: this class decides *what* the filesystem
+ * contains, an adapter decides *how* to say it to a particular kernel
+ * interface. Adapters translate the errors thrown here into their own
+ * error codes with `classifyErrno`. Mirrors Python's `MountCore`.
+ *
+ * Every op goes through `ws.vfs`, which delegates to the dispatcher, so
+ * a mount walks the same dispatcher as a shell line (mount modes, policies,
+ * cache, invalidation) and every op it runs lands on the `ws.vfs.records`
+ * ledger. Reaching `ws.dispatch` from here instead would skip the record;
+ * reaching a backend directly would skip the dispatcher.
+ */
+export class MountCore {
+    files;
+    session;
+    now;
+    root;
+    handles = new FileTable();
+    // Per file identity: the hydration read out (opens share it), a
+    // generation a change under it bumps, the chain of mutations, the chain of
+    // removals, and the opens out that a removal waits for.
+    hydrations = new Map();
+    hydrationGen = new Map();
+    pending = new Map();
+    removals = new Map();
+    opening = new Map();
+    uid;
+    gid;
+    constructor(files, options = {}) {
+        this.files = files;
+        this.now = new Date();
+        this.root = options.rootPrefix !== undefined ? rstripSlash(options.rootPrefix) : '';
+        this.uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+        this.gid = typeof process.getgid === 'function' ? process.getgid() : 0;
+        this.session = options.session ?? null;
+        const skipped = this.session === null ? [] : skippedAtDispatch(this.session.commands);
+        if (this.session !== null && skipped.length > 0) {
+            // This entry point sees ops, never a line, so the profile's command-level
+            // rules have nothing here to judge.
+            console.warn(`session ${this.session.sessionId}: an entry point that sees only ops (a kernel mount, ` +
+                `SFTP, codex-exec's file calls) cannot apply ${skipped.join('; ')}; path rules, ` +
+                'hides and modes still hold');
+        }
+    }
+    // ── helpers ──────────────────────────────────────────────────────
+    /**
+     * Run one op under the bound session's mount grants and profile, as the
+     * Python MountCore binds each op: dispatch reads the session from
+     * context, so binding at the op entry point is what scopes a kernel or
+     * SFTP mount to it. Unbound, an op runs as whatever session is current.
+     */
+    op(fn) {
+        return this.session === null ? fn() : runWithSession(this.session, fn);
+    }
+    resolve(path) {
+        if (this.root === '')
+            return path;
+        return path === '/' ? this.root : this.root + path;
+    }
+    dirStat() {
+        return {
+            mtime: this.now,
+            atime: this.now,
+            ctime: this.now,
+            nlink: 2,
+            size: DIR_SIZE,
+            mode: DIR_MODE,
+            uid: this.uid,
+            gid: this.gid,
+            rdev: 0,
+        };
+    }
+    /**
+     * The attrs for one stat row, the way a guest's stat reads it. The row
+     * carries the namespace overlay (chmod bits, chown ids, a touched mtime),
+     * so what a metadata op stored is what the mount shows, and a device
+     * keeps its type and numbers. String uid/gid (names) fall back to the
+     * mounting user: the kernel wants numbers and there is no user db to map
+     * against. A missing stamp falls back to the mount's start time; epoch
+     * zero is a real time and lands. `size` replaces the row's, from an open
+     * handle or a link's shown target. Mirrors Python's `MountCore.attrs`.
+     */
+    attrs(s, size = null) {
+        const mtime = mtimeMs(s);
+        const when = mtime === null ? this.now : new Date(mtime);
+        const atime = atimeMs(s);
+        return {
+            mtime: when,
+            atime: atime === null ? when : new Date(atime),
+            ctime: when,
+            nlink: isDir(s) ? 2 : 1,
+            size: size ?? contentSize(s),
+            mode: posixMode(s),
+            uid: typeof s.uid === 'number' ? s.uid : this.uid,
+            gid: typeof s.gid === 'number' ? s.gid : this.gid,
+            rdev: deviceRdev(s),
+        };
+    }
+    /**
+     * The target to present for a link at a mount path. Relative targets are
+     * stored verbatim and returned as-is. Absolute targets name virtual
+     * paths, so they are rewritten relative to the link's directory: returned
+     * raw, the kernel would resolve them against the host root and escape
+     * the mountpoint.
+     */
+    shownTarget(path, target) {
+        if (!target.startsWith('/'))
+            return target;
+        let virtualTarget = target;
+        if (this.root !== '') {
+            if (target === this.root) {
+                virtualTarget = '/';
+            }
+            else if (target.startsWith(this.root + '/')) {
+                virtualTarget = target.slice(this.root.length);
+            }
+            else {
+                // points outside the scoped root: unreachable through this
+                // mount, keep the stored form (a dangling link is legal)
+                return target;
+            }
+        }
+        const slash = path.lastIndexOf('/');
+        const parent = slash <= 0 ? '/' : path.slice(0, slash);
+        // A target that is the link's own directory is `.`, as Python's relpath
+        // names it; posix.relative answers the empty string.
+        return posix.relative(parent, virtualTarget) || '.';
+    }
+    /**
+     * The length of the bytes an open handle on the file holds. A size-unknown
+     * file is read whole when it opens, so while a handle is open its length
+     * answers a stat by path too (`ls -l` beside a `cat`). Once every handle
+     * is released, the dispatcher answers from the workspace cache instead.
+     * Mirrors Python's `held_size`.
+     */
+    heldSize(path) {
+        for (const ctx of this.openOn(this.identity(path))) {
+            if (ctx.data !== undefined)
+                return ctx.data.byteLength;
+        }
+        return null;
+    }
+    /**
+     * Read a size-unknown file whole for the handle opening it, through the
+     * dispatcher, so a caching mount keeps the bytes for the next open and for
+     * a stat once this one closes. Undefined when the read fails: open() stays
+     * permissive and the read() that follows surfaces the error. Mirrors
+     * Python's `_hydrate`.
+     */
+    hydrate(path) {
+        const key = this.identity(path);
+        const inflight = this.hydrations.get(key);
+        if (inflight !== undefined)
+            return inflight;
+        const promise = (async () => {
+            try {
+                for (;;) {
+                    const gen = this.hydrationGen.get(key) ?? 0;
+                    const data = await this.op(() => this.files.read(this.resolve(path)));
+                    // The file changed while this read was out: what came back is
+                    // stale, so read again rather than hand it over.
+                    if ((this.hydrationGen.get(key) ?? 0) !== gen)
+                        continue;
+                    return data;
+                }
+            }
+            catch (err) {
+                console.debug(`fuse: hydration read of ${path} failed, deferring to read(): ${String(err)}`);
+                return undefined;
+            }
+            finally {
+                this.hydrations.delete(key);
+                this.hydrationGen.delete(key);
+            }
+        })();
+        this.hydrations.set(key, promise);
+        return promise;
+    }
+    /**
+     * Run one mutation of a file after every mutation already queued for
+     * it, and let the next one wait for it. Serialization is per identity,
+     * so a flush through a link and a truncate through its target queue
+     * behind each other, and a flush still landing cannot be overtaken by a
+     * truncate that would then be undone when the flush completes.
+     */
+    mutate(key, fn) {
+        return this.queue(this.pending, key, fn);
+    }
+    /**
+     * Run `fn` holding the chain of every key, taken in sorted order so two
+     * callers that hold the same pair never wait on each other. Mirrors
+     * Python's `_queue_all`.
+     */
+    queueAll(queues, keys, fn) {
+        const [first = '', ...rest] = [...new Set(keys)].sort(compareCodePoints);
+        if (rest.length === 0)
+            return this.queue(queues, first, fn);
+        return this.queue(queues, first, () => this.queueAll(queues, rest, fn));
+    }
+    /**
+     * Run `fn`, which removes, replaces or moves the files at `paths`, after
+     * the opens of those names already out, with later ones held back until
+     * it is done, as the kernel orders an open and an unlink or a rename of
+     * one name. `hold` reads the rest for the handles open before; an open
+     * that slipped in while that read was out would get a chunked handle onto
+     * bytes about to go. Chains of their own, taken before any `pending` one,
+     * rather than `pending` itself: an open they wait for may be truncating
+     * there.
+     */
+    removing(paths, fn) {
+        const keys = paths.map((path) => this.identity(path, false));
+        return this.queueAll(this.removals, keys, async () => {
+            await Promise.all(keys.flatMap((key) => [...(this.opening.get(key) ?? [])]));
+            await fn();
+        });
+    }
+    /**
+     * Run `fn` after every call already queued under `key` in `queues`, and
+     * let the next one wait for it, whether it resolves or throws.
+     */
+    queue(queues, key, fn) {
+        const prev = queues.get(key) ?? Promise.resolve();
+        const run = prev.then(fn, fn);
+        const tail = run.then(() => undefined, () => undefined);
+        queues.set(key, tail);
+        void tail.then(() => {
+            if (queues.get(key) === tail)
+                queues.delete(key);
+        });
+        return run;
+    }
+    /**
+     * Land write runs on the mount, one pwrite each, in order. A pwrite keeps
+     * every stored byte the handle did not write, so nothing is read through
+     * the dispatcher first: a session that may write a file and not read it writes
+     * through FUSE, as through a write-only descriptor. The runs that landed
+     * leave `runs` in one step, so after a failure `runs` holds only what did
+     * not land and a retry never replays a run over bytes another writer has
+     * since put there. A run that fails still invalidates what the core holds,
+     * since the runs before it have landed.
+     */
+    async applyWrites(path, runs) {
+        const target = this.resolve(path);
+        let landed = 0;
+        try {
+            for (const [offset, data] of runs) {
+                await this.op(() => this.files.pwrite(target, data, offset));
+                landed += 1;
+            }
+        }
+        finally {
+            runs.splice(0, landed);
+            await this.changed(path);
+        }
+    }
+    // ── POSIX surface (throws; adapters classify) ────────────────────
+    /**
+     * POSIX attributes for a path. One stat through the dispatcher answers: a
+     * link the session cannot see is absent, as it is to the shell, and a
+     * visible one reports its own row with its target read through the
+     * dispatcher too. `follow` reports a trailing link's target rather than
+     * the link (stat rather than lstat).
+     */
+    async getattr(path, follow = false, ctx = null) {
+        let size = ctx?.data?.byteLength ?? null;
+        if (path === '/')
+            return this.rootAttrs();
+        // macOS Finder/Spotlight probes .DS_Store, ._*, .Spotlight-V100, etc.
+        // Reject early to avoid hitting the ops layer.
+        const name = path.slice(path.lastIndexOf('/') + 1);
+        if (isMacosMetadata(name)) {
+            throw enoent(path);
+        }
+        const virtual = this.resolve(path);
+        let s;
+        if (ctx?.detached !== undefined) {
+            // Its name is gone: it stats by the row its file had then.
+            s = ctx.detached;
+        }
+        else {
+            try {
+                s = await this.op(() => this.files.stat(virtual, undefined, { nofollow: !follow }));
+            }
+            catch (err) {
+                // An open descriptor keeps the bytes it had after an unlink.
+                if (size === null || classify(err) !== 'ENOENT')
+                    throw err;
+                s = new FileStat({ name, type: FileType.FILE });
+            }
+        }
+        if (isLink(s)) {
+            const target = await this.op(() => this.files.readlink(virtual));
+            return this.attrs(s, new TextEncoder().encode(this.shownTarget(path, target)).byteLength);
+        }
+        if (isDir(s))
+            return this.attrs(s);
+        // A size-unknown file stats as 0 rather than be fetched on every ls -l;
+        // direct_io keeps its reads whole regardless.
+        if (size === null && s.size === null)
+            size = this.heldSize(path);
+        if (ctx?.writeBuf !== undefined && ctx.writeBuf.length > 0) {
+            let end = size ?? contentSize(s);
+            for (const [offset, data] of ctx.writeBuf)
+                end = Math.max(end, offset + data.byteLength);
+            size = end;
+        }
+        return this.attrs(s, size);
+    }
+    /**
+     * Attributes through an open handle: the path's row, with the size the
+     * handle holds, what it wrote and has not flushed included.
+     */
+    async fgetattr(path, fd) {
+        const ctx = this.handles.get(fd) ?? null;
+        if (ctx !== null)
+            await this.settled(ctx);
+        return this.getattr(ctx?.path ?? path, ctx !== null, ctx);
+    }
+    /**
+     * The mount root's attrs: its own row through the dispatcher, so a chmod
+     * made on it shows, or a plain directory when nothing answers for it (a
+     * workspace with no mount at `/`). Mirrors Python's `root_attrs`.
+     */
+    async rootAttrs() {
+        let s;
+        try {
+            s = await this.op(() => this.files.stat(this.resolve('/')));
+        }
+        catch (err) {
+            if (classify(err) !== 'ENOENT')
+                throw err;
+            console.debug(`fuse: the mount root has no row of its own: ${String(err)}`);
+            return this.dirStat();
+        }
+        return this.attrs(s);
+    }
+    async readdir(path) {
+        const names = new Set();
+        const entries = await this.op(() => this.files.readdir(this.resolve(path)));
+        for (const e of entries) {
+            const part = rstripSlash(e).split('/').pop() ?? '';
+            if (part !== '' && !isMacosMetadata(part))
+                names.add(part);
+        }
+        return ['.', '..', ...[...names].sort(compareCodePoints)];
+    }
+    async read(path, fd, pos, len) {
+        // A rendered read: a filetype registered on the mount shows as text.
+        const ctx = this.handles.get(fd);
+        if (ctx !== undefined)
+            await this.settled(ctx);
+        if (ctx === undefined) {
+            // Whole, as a handle's first read is: the read that fills the cache
+            // and records the version a conditional write sends.
+            const data = await this.op(() => this.files.read(this.resolve(path)));
+            return data.subarray(pos, pos + len);
+        }
+        let stored;
+        if (ctx.live === true) {
+            stored = await this.op(() => this.files.read(this.resolve(ctx.path), { offset: pos, size: len }));
+        }
+        else if (ctx.chunked !== undefined && ctx.data === undefined) {
+            stored = await ctx.chunked.pread(pos, len);
+        }
+        else {
+            let held = ctx.data;
+            if (held === undefined) {
+                // A change landing while this read is out keeps it from holding
+                // what it fetched.
+                const generation = ctx.generation ?? 0;
+                held = await this.op(() => this.files.read(this.resolve(ctx.path)));
+                if ((ctx.generation ?? 0) === generation)
+                    ctx.data = held;
+            }
+            stored = held.subarray(pos, pos + len);
+        }
+        if (ctx.writeBuf === undefined || ctx.writeBuf.length === 0)
+            return stored;
+        return overlaid(stored, pos, len, ctx.writeBuf);
+    }
+    /** Buffer a write on its handle, or apply it directly when there is none. */
+    async write(path, fd, data, pos) {
+        const ctx = this.handles.get(fd);
+        const key = ctx === undefined ? this.identity(path) : ctx.key;
+        this.supersede(key, pos, data.byteLength, ctx);
+        if (ctx !== undefined) {
+            ctx.writeBuf ??= [];
+            ctx.writeBuf.push([pos, data]);
+            return;
+        }
+        await this.mutate(key, () => this.applyWrites(path, [[pos, data]]));
+    }
+    /**
+     * Cut a new write's range out of what the file's other handles hold:
+     * their bytes there are older, and the new write replaces them. No two
+     * handles on a file then hold the same bytes, so whichever flush, release
+     * or sync lands first, the file ends as its writes were made. Nothing
+     * lands here, so a write never waits on one.
+     */
+    supersede(key, pos, size, ctx) {
+        // Its name is gone: the handles open there are on another file.
+        if (ctx?.detached !== undefined)
+            return;
+        const end = pos + size;
+        for (const other of this.openOn(key)) {
+            if (other === ctx || other.writeBuf === undefined)
+                continue;
+            const kept = [];
+            for (const [at, run] of other.writeBuf) {
+                if (at >= end || at + run.byteLength <= pos) {
+                    kept.push([at, run]);
+                    continue;
+                }
+                if (at < pos)
+                    kept.push([at, run.subarray(0, pos - at)]);
+                if (at + run.byteLength > end)
+                    kept.push([end, run.subarray(end - at)]);
+            }
+            other.writeBuf = kept;
+        }
+    }
+    /**
+     * Create an empty file and return a fresh handle. `mode` is what the
+     * creator asked for, umask applied; null takes the mount's default.
+     */
+    async create(path, mode = null) {
+        const key = this.identity(path);
+        await this.mutate(key, async () => {
+            await this.op(() => this.files.create(this.resolve(path)));
+            await this.keepMode(path, mode);
+            await this.changed(path);
+        });
+        return this.handles.add({ path, key });
+    }
+    /** Create a directory, keeping the mode it was asked for. */
+    async mkdir(path, mode = null) {
+        await this.op(() => this.files.mkdir(this.resolve(path)));
+        await this.keepMode(path, mode);
+    }
+    /**
+     * Store the mode a create asked for, when it is not the one the backend
+     * made the entry with (a disk mount applies the daemon's umask), so
+     * `open(O_CREAT, 0600)` and `mkdir -m` read back as asked without a
+     * write per ordinary create. Mirrors Python's `_keep_mode`.
+     */
+    async keepMode(path, mode) {
+        if (mode === null)
+            return;
+        try {
+            const made = await this.op(() => this.files.stat(this.resolve(path)));
+            if ((posixMode(made) & 0o7777) !== (mode & 0o7777))
+                await this.setattr(path, mode);
+        }
+        catch (err) {
+            // The entry exists: a policy that refuses the stat or the chmod leaves
+            // the mode it was made with rather than failing a create that landed.
+            console.debug(`mount: keeping the mode of ${path} failed: ${String(err)}`);
+        }
+    }
+    /** The target of a namespace link, read through the dispatcher; EINVAL when not a link. */
+    async readlink(path) {
+        const target = await this.op(() => this.files.readlink(this.resolve(path)));
+        return this.shownTarget(path, target);
+    }
+    /**
+     * Create namespace link `dest -> src` (ln -s src dest; libfuse passes
+     * the pointee first). Relative sources are stored verbatim (resolved
+     * at follow time, exactly like the shell `ln -s`); absolute sources
+     * are mapped into virtual space so a scoped mount stores the path it
+     * will later follow.
+     */
+    async symlink(src, dest) {
+        // The write routes through the dispatcher like every other FUSE op, so
+        // session grants and admission policies refuse a scoped kernel
+        // mount exactly like a scoped shell.
+        const stored = src.startsWith('/') ? this.resolve(src) : src;
+        await this.op(() => this.files.symlink(this.resolve(dest), stored));
+    }
+    /**
+     * Remove the entry at `path`, a link entry like any other.
+     *
+     * A link routes through the dispatcher rather than straight to the node
+     * table: `unlink` is a LINK_ENTRY_OPS member, so the dispatcher answers a
+     * link path itself, gated by session grants and admission policies
+     * and recorded on the ledger. Writing the table here instead let a
+     * session-scoped kernel mount delete a link on a mount its profile
+     * hides. Mirrors Python's MountCore.unlink.
+     */
+    async unlink(path) {
+        const key = this.identity(path, false);
+        await this.removing([path], () => this.mutate(key, async () => {
+            const named = this.named(path);
+            const row = await this.hold(path, named);
+            await this.op(() => this.files.unlink(this.resolve(path)));
+            for (const ctx of named)
+                ctx.detached = row;
+            await this.changed(path, false);
+        }));
+    }
+    /**
+     * The one function every mutation of a file's bytes goes through. The
+     * open handles on a file are matched by its identity (the mount path with
+     * namespace links followed), and this is the only place their bytes are
+     * refreshed, so a new mutating op cannot forget one of them and a link
+     * alias cannot slip past. A hydration still in flight is outdated so it
+     * re-reads instead of handing over what it fetched, and hydrated handles
+     * on the file are refreshed in one read through the dispatcher, so fstat
+     * and read through any of them, including the handle that wrote, see the
+     * new bytes. A removal or rename passes `rehydrate = false`: POSIX keeps
+     * an open descriptor on the bytes it had, and the name, not what it
+     * points at, is what changed. A refresh that fails is logged
+     * and leaves the handles unhydrated rather than failing the committed
+     * mutation. Mirrors Python's `_changed`.
+     */
+    async changed(path, rehydrate = true) {
+        const key = this.identity(path, rehydrate);
+        if (this.hydrations.has(key)) {
+            this.hydrationGen.set(key, (this.hydrationGen.get(key) ?? 0) + 1);
+        }
+        if (!rehydrate)
+            return;
+        const handles = this.openOn(key);
+        for (const ctx of handles) {
+            ctx.generation = (ctx.generation ?? 0) + 1;
+            ctx.chunked?.drop();
+        }
+        const hydrated = handles.filter((ctx) => ctx.data !== undefined);
+        if (hydrated.length === 0)
+            return;
+        let data;
+        try {
+            data = await this.op(() => this.files.read(this.resolve(path)));
+        }
+        catch (err) {
+            // The mutation landed, so a refresh that fails must not fail it; the
+            // next read through these handles fetches and reports.
+            console.warn(`fuse: refresh of ${path} after a change failed: ${String(err)}`);
+            for (const ctx of hydrated)
+                delete ctx.data;
+            return;
+        }
+        for (const ctx of hydrated)
+            ctx.data = data;
+    }
+    async rename(src, dst) {
+        // The facade is where a cross-mount pair is refused with EXDEV,
+        // which is what makes `mv` between two backends fall back to
+        // copy+unlink instead of addressing the destination against the
+        // source's backend.
+        const source = this.resolve(src);
+        const target = this.resolve(dst);
+        const moved = this.identity(src, false);
+        await this.removing([src, dst], () => this.queueAll(this.pending, [moved, this.identity(dst, false)], async () => {
+            const replaced = this.named(dst).filter((ctx) => ctx.key !== moved);
+            const row = await this.hold(dst, replaced);
+            await this.op(() => this.files.rename(source, target));
+            for (const ctx of replaced)
+                ctx.detached = row;
+            for (const ctx of this.handles.values()) {
+                if (ctx.detached !== undefined)
+                    continue;
+                if (ctx.key === source || ctx.key.startsWith(`${source}/`)) {
+                    ctx.key = target + ctx.key.slice(source.length);
+                    ctx.path = ctx.key.slice(this.root.length);
+                }
+            }
+            await this.changed(src, false);
+            await this.changed(dst, false);
+        }));
+    }
+    // No emptiness pre-check: every backend's rmdir refuses a non-empty
+    // directory itself.
+    async rmdir(path) {
+        await this.op(() => this.files.rmdir(this.resolve(path)));
+    }
+    /**
+     * Where a mount path really points: the mount-resolved path with every
+     * namespace link followed, so two handles opened through a link and
+     * its target are recognised as the same file.
+     */
+    identity(path, follow = true) {
+        const virtual = this.resolve(path);
+        const reader = readerOf(this.files);
+        // An op on the entry itself (unlink, rename, lsetattr) names the link,
+        // which may loop: only the links above it are followed.
+        const resolved = () => follow ? reader.resolve(virtual) : reader.resolveParent(virtual);
+        // Judged as the bound session judges every op (`op`): outside it the
+        // facade's session is the default one, whose profile may hide a link
+        // this session's handles were opened through.
+        if (this.session === null)
+            return resolved();
+        return callsAs({ ...currentCaller(), session: this.session }, resolved)();
+    }
+    /**
+     * Persist a handle's buffered writes. The buffer is detached before the
+     * await so a write arriving meanwhile is not lost to the clear, and the
+     * runs that did not land are restored ahead of those later writes when
+     * persistence fails, so the acknowledged bytes stay for the handle's own
+     * flush to retry.
+     */
+    async settle(ctx) {
+        // Queued with nothing buffered too: a flush still landing has taken the
+        // buffer, and this one waits for it and retries what it puts back,
+        // rather than reporting the file settled.
+        for (;;) {
+            const key = ctx.key;
+            const landed = await this.mutate(key, async () => {
+                // A rename that moved the handle while this waited put its file in
+                // another queue: it lands from that one instead.
+                if (ctx.key !== key)
+                    return false;
+                await this.persistBuffered(ctx);
+                return true;
+            });
+            if (landed)
+                return;
+        }
+    }
+    /** The handles open on the entry at `path` itself. */
+    named(path) {
+        return this.openOn(this.identity(path, false));
+    }
+    /**
+     * The handles open on the file `key` names. A detached handle is on a file
+     * with no name left, whatever its key says.
+     */
+    openOn(key) {
+        return [...this.handles.values()].filter((ctx) => ctx.key === key && ctx.detached === undefined);
+    }
+    /** Land the buffered writes of every handle open on `key`. */
+    async landBuffered(key) {
+        for (const ctx of this.openOn(key))
+            await this.persistBuffered(ctx);
+    }
+    async persistBuffered(ctx) {
+        // A detached handle keeps what it wrote, as writes to an unlinked file
+        // stay with it: there is no name to land them on.
+        if (ctx.writeBuf === undefined || ctx.writeBuf.length === 0 || ctx.detached !== undefined)
+            return;
+        const runs = writeRuns(ctx.writeBuf);
+        ctx.writeBuf = [];
+        try {
+            await this.applyWrites(ctx.path, runs);
+        }
+        catch (err) {
+            ctx.writeBuf = [...runs, ...ctx.writeBuf];
+            throw err;
+        }
+    }
+    async truncate(path, size) {
+        // A write the kernel already acknowledged on another handle precedes
+        // this truncation in POSIX order, so it is flushed first rather than
+        // left queued to land over the shortened file at that handle's
+        // release. Handles are matched by identity, not by the path they
+        // were opened through, so a link alias is settled too. Mirrors
+        // Python's MountCore.truncate.
+        const key = this.identity(path);
+        await this.mutate(key, async () => {
+            await this.landBuffered(key);
+            await this.op(() => this.files.truncate(this.resolve(path), size));
+            await this.changed(path);
+        });
+    }
+    statfs() {
+        return {
+            bsize: 4096,
+            frsize: 4096,
+            blocks: 1024 * 1024,
+            bfree: 1024 * 1024,
+            bavail: 1024 * 1024,
+            files: 1_000_000,
+            ffree: 1_000_000,
+            favail: 1_000_000,
+            namemax: 255,
+        };
+    }
+    /**
+     * Store metadata through the dispatcher. The backend keeps what it can and
+     * the namespace overlay the rest, so a chmod, chown or `touch -d` through
+     * the mount is what `stat` in a shell reads back, on a backend with no
+     * permission bits or settable times of its own too. A null field is left
+     * as it is. Mirrors Python's `MountCore.setattr`.
+     */
+    async setattr(path, mode, uid = null, gid = null, atime = null, mtime = null, follow = false) {
+        // The kernel has already resolved any link the call follows, so a
+        // kernel mount names the entry to change, a link itself for `chown -h`;
+        // SFTP's setstat asks to follow one.
+        const fields = { nofollow: !follow };
+        if (mode !== null)
+            fields.mode = mode & 0o7777;
+        if (uid !== null)
+            fields.uid = uid;
+        if (gid !== null)
+            fields.gid = gid;
+        if (atime !== null)
+            fields.atime = atime.toISOString();
+        if (mtime !== null)
+            fields.mtime = mtime.toISOString();
+        const key = this.identity(path, follow);
+        const timed = atime !== null || mtime !== null;
+        const run = async () => {
+            // cp -p sets times on a file it still holds open: its buffered
+            // writes land first, or they would stamp over them.
+            if (timed)
+                await this.landBuffered(key);
+            await this.op(() => this.files.setattr(this.resolve(path), fields));
+        };
+        await (timed ? this.mutate(key, run) : run());
+    }
+    /**
+     * Store an extended attribute through the dispatcher, which keeps
+     * it on the path's namespace node: it outlives the mount, moves with a
+     * rename, and is the attribute every other surface (the shell's
+     * getfattr, a guest's os.getxattr) reads. Tools that set xattrs as a
+     * matter of course (rsync -aX, tar --xattrs, cp -p, Finder writing
+     * com.apple.*) succeed on a backend with no attribute slot of its own.
+     * Mirrors the python MountCore.
+     */
+    async setxattr(path, name, value, opts = {}) {
+        await this.op(() => this.files.setxattr(this.resolve(path), name, Uint8Array.from(value), opts));
+    }
+    /** One attribute, the backend's own facts included; ENODATA when unset. */
+    async getxattr(path, name) {
+        return this.op(() => this.files.getxattr(this.resolve(path), name));
+    }
+    async listxattr(path) {
+        return this.op(() => this.files.listxattr(this.resolve(path)));
+    }
+    async removexattr(path, name) {
+        await this.op(() => this.files.removexattr(this.resolve(path), name));
+    }
+    async open(path, flags = 0) {
+        for (let removal = this.removalOf(path); removal !== undefined; removal = this.removalOf(path)) {
+            await removal;
+        }
+        const keys = new Set([this.identity(path, false), this.identity(path)]);
+        const opened = this.openPath(path, flags);
+        const out = opened.then(() => undefined, () => undefined);
+        for (const key of keys)
+            this.opening.set(key, (this.opening.get(key) ?? new Set()).add(out));
+        try {
+            return await opened;
+        }
+        finally {
+            for (const key of keys) {
+                const opening = this.opening.get(key);
+                opening?.delete(out);
+                if (opening?.size === 0)
+                    this.opening.delete(key);
+            }
+        }
+    }
+    /** The open itself, which a removal of its name waits for. */
+    async openPath(path, flags) {
+        const s = await this.op(() => this.files.stat(this.resolve(path)));
+        const ctx = { path, key: this.identity(path), live: s.extra[LIVE_KEY] === true };
+        if (s.type === FileType.DIRECTORY)
+            return this.handles.add(ctx);
+        if ((flags & fsConstants.O_TRUNC) !== 0) {
+            // libfuse 3 sends no SETATTR ahead of an O_TRUNC open (atomic
+            // O_TRUNC), so the flag is the whole truncation.
+            await this.truncate(path, 0);
+        }
+        if (ctx.live === true)
+            return this.handles.add(ctx);
+        if (s.size === null) {
+            // Hydrate through the rendered read path, after an O_TRUNC too: an
+            // extension whose renderer gives an empty file a body is honored
+            // rather than shadowed by literal raw emptiness.
+            const data = await this.hydrate(path);
+            if (data !== undefined)
+                ctx.data = data;
+        }
+        else if (s.size > READ_CHUNK && (flags & fsConstants.O_TRUNC) === 0) {
+            // Read a chunk at a time, at the handle's path then (a rename moves
+            // it): a `head` must not move the file.
+            ctx.chunked = new ChunkedHandle(path, s.size, (offset, size) => this.op(() => this.files.read(this.resolve(ctx.path), { offset, size })));
+        }
+        return this.handles.add(ctx);
+    }
+    /**
+     * A removal of `path` still running. One is keyed by the name it takes, so
+     * an open through a link meets the link's removal and then its target's.
+     */
+    removalOf(path) {
+        return this.removals.get(this.identity(path, false)) ?? this.removals.get(this.identity(path));
+    }
+    /**
+     * Keep what the handles open on `path` need once it goes, and return the
+     * row they stat by from then on. POSIX keeps an open descriptor on the
+     * file it had, so an unlink or a rename onto it must not leave a handle
+     * reading or stat'ing the file at that name next. A handle holding no
+     * bytes yet (never read, or chunked and holding one chunk) gets them all
+     * from one read every such handle shares; it runs under `removing` and
+     * the file's `pending` chain, so no handle opens on the file and no write
+     * lands on it meanwhile. The handles are matched by the
+     * entry itself, so removing a link holds nothing: it takes the link,
+     * never its target's bytes. A stat or a read that fails (a policy may
+     * allow the removal and refuse either) leaves a bare row or the handles
+     * as they are, each on its own, rather than refusing a mutation the
+     * caller is allowed. Mirrors Python's `MountCore._hold`.
+     */
+    async hold(path, named) {
+        const bare = new FileStat({ name: path.slice(path.lastIndexOf('/') + 1), type: FileType.FILE });
+        if (named.length === 0)
+            return bare;
+        const virtual = this.resolve(path);
+        let row = bare;
+        try {
+            row = await this.op(() => this.files.stat(virtual));
+        }
+        catch (err) {
+            console.warn(`fuse: the row of ${path} before it goes failed: ${String(err)}`);
+        }
+        const lacking = named.filter((ctx) => ctx.data === undefined && ctx.live !== true);
+        if (lacking.length === 0)
+            return row;
+        let data;
+        try {
+            data = await this.op(() => this.files.read(virtual));
+        }
+        catch (err) {
+            console.warn(`fuse: holding ${path} before it goes failed: ${String(err)}`);
+            return row;
+        }
+        for (const ctx of lacking) {
+            ctx.data = data;
+            delete ctx.chunked;
+        }
+        return row;
+    }
+    /**
+     * Wait for a flush or truncation of the handle's file still landing, into
+     * the queue a rename moved the handle to. Mirrors Python's `_settled`.
+     */
+    async settled(ctx) {
+        let key = null;
+        while (key !== ctx.key) {
+            key = ctx.key;
+            await this.pending.get(key);
+        }
+    }
+    /**
+     * Land a handle's buffered writes and let it go. The handle goes even
+     * when the landing fails, as close(2) releases its descriptor: no
+     * adapter retries a release, so a kept handle would never close. The
+     * failure still reaches the caller.
+     */
+    async release(fd) {
+        const ctx = this.handles.get(fd);
+        try {
+            // The FSKit shim sends RELEASE with no FLUSH before it.
+            if (ctx !== undefined)
+                await this.flush(ctx.path, fd);
+        }
+        finally {
+            this.handles.pop(fd);
+        }
+    }
+    async flush(_path, fd) {
+        const ctx = this.handles.get(fd);
+        if (ctx !== undefined)
+            await this.settle(ctx);
+    }
+    /**
+     * Land what every open handle holds, as sync(2) does, for a client whose
+     * close(2) returns before it releases the handle (sshfs). A landing that
+     * fails is logged, and its bytes stay on the handle for its own flush to
+     * retry and report.
+     */
+    async sync() {
+        for (const ctx of [...this.handles.values()]) {
+            try {
+                await this.settle(ctx);
+            }
+            catch (err) {
+                console.warn(`fuse: landing ${ctx.path} failed: ${String(err)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=core.js.map