@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/files/structured.js

@@ -0,0 +1,284 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { base64, CHUNK_BYTES, identifier, integer, keys, string } from '../tools/validation.js';
+import { openMediaSource, pinned, resolveAbsolute } from './fence.js';
+import { configuredRoots, filesystemScope, inside, READ_ONLY } from './scope.js';
+import { MAX_UPLOAD_BYTES, TEMP_PREFIX, UPLOAD_TTL_MS, UploadStore } from './uploads.js';
+import { FileIndexCache } from './find/fileIndex.js';
+import { rankPaths } from './find/fuzzy.js';
+export const LIST_MAX_ENTRIES = 2000;
+export const LIST_MAX_VISITED = 10000;
+export const FIND_DEFAULT_LIMIT = 50;
+export const FIND_MAX_LIMIT = 200;
+/**
+ * The Files tab's file semantics (`files.*` tool requests): absolute paths in the `configured-roots` scope, or in the
+ * `read-only` scope when a request says `readOnly: true`. Errors are thrown with the messages callers see today
+ * (`tool_result.error`). Tools never compose a shell command.
+ */
+export class StructuredFiles {
+    scope;
+    uploads;
+    // Home and its ancestors walk instead of asking git: a dotfiles repository at `~` (often ignoring
+    // `*`) would answer for the whole home with just its tracked dotfiles.
+    indexes = new FileIndexCache(name => name.startsWith(TEMP_PREFIX), Date.now, scope => { const relative = path.relative(scope, this.home); return !relative.startsWith('..') && !path.isAbsolute(relative); });
+    home;
+    roots;
+    downloads;
+    constructor(scope, ttl, stateDir) {
+        this.scope = scope;
+        this.home = scope.home;
+        this.roots = [...scope.roots];
+        this.downloads = path.join(scope.home, 'Downloads');
+        this.uploads = new UploadStore(scope.roots, ttl, stateDir);
+    }
+    static async create(home, roots, ttl = UPLOAD_TTL_MS, stateDir, filesystem = false) {
+        const scope = filesystem ? await filesystemScope(home) : await configuredRoots(home, roots);
+        if (stateDir)
+            await UploadStore.prepareStateDir(stateDir);
+        const files = new StructuredFiles(scope, ttl, stateDir);
+        await files.uploads.recover((raw, missingLeaf, mutation) => files.resolve(raw, missingLeaf, mutation));
+        return files;
+    }
+    /** Uploads in flight. */
+    get activeUploads() { return this.uploads.size; }
+    scopeFor(readOnly) { return readOnly ? READ_ONLY : this.scope; }
+    /** Validates an absolute path in this instance's configured-roots scope (or the read-only scope). */
+    resolve(raw, missingLeaf = false, mutation = false, readOnly = false, followLeaf = true) {
+        return resolveAbsolute(this.scopeFor(readOnly), raw, missingLeaf, mutation, followLeaf);
+    }
+    /** The descriptor stays pinned after cwd is restored; media children inherit it, never re-open the path. */
+    openMediaSource(raw, readOnly = false) {
+        return openMediaSource(this.scopeFor(readOnly), raw);
+    }
+    async dispatch(method, p) {
+        if (p.readOnly !== undefined && typeof p.readOnly !== 'boolean')
+            throw new Error('Invalid readOnly');
+        if (p.readOnly !== undefined && !['files.list', 'files.find', 'files.read'].includes(method))
+            throw new Error('Read-only file access cannot modify files');
+        await this.expire();
+        if (method === 'files.find')
+            return this.find(p);
+        // Any write may add, move or remove a path a cached search list still holds. Invalidate before and again after
+        // the mutation: a search building its list concurrently (find takes no pin) then never caches a pre-mutation list.
+        if (!['files.list', 'files.read'].includes(method)) {
+            this.indexes.invalidate();
+            try {
+                return await this.locate(method, p);
+            }
+            finally {
+                this.indexes.invalidate();
+            }
+        }
+        return this.locate(method, p);
+    }
+    async locate(method, p) {
+        let parent;
+        if (method === 'files.upload.chunk' || method === 'files.upload.finish' || method === 'files.upload.cancel') {
+            const upload = this.uploads.get(identifier(p, 'uploadId'));
+            if (!upload && method === 'files.upload.cancel') {
+                keys(p, ['uploadId']);
+                return { ok: true };
+            }
+            if (!upload)
+                throw new Error('Upload not found or expired');
+            parent = path.dirname(upload.target);
+        }
+        else {
+            const target = await this.resolve(string(p, 'path', 4096, method === 'files.list' ? this.home : undefined), method === 'files.mkdir' || method === 'files.upload.begin', !['files.list', 'files.read'].includes(method), p.readOnly === true, !['files.rename', 'files.delete'].includes(method));
+            parent = method === 'files.list' ? target : path.dirname(target);
+        }
+        return pinned(parent, async (pin) => {
+            if (method.startsWith('files.upload.') && method !== 'files.upload.begin') {
+                // Re-read: the upload may have finished, been cancelled or expired while this call waited for the pin.
+                const upload = this.uploads.get(identifier(p, 'uploadId'));
+                if (!upload && method === 'files.upload.cancel') {
+                    keys(p, ['uploadId']);
+                    return { ok: true };
+                }
+                if (!upload)
+                    throw new Error('Upload not found or expired');
+                const stat = await fs.stat('.');
+                if (stat.dev !== upload.parent.dev || stat.ino !== upload.parent.ino) {
+                    if (method === 'files.upload.cancel') {
+                        await this.uploads.abandon(upload);
+                        return { ok: true };
+                    }
+                    throw new Error('Upload parent changed');
+                }
+            }
+            return this.perform(method, p, pin);
+        });
+    }
+    async perform(method, p, pin) {
+        switch (method) {
+            case 'files.list': {
+                keys(p, ['path', 'readOnly']);
+                const target = await this.resolve(string(p, 'path', 4096, this.home), false, false, p.readOnly === true);
+                const displayedPath = this.scope.kind === 'filesystem' ? string(p, 'path', 4096, this.home) : target;
+                const listing = await fs.opendir(pin.leaf(target));
+                const entries = [];
+                let visited = 0;
+                try {
+                    for await (const entry of listing) {
+                        if (++visited > LIST_MAX_VISITED || entries.length >= LIST_MAX_ENTRIES)
+                            throw new Error('Directory entry limit exceeded');
+                        if (entry.name.startsWith(TEMP_PREFIX) || entry.isSymbolicLink())
+                            continue;
+                        const entryPath = path.join(target, entry.name);
+                        let stat;
+                        try {
+                            await this.resolve(entryPath, false, false, p.readOnly === true);
+                            stat = await fs.lstat(pin.leaf(entryPath));
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (!stat.isFile() && !stat.isDirectory())
+                            continue;
+                        entries.push({ name: entry.name, path: path.join(displayedPath, entry.name), directory: stat.isDirectory(), size: stat.size, modifiedAt: stat.mtimeMs, createdAt: stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.ctimeMs > 0 ? stat.ctimeMs : stat.mtimeMs,
+                            ...(this.scope.kind === 'filesystem' ? { writable: await fs.access(entryPath, constants.W_OK).then(() => true, () => false) } : {}) });
+                    }
+                }
+                finally {
+                    await listing.close().catch(() => { });
+                }
+                entries.sort((a, b) => Number(b.directory) - Number(a.directory) || String(a.name).localeCompare(String(b.name)));
+                const parent = path.dirname(displayedPath);
+                return { path: displayedPath, parent: p.readOnly === true || this.scope.kind === 'filesystem' ? (parent === displayedPath ? null : parent) : this.roots.includes(target) || !this.roots.some(root => inside(parent, root)) ? null : parent, entries, roots: this.roots };
+            }
+            case 'files.read': {
+                keys(p, ['path', 'offset', 'length', 'readOnly']);
+                const offset = integer(p, 'offset', 0, Number.MAX_SAFE_INTEGER, 0);
+                const length = integer(p, 'length', 1, CHUNK_BYTES, CHUNK_BYTES);
+                const target = await this.resolve(string(p, 'path'), false, false, p.readOnly === true);
+                const handle = await pin.regularHandle(target);
+                try {
+                    const stat = await handle.stat();
+                    const buffer = Buffer.alloc(length);
+                    const { bytesRead } = await handle.read(buffer, 0, length, offset);
+                    return { data: buffer.subarray(0, bytesRead).toString('base64'), size: stat.size, eof: offset + bytesRead >= stat.size, name: path.basename(target),
+                        ...(this.scope.kind === 'filesystem' ? { writable: await fs.access(pin.leaf(target), constants.W_OK).then(() => true, () => false) } : {}) };
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            case 'files.mkdir': {
+                keys(p, ['path']);
+                const target = await this.resolve(string(p, 'path'), true, true);
+                await fs.mkdir(pin.leaf(target));
+                return { ok: true };
+            }
+            case 'files.rename': {
+                keys(p, ['path', 'name']);
+                const target = await this.resolve(string(p, 'path'), false, true, false, false);
+                const name = string(p, 'name', 255);
+                if (name === '.' || name === '..' || /[/\\]/.test(name) || name.startsWith(TEMP_PREFIX))
+                    throw new Error('Invalid new name');
+                const destination = await this.resolve(path.join(path.dirname(target), name), true, true);
+                // Node rename() overwrites files. Hard-link commits are exclusive for files; for directories,
+                // reserve the destination with mkdir and replace only that empty reservation atomically.
+                const stat = await fs.lstat(pin.leaf(target));
+                if (stat.isFile()) {
+                    await fs.link(pin.leaf(target), pin.leaf(destination));
+                    await fs.unlink(pin.leaf(target));
+                }
+                else if (stat.isDirectory()) {
+                    await fs.mkdir(pin.leaf(destination), { mode: stat.mode });
+                    try {
+                        await fs.rename(pin.leaf(target), pin.leaf(destination));
+                    }
+                    catch (error) {
+                        await fs.rmdir(pin.leaf(destination)).catch(() => { });
+                        throw error;
+                    }
+                }
+                else
+                    throw new Error('Not a regular file or directory');
+                return { ok: true };
+            }
+            case 'files.delete': {
+                keys(p, ['path']);
+                const target = await this.resolve(string(p, 'path'), false, true, false, false);
+                const stat = await fs.lstat(pin.leaf(target));
+                if (stat.isDirectory())
+                    await fs.rmdir(pin.leaf(target));
+                else if (stat.isFile())
+                    await fs.unlink(pin.leaf(target));
+                else
+                    throw new Error('Not a regular file or directory');
+                return { ok: true };
+            }
+            case 'files.upload.begin': {
+                keys(p, ['path', 'size', 'overwrite']);
+                const size = integer(p, 'size', 0, MAX_UPLOAD_BYTES);
+                if (p.overwrite !== undefined && typeof p.overwrite !== 'boolean')
+                    throw new Error('Invalid overwrite');
+                return this.uploads.begin(pin, () => this.resolve(string(p, 'path'), true, true), size, p.overwrite === true, this.scope.kind === 'filesystem', string(p, 'path'));
+            }
+            case 'files.upload.chunk': {
+                keys(p, ['uploadId', 'offset', 'data']);
+                const upload = this.uploads.use(identifier(p, 'uploadId'));
+                const offset = integer(p, 'offset', 0, MAX_UPLOAD_BYTES);
+                const bytes = base64(p.data);
+                return this.uploads.chunk(upload, offset, bytes);
+            }
+            case 'files.upload.finish': {
+                keys(p, ['uploadId']);
+                const upload = this.uploads.use(identifier(p, 'uploadId'));
+                return this.uploads.finish(pin, upload, (raw, missingLeaf, mutation) => this.resolve(raw, missingLeaf, mutation));
+            }
+            case 'files.upload.cancel': {
+                keys(p, ['uploadId']);
+                return this.uploads.cancel(identifier(p, 'uploadId'));
+            }
+            default: throw new Error('Unsupported file tool');
+        }
+    }
+    /**
+     * Fuzzy file-name search below one directory (`path`, default home). Ranking runs over the cached
+     * relative-path list; only the best candidates are re-validated against the same root/symlink fence
+     * as `files.list` before they are returned, so a path git still remembers but the disk lost, or one
+     * that became a symbolic link, never reaches the client. Uses no cwd: absolute paths throughout, so it
+     * never enters (or waits for) a `pinned()` section.
+     */
+    async find(p) {
+        keys(p, ['path', 'query', 'limit', 'readOnly']);
+        const readOnly = p.readOnly === true;
+        const query = string(p, 'query', 256).trim();
+        if (!query)
+            throw new Error('Invalid query');
+        const limit = integer(p, 'limit', 1, FIND_MAX_LIMIT, FIND_DEFAULT_LIMIT);
+        const scope = await this.resolve(string(p, 'path', 4096, this.home), false, false, readOnly);
+        const displayedScope = this.scope.kind === 'filesystem' ? string(p, 'path', 4096, this.home) : scope;
+        if (!(await fs.stat(scope)).isDirectory())
+            throw new Error('Search scope is not a directory');
+        const index = await this.indexes.get(scope);
+        const ranked = rankPaths(index.paths, query);
+        const entries = [];
+        let checked = 0;
+        // Bounded: a stale list full of vanished paths must not turn one search into a disk scan.
+        for (const hit of ranked.slice(0, limit * 4)) {
+            if (entries.length >= limit)
+                break;
+            checked++;
+            const relative = index.paths[hit.index];
+            const target = path.join(scope, relative);
+            let stat;
+            try {
+                await this.resolve(target, false, false, readOnly);
+                stat = await fs.lstat(target);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isFile() && !stat.isDirectory())
+                continue;
+            entries.push({ name: path.basename(relative), path: path.join(displayedScope, relative), directory: stat.isDirectory(), match: relative, positions: hit.positions });
+        }
+        // Candidates the fence dropped are not matches; the unchecked tail is counted as is.
+        return { path: displayedScope, entries, total: entries.length + ranked.length - checked, truncated: index.truncated, source: index.source };
+    }
+    async expire() { await this.uploads.expire(); }
+    async dispose() { await this.uploads.dispose(); }
+}

package/dist/workstation/{fileOps.js → files/text.js}

@@ -2,27 +2,26 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { link, lstat, mkdir, open, readdir, rename, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { ComputerFileError, computerFileError, resolveComputerDirCreatePath, resolveComputerDirPath, resolveComputerFilePath } from './filePaths.js';
+import { canonicalRoot, FileError, pinned, resolvePinnedDir, resolvePinnedDirCreate, resolvePinnedLeaf, resolveRelativeDir, resolveRelativeDirCreate, resolveRelativeFile, throwIfAborted, toFileError, withinRoot, } from './fence.js';
+import { assertScopeAllows } from './scope.js';
+/** Text file semantics of the platform agent tools (`file_*_request`): request-root scope only. */
 export const MAX_READ_BYTES = 8 * 1024 * 1024;
 export const MAX_PAGE_BYTES = 256 * 1024;
 export const MAX_WRITE_BYTES = 1024 * 1024;
-// Transport-free primitives. Untrusted channel requests must use fileWorkerClient, which pins the
-// parent directory before invoking these with resolvePinnedLeafPath; pathname-only resolution here
-// is retained for unit tests and trusted callers, not as a security boundary against rename races.
+// Transport-free engines (formerly fileOps.ts). Untrusted requests must go through the scope entry points at the
+// bottom of this file (or the legacy fork-per-request worker), which pin the parent directory before invoking these
+// with a pinned leaf resolver; pathname-only resolution here is retained for unit tests and trusted callers, not as a
+// security boundary against rename races.
 const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
-function throwIfAborted(signal) {
-    if (signal?.aborted)
-        throw new ComputerFileError('workstation_offline', 'File operation was cancelled');
-}
 async function snapshotFile(file, signal) {
     let handle;
     try {
         handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
         const before = await handle.stat({ bigint: true });
         if (!before.isFile())
-            throw new ComputerFileError('not_regular_file', 'Target is not a regular file');
+            throw new FileError('not_regular_file', 'Target is not a regular file');
         if (before.size > BigInt(MAX_READ_BYTES))
-            throw new ComputerFileError('too_large', 'File exceeds 8 MiB');
+            throw new FileError('too_large', 'File exceeds 8 MiB');
         const parts = [];
         let total = 0;
         while (true) {
@@ -33,25 +32,25 @@ async function snapshotFile(file, signal) {
                 break;
             total += bytesRead;
             if (total > MAX_READ_BYTES)
-                throw new ComputerFileError('too_large', 'File exceeds 8 MiB');
+                throw new FileError('too_large', 'File exceeds 8 MiB');
             parts.push(chunk.subarray(0, bytesRead));
         }
         const after = await handle.stat({ bigint: true });
         if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || BigInt(total) !== after.size) {
-            throw new ComputerFileError('conflict', 'File changed during read');
+            throw new FileError('conflict', 'File changed during read');
         }
         return Buffer.concat(parts, total);
     }
     catch (error) {
-        throw computerFileError(error);
+        throw toFileError(error);
     }
     finally {
         await handle?.close();
     }
 }
-export async function readComputerFile(request, signal, resolvePath = resolveComputerFilePath) {
+export async function readTextFile(request, signal, resolvePath = resolveRelativeFile) {
     if (!Number.isSafeInteger(request.startLine) || request.startLine < 1 || !Number.isSafeInteger(request.maxLines) || request.maxLines < 1 || request.maxLines > 2000) {
-        throw new ComputerFileError('invalid_argument', 'Invalid line range');
+        throw new FileError('invalid_argument', 'Invalid line range');
     }
     const file = await resolvePath(request.root, request.path, false);
     let bytes;
@@ -59,7 +58,7 @@ export async function readComputerFile(request, signal, resolvePath = resolveCom
         bytes = await snapshotFile(file, signal);
     }
     catch (error) {
-        if (!(error instanceof ComputerFileError) || error.code !== 'conflict')
+        if (!(error instanceof FileError) || error.code !== 'conflict')
             throw error;
         bytes = await snapshotFile(file, signal);
     }
@@ -68,7 +67,7 @@ export async function readComputerFile(request, signal, resolvePath = resolveCom
         source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
     }
     catch {
-        throw new ComputerFileError('invalid_encoding', 'File is not valid UTF-8');
+        throw new FileError('invalid_encoding', 'File is not valid UTF-8');
     }
     const lines = [];
     for (let begin = 0; begin < source.length;) {
@@ -84,7 +83,7 @@ export async function readComputerFile(request, signal, resolvePath = resolveCom
     for (let index = first; index < lines.length && selected < request.maxLines; index++) {
         const lineBytes = Buffer.byteLength(lines[index], 'utf8');
         if (lineBytes > MAX_PAGE_BYTES)
-            throw new ComputerFileError('line_too_long', 'A line exceeds 256 KiB');
+            throw new FileError('line_too_long', 'A line exceeds 256 KiB');
         if (pageBytes + lineBytes > MAX_PAGE_BYTES)
             break;
         content += lines[index];
@@ -129,17 +128,17 @@ function validUnicode(content) {
     }
     return true;
 }
-export async function writeComputerFile(request, signal, resolvePath = resolveComputerFilePath) {
+export async function writeTextFile(request, signal, resolvePath = resolveRelativeFile) {
     if (request.content.includes('\0') || !validUnicode(request.content)) {
-        throw new ComputerFileError('invalid_encoding', 'Content must be valid UTF-8 text without NUL');
+        throw new FileError('invalid_encoding', 'Content must be valid UTF-8 text without NUL');
     }
     const bytes = Buffer.from(request.content, 'utf8');
     if (bytes.length > MAX_WRITE_BYTES)
-        throw new ComputerFileError('too_large', 'Content exceeds 1 MiB');
+        throw new FileError('too_large', 'Content exceeds 1 MiB');
     if (request.mode !== 'create' && request.mode !== 'replace')
-        throw new ComputerFileError('invalid_argument', 'Invalid write mode');
+        throw new FileError('invalid_argument', 'Invalid write mode');
     if (request.mode === 'create' ? request.expectedSha256 !== undefined : !/^[0-9a-f]{64}$/.test(request.expectedSha256 ?? '')) {
-        throw new ComputerFileError('invalid_argument', 'create forbids expected_sha256; replace requires lowercase SHA-256');
+        throw new FileError('invalid_argument', 'create forbids expected_sha256; replace requires lowercase SHA-256');
     }
     throwIfAborted(signal);
     const file = await resolvePath(request.root, request.path, request.mode === 'create');
@@ -150,12 +149,12 @@ export async function writeComputerFile(request, signal, resolvePath = resolveCo
         if (request.mode === 'replace') {
             const current = await snapshotFile(file, signal);
             if (hash(current) !== request.expectedSha256)
-                throw new ComputerFileError('conflict', 'File changed since it was read');
+                throw new FileError('conflict', 'File changed since it was read');
             try {
                 mode = (await stat(file)).mode & 0o777;
             }
             catch (error) {
-                throw computerFileError(error);
+                throw toFileError(error);
             }
         }
         const parent = dirname(file);
@@ -178,18 +177,18 @@ export async function writeComputerFile(request, signal, resolvePath = resolveCo
             return { path: request.path, sizeBytes: bytes.length, sha256: hash(bytes), created: request.mode === 'create' };
         }
         catch (error) {
-            throw computerFileError(error);
+            throw toFileError(error);
         }
         finally {
             await handle?.close();
             await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
-                throw computerFileError(error); });
+                throw toFileError(error); });
         }
     });
 }
-export async function listComputerDir(request, signal, resolvePath = resolveComputerDirPath) {
+export async function listTextDir(request, signal, resolvePath = resolveRelativeDir) {
     if (!Number.isSafeInteger(request.maxEntries) || request.maxEntries < 1 || request.maxEntries > 2000) {
-        throw new ComputerFileError('invalid_argument', 'Invalid entry range');
+        throw new FileError('invalid_argument', 'Invalid entry range');
     }
     throwIfAborted(signal);
     const dir = await resolvePath(request.root, request.path);
@@ -220,7 +219,7 @@ export async function listComputerDir(request, signal, resolvePath = resolveComp
             }
             catch (error) {
                 if (error.code !== 'ENOENT')
-                    throw computerFileError(error);
+                    throw toFileError(error);
                 continue;
             }
         }
@@ -232,7 +231,7 @@ export async function listComputerDir(request, signal, resolvePath = resolveComp
             catch (error) {
                 // A file that vanished between readdir and lstat simply drops out of the snapshot.
                 if (error.code !== 'ENOENT')
-                    throw computerFileError(error);
+                    throw toFileError(error);
                 continue;
             }
         }
@@ -241,16 +240,16 @@ export async function listComputerDir(request, signal, resolvePath = resolveComp
     const nextAfter = truncated ? entries[entries.length - 1]?.name : undefined;
     return { path: request.path, entries, truncated, ...(nextAfter !== undefined ? { nextAfter } : {}) };
 }
-export async function createComputerDir(request, signal, resolvePlan = resolveComputerDirCreatePath) {
+export async function createTextDir(request, signal, resolvePlan = resolveRelativeDirCreate) {
     throwIfAborted(signal);
     const plan = await resolvePlan(request.root, request.path, request.parents);
     if (plan.missing.length === 0) {
         if (!request.parents)
-            throw new ComputerFileError('conflict', 'Target already exists');
+            throw new FileError('conflict', 'Target already exists');
         return { path: request.path, created: false };
     }
     if (!request.parents && plan.missing.length > 1) {
-        throw new ComputerFileError('not_found', 'Parent directory not found');
+        throw new FileError('not_found', 'Parent directory not found');
     }
     let cursor = plan.anchor;
     let created = false;
@@ -263,15 +262,95 @@ export async function createComputerDir(request, signal, resolvePlan = resolveCo
         }
         catch (error) {
             if (error.code !== 'EEXIST')
-                throw computerFileError(error);
+                throw toFileError(error);
             if (!request.parents)
-                throw new ComputerFileError('conflict', 'Target already exists');
+                throw new FileError('conflict', 'Target already exists');
         }
         // A component we just made (or found racing us) must be a real directory, never a symlink stand-in.
-        const entry = await lstat(target).catch(error => { throw computerFileError(error); });
+        const entry = await lstat(target).catch(error => { throw toFileError(error); });
         if (entry.isSymbolicLink() || !entry.isDirectory())
-            throw new ComputerFileError('conflict', 'Path is not a directory');
+            throw new FileError('conflict', 'Path is not a directory');
         cursor = target;
     }
     return { path: request.path, created };
 }
+const targetLocks = new Map();
+async function serialTarget(target, action) {
+    const previous = targetLocks.get(target) ?? Promise.resolve();
+    let release;
+    const gate = new Promise(resolve => { release = resolve; });
+    const queued = previous.then(() => gate);
+    targetLocks.set(target, queued);
+    await previous;
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (targetLocks.get(target) === queued)
+            targetLocks.delete(target);
+    }
+}
+// The worker client checked for cancellation after pathname validation, when it was about to start the operation.
+async function throwIfAbortedThen(signal, run) {
+    throwIfAborted(signal);
+    return run();
+}
+function requireRequestRoot(scope, operation) {
+    if (scope?.kind !== 'request-root')
+        throw new FileError('invalid_argument', 'Text file operations require a request root');
+    assertScopeAllows(scope, operation);
+}
+/**
+ * Runs `run` with the cwd pinned to `anchor`, which must still be inside the canonical root after chdir. Cancellation
+ * keeps the file worker's contract: a request cancelled once it is under way reports `outcome_unknown` for mutations
+ * and `workstation_offline` for reads.
+ */
+async function anchored(operation, root, anchor, signal, hooks, run) {
+    try {
+        await hooks?.afterValidation?.();
+        return await pinned(anchor, async () => {
+            await hooks?.afterPinned?.();
+            throwIfAborted(signal);
+            return run();
+        }, { verify: withinRoot(root), signal });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw new FileError(operation === 'write' || operation === 'mkdir' ? 'outcome_unknown' : 'workstation_offline', 'File operation was cancelled');
+        throw toFileError(error);
+    }
+}
+export async function readText(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'read');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeFile(root, request.path, false);
+    throwIfAborted(signal);
+    // As the file worker did, the result names the leaf it read.
+    return anchored('read', root, dirname(target), signal, hooks, () => readTextFile({ ...request, root: '.', path: basename(target) }, signal, resolvePinnedLeaf));
+}
+export async function writeText(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'write');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeFile(root, request.path, request.mode === 'create');
+    return serialTarget(target, () => throwIfAbortedThen(signal, () => anchored('write', root, dirname(target), signal, hooks, () => writeTextFile({ ...request, root: '.', path: basename(target) }, signal, resolvePinnedLeaf))));
+}
+export async function listDir(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'list');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeDir(root, request.path);
+    throwIfAborted(signal);
+    // Listing the root pins the root itself; '' is the zero-component leaf.
+    const anchor = target === root ? root : dirname(target);
+    const leaf = target === root ? '' : basename(target);
+    const data = await anchored('list', root, anchor, signal, hooks, () => listTextDir({ ...request, root: '.', path: leaf }, signal, resolvePinnedDir));
+    return { ...data, path: request.path };
+}
+export async function makeDir(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'mkdir');
+    const root = await canonicalRoot(scope.root);
+    const plan = await resolveRelativeDirCreate(root, request.path, request.parents);
+    throwIfAborted(signal);
+    const data = await anchored('mkdir', root, plan.anchor, signal, hooks, () => createTextDir({ ...request, root: '.', path: plan.missing.join('/') }, signal, resolvePinnedDirCreate));
+    return { ...data, path: request.path };
+}