@struktoai/mirage-node 0.0.7 → 0.0.8

package/dist/mount/core.js

@@ -1,915 +0,0 @@
-// ========= 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