attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/file/write.js

@@ -0,0 +1,1028 @@
+/**
+ * Atomic workspace writes with compare-and-swap guards and a write journal.
+ *
+ * The write path is intentionally conservative:
+ *
+ * - the target is resolved through the session sandbox before any I/O;
+ * - the current fingerprint is computed from the bytes that are actually
+ *   present, so `expectFingerprint` is a real CAS rather than a cached guess;
+ * - the new bytes go to a same-directory `.amp-*.tmp` file that is `fsync`ed
+ *   and renamed over the target, so a reader never observes a half-written
+ *   file;
+ * - the parent chain is created only when `createParents` is set, and every
+ *   created level is re-checked against the sandbox;
+ * - `dryRun` performs every check and builds a projected node without touching
+ *   the disk.
+ *
+ * In-process writers serialize on `(sessionId, rootId, relativePath)`. That is
+ * not a cross-process lock: a second process is caught by the CAS fingerprint,
+ * which is why the journal records both the previous and the next fingerprint.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { NamedLocks } from "../concurrency/namedLocks.js";
+import { rawDigest } from "../fingerprint/raw.js";
+import { countLines, decodeText, detectCharset, encodeText } from "../syntax/charset.js";
+import { fail, isFilesystemError } from "./errors.js";
+import { buildFileNode } from "./file.js";
+import { describeFile, extensionOfPath, nameOfPath } from "./metadata.js";
+import { byteRangeFingerprint, locateLineSpan } from "./read.js";
+import { creationTime, formatIsoTime, formatNodeTime } from "./time.js";
+/**
+ * Default ceiling for the resulting file size, in bytes.
+ */
+const DefaultWriteBytes = 4 * 1024 * 1024;
+/**
+ * Hard ceiling for the resulting file size, regardless of host configuration.
+ */
+const MaxWriteBytes = 64 * 1024 * 1024;
+/**
+ * Chunk size used when fingerprinting an existing file without loading it.
+ */
+const HashChunkBytes = 64 * 1024;
+/**
+ * Extract an `errno` code from an unknown thrown value without trusting it.
+ */
+const errorCode = (error) => {
+    if (typeof (error) !== "object" || error === null) {
+        return "";
+    }
+    const code = error.code;
+    return typeof (code) === "string" ? code : "";
+};
+/**
+ * Translate a host filesystem failure into the closed domain taxonomy. The
+ * original message is dropped on purpose: it embeds absolute paths.
+ */
+const mapFsError = (error) => {
+    if (isFilesystemError(error)) {
+        throw error;
+    }
+    switch (errorCode(error)) {
+        case "ENOENT": {
+            return fail("not_found");
+        }
+        case "EEXIST": {
+            return fail("already_exists");
+        }
+        case "EACCES":
+        case "EPERM":
+        case "EROFS": {
+            return fail("permission_denied");
+        }
+        case "EISDIR": {
+            return fail("not_file");
+        }
+        case "ENOTDIR": {
+            return fail("not_directory");
+        }
+        case "ENAMETOOLONG": {
+            return fail("invalid_path");
+        }
+        case "ELOOP": {
+            return fail("symlink_denied");
+        }
+        case "ENOSPC":
+        case "EDQUOT": {
+            return fail("quota_exceeded");
+        }
+        default: {
+            return fail("internal_error");
+        }
+    }
+};
+/**
+ * Run a best-effort cleanup without masking the failure that caused it.
+ */
+const quietly = (action) => {
+    try {
+        action();
+    }
+    catch {
+        return;
+    }
+};
+/**
+ * Resolve a positive safe integer option, clamping it to `maximum`.
+ *
+ * @param value - Caller value, or `undefined` for the default.
+ * @param fallback - Default when the value is absent.
+ * @param maximum - Inclusive upper bound.
+ * @returns The effective value.
+ */
+const positiveInteger = (value, fallback, maximum) => {
+    if (value === (void 0)) {
+        return fallback;
+    }
+    if (!Number.isSafeInteger(value) || value < 1) {
+        return fail("invalid_arguments");
+    }
+    return Math.min(value, maximum);
+};
+/**
+ * `lstat` a path that may legitimately be absent.
+ */
+const statIfExists = (absolute) => {
+    try {
+        return lstatSync(absolute);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return undefined;
+        }
+        return mapFsError(error);
+    }
+};
+/**
+ * `lstat` a path that must exist.
+ */
+const statOrFail = (absolute) => {
+    try {
+        return lstatSync(absolute);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+};
+/**
+ * Read a file as bytes, translating a failure instead of leaking it.
+ */
+const readRegularFile = (absolute) => {
+    try {
+        return readFileSync(absolute);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+};
+/**
+ * Hash a file through a fixed-size buffer. Used for the previous fingerprint so
+ * overwriting a large file does not require loading it into memory.
+ */
+const hashRegularFile = (absolute) => {
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(HashChunkBytes);
+    let descriptor = (void 0);
+    try {
+        descriptor = openSync(absolute, "r");
+        let count = readSync(descriptor, buffer, 0, buffer.byteLength, null);
+        while (count > 0) {
+            hash.update(buffer.subarray(0, count));
+            count = readSync(descriptor, buffer, 0, buffer.byteLength, null);
+        }
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+    finally {
+        if (descriptor !== (void 0)) {
+            const openDescriptor = descriptor;
+            quietly(() => closeSync(openDescriptor));
+        }
+    }
+    return `sha256:${hash.digest("hex")}`;
+};
+/**
+ * Decode with a detected charset. A decoder failure is reported as
+ * `charset_unsupported`; a classified domain error passes through unchanged.
+ */
+const decodePreviewText = (bytes, charset) => {
+    try {
+        return decodeText(bytes, charset);
+    }
+    catch (error) {
+        if (isFilesystemError(error)) {
+            throw error;
+        }
+        return fail("charset_unsupported");
+    }
+};
+/**
+ * Build the node a successful write would produce, without writing.
+ *
+ * When the target exists its current node is the base, so descriptions and
+ * timestamps survive; only the content-derived fields are projected from the
+ * new bytes. A new target gets a minimal node whose timestamps are "now",
+ * because there is no file to inspect yet; its descriptive fields are still
+ * derived from the new bytes instead of being left empty.
+ */
+const previewFileNode = (rooted, bytes, timeZone) => {
+    const detected = detectCharset(bytes);
+    const charset = detected.binary ? "binary" : detected.charset;
+    const lines = detected.binary ? 0n : countLines(decodePreviewText(bytes, charset));
+    const fingerprint = rawDigest(bytes);
+    const byteCount = BigInt(bytes.byteLength);
+    const current = statIfExists(rooted.absolute);
+    if (current !== (void 0) && current.isFile()) {
+        const existing = buildFileNode(rooted.root, rooted.relative, { timeZone });
+        return { ...existing, charset, lines, bytes: byteCount, fingerprint };
+    }
+    const described = describeFile(rooted.absolute, rooted.relative, charset, bytes);
+    const now = new Date();
+    return {
+        type: "File",
+        path: rooted.relative,
+        name: nameOfPath(rooted.relative),
+        extension: extensionOfPath(rooted.relative),
+        children: [],
+        fingerprint,
+        charset,
+        lines,
+        bytes: byteCount,
+        create: formatNodeTime(now, timeZone),
+        modify: formatNodeTime(now, timeZone),
+        description: described.description,
+        summary: described.summary,
+        purpose: described.purpose,
+    };
+};
+/**
+ * Normalize and validate a write mode. `upsert` is the default because a write
+ * is an assignment: it should not fail merely because the file is new.
+ */
+const normalizeMode = (mode) => {
+    if (mode === (void 0)) {
+        return "upsert";
+    }
+    switch (mode) {
+        case "create":
+        case "overwrite":
+        case "upsert":
+        case "append": {
+            return mode;
+        }
+        default: {
+            return fail("invalid_arguments");
+        }
+    }
+};
+/**
+ * Validate a text encoding name.
+ */
+const normalizeEncoding = (encoding) => {
+    if (encoding === (void 0)) {
+        return "utf-8";
+    }
+    switch (encoding) {
+        case "utf-8":
+        case "utf-8-bom":
+        case "utf-16le":
+        case "utf-16be":
+        case "latin1": {
+            return encoding;
+        }
+        default: {
+            return fail("invalid_arguments");
+        }
+    }
+};
+/**
+ * Encode the request content. Raw bytes may only be written as UTF-8 (the
+ * default); declaring another encoding for already-encoded bytes is a caller
+ * bug, not something to guess about.
+ */
+const encodeContent = (content, encoding) => {
+    if (typeof (content) === "string") {
+        return encodeText(content, normalizeEncoding(encoding));
+    }
+    if (content instanceof Uint8Array) {
+        if (encoding !== (void 0) && encoding !== "utf-8") {
+            return fail("invalid_arguments");
+        }
+        return content;
+    }
+    return fail("invalid_arguments");
+};
+/**
+ * Enforce the compare-and-swap precondition. `undefined` skips the check,
+ * `null` requires an absent file and a string must match exactly.
+ */
+const checkCas = (expected, previous) => {
+    if (expected === (void 0)) {
+        return;
+    }
+    if (expected !== null && typeof (expected) !== "string") {
+        return fail("invalid_arguments");
+    }
+    if (expected === null) {
+        if (previous !== null) {
+            return fail("fingerprint_mismatch");
+        }
+        return;
+    }
+    if (previous !== expected) {
+        return fail("fingerprint_mismatch");
+    }
+};
+/**
+ * Enforce the mode precondition against the observed file state.
+ */
+const checkMode = (mode, exists) => {
+    if (mode === "create" && exists) {
+        return fail("already_exists");
+    }
+    if (mode === "overwrite" && !exists) {
+        return fail("not_found");
+    }
+};
+/**
+ * Assemble the bytes that end up on disk. Append reads the previous bytes and
+ * concatenates; every other mode writes exactly the encoded fragment. The
+ * size ceiling applies to the result, so an append cannot grow past it.
+ */
+const finalContent = (absolute, encoded, mode, current, maxBytes) => {
+    if (mode === "append" && current !== (void 0)) {
+        if (current.size + encoded.byteLength > maxBytes) {
+            return fail("quota_exceeded");
+        }
+        const previous = readRegularFile(absolute);
+        const combined = new Uint8Array(previous.byteLength + encoded.byteLength);
+        combined.set(previous, 0);
+        combined.set(encoded, previous.byteLength);
+        return combined;
+    }
+    if (encoded.byteLength > maxBytes) {
+        return fail("quota_exceeded");
+    }
+    return encoded;
+};
+/**
+ * Create one missing directory level after checking it against the sandbox.
+ */
+const makeDirectoryChain = (sandbox, root, relative) => {
+    const segments = relative.split("/");
+    for (let index = 1; index <= segments.length; index += 1) {
+        const current = segments.slice(0, index).join("/");
+        const absolute = join(root.path, current);
+        if (!sandbox.contains(root.path, absolute)) {
+            return fail("path_escape");
+        }
+        sandbox.revalidate({ root, relative: current, absolute });
+        const stat = statIfExists(absolute);
+        if (stat !== (void 0)) {
+            if (!stat.isDirectory()) {
+                return fail("not_directory");
+            }
+            continue;
+        }
+        try {
+            mkdirSync(absolute);
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST") {
+                return mapFsError(error);
+            }
+        }
+    }
+};
+/**
+ * Validate the existing prefix of a directory chain without creating anything.
+ * Used by `dryRun`, which must reject a non-directory ancestor but must not
+ * mutate the disk.
+ */
+const validateDirectoryChain = (sandbox, root, relative) => {
+    const segments = relative.split("/");
+    for (let index = 1; index <= segments.length; index += 1) {
+        const current = segments.slice(0, index).join("/");
+        const absolute = join(root.path, current);
+        if (!sandbox.contains(root.path, absolute)) {
+            return fail("path_escape");
+        }
+        sandbox.revalidate({ root, relative: current, absolute });
+        const stat = statIfExists(absolute);
+        if (stat === (void 0)) {
+            return;
+        }
+        if (!stat.isDirectory()) {
+            return fail("not_directory");
+        }
+    }
+};
+/**
+ * Ensure the target's parent directory exists (or would be creatable).
+ */
+const prepareParent = (sandbox, rooted, createParents, materialize) => {
+    const segments = rooted.relative.split("/");
+    if (segments.length <= 1) {
+        return;
+    }
+    const parent = segments.slice(0, -1).join("/");
+    if (createParents) {
+        if (materialize) {
+            makeDirectoryChain(sandbox, rooted.root, parent);
+        }
+        else {
+            validateDirectoryChain(sandbox, rooted.root, parent);
+        }
+        return;
+    }
+    const absolute = join(rooted.root.path, parent);
+    if (!sandbox.contains(rooted.root.path, absolute)) {
+        return fail("path_escape");
+    }
+    sandbox.revalidate({ root: rooted.root, relative: parent, absolute });
+    const stat = statIfExists(absolute);
+    if (stat === (void 0)) {
+        return fail("not_found");
+    }
+    if (!stat.isDirectory()) {
+        return fail("not_directory");
+    }
+};
+/**
+ * Write bytes through a same-directory temporary file: write, `fsync`, close,
+ * then `rename` over the target. A failure before the rename removes the
+ * temporary file; the target is never truncated in place.
+ */
+const atomicWrite = (absolute, bytes, modeBits) => {
+    const temp = join(dirname(absolute), `.amp-${randomBytes(8).toString("hex")}.tmp`);
+    let descriptor = (void 0);
+    let renamed = false;
+    try {
+        descriptor = openSync(temp, "wx", modeBits === (void 0) ? 0o666 : modeBits);
+        writeFileSync(descriptor, bytes);
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = (void 0);
+        renameSync(temp, absolute);
+        renamed = true;
+    }
+    finally {
+        if (descriptor !== (void 0)) {
+            const openDescriptor = descriptor;
+            quietly(() => closeSync(openDescriptor));
+        }
+        if (!renamed) {
+            quietly(() => rmSync(temp, { force: true }));
+        }
+    }
+};
+/**
+ * Write locks keyed by `(sessionId, rootId, relativePath)`.
+ *
+ * The class is exported so a host can own one registry and share it with other
+ * workspace components; {@link writeFile} uses a process-wide registry because
+ * its frozen signature carries no lock parameter.
+ */
+export class WriteLocks {
+    locks = new NamedLocks();
+    async run(name, fn) {
+        return this.locks.run(name, fn);
+    }
+    /**
+     * Number of distinct lock names seen so far.
+     */
+    get size() {
+        return this.locks.size;
+    }
+}
+/**
+ * Process-wide lock registry used by {@link writeFile}.
+ */
+const WriteLockRegistry = new WriteLocks();
+/**
+ * Run the checks and the write while holding the path lock. Journal creation is
+ * metadata only; the callback and the tree refresh run after the lock is
+ * released so a callback can safely write the same path again.
+ */
+const writeLocked = (context) => {
+    context.sandbox.revalidate(context.rooted);
+    const current = statIfExists(context.rooted.absolute);
+    if (current !== (void 0)) {
+        if (current.isSymbolicLink()) {
+            return fail("symlink_denied");
+        }
+        if (!current.isFile()) {
+            return fail("not_file");
+        }
+    }
+    const previousFingerprint = current === (void 0) ? null : hashRegularFile(context.rooted.absolute);
+    checkCas(context.request.expectFingerprint, previousFingerprint);
+    checkMode(context.mode, current !== (void 0));
+    const encoded = encodeContent(context.content, context.request.encoding);
+    const bytes = finalContent(context.rooted.absolute, encoded, context.mode, current, context.maxBytes);
+    prepareParent(context.sandbox, context.rooted, context.createParents, !context.dryRun);
+    const created = current === (void 0);
+    context.sandbox.revalidate(context.rooted);
+    if (context.dryRun) {
+        const preview = previewFileNode(context.rooted, bytes, context.timeZone);
+        return {
+            result: {
+                node: preview,
+                previousFingerprint,
+                created,
+                dryRun: true,
+                bytesWritten: BigInt(bytes.byteLength),
+                revision: preview.fingerprint,
+            },
+            journal: (void 0),
+            relative: context.rooted.relative,
+        };
+    }
+    atomicWrite(context.rooted.absolute, bytes, current === (void 0) ? (void 0) : current.mode & 0o777);
+    context.sandbox.revalidate(context.rooted);
+    const nextStat = statOrFail(context.rooted.absolute);
+    const node = fileNodeFromBytes(context.rooted, bytes, nextStat, context.timeZone);
+    let journal = (void 0);
+    if (context.options.journal !== (void 0)) {
+        journal = {
+            id: `w.${randomBytes(8).toString("hex")}`,
+            sessionId: context.sessionId,
+            rootId: context.rooted.root.id,
+            path: context.rooted.relative,
+            mode: context.mode,
+            previousFingerprint,
+            nextFingerprint: rawDigest(bytes),
+            bytes: BigInt(bytes.byteLength),
+            at: formatIsoTime(new Date()),
+        };
+    }
+    return {
+        result: {
+            node,
+            previousFingerprint,
+            created,
+            dryRun: false,
+            bytesWritten: BigInt(bytes.byteLength),
+            revision: node.fingerprint,
+        },
+        journal,
+        relative: context.rooted.relative,
+    };
+};
+/**
+ * Publish the journal record and refresh the tree after the lock is released.
+ */
+const publishWrite = (commit, options) => {
+    if (commit.result.dryRun) {
+        return commit.result;
+    }
+    if (options.journal !== (void 0) && commit.journal !== (void 0)) {
+        options.journal(commit.journal);
+    }
+    const tree = options.tree;
+    if (tree === (void 0)) {
+        return commit.result;
+    }
+    return { ...commit.result, revision: tree.refresh(commit.relative).revision };
+};
+/**
+ * Write one workspace file atomically.
+ *
+ * Order of checks matches the contract: resolve, lock, read the current file
+ * and its fingerprint, CAS, mode, content encoding, size ceiling, parent
+ * directory, then the atomic rename. A `dryRun` stops right after the parent
+ * check and returns the projected node instead of writing.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and the journal.
+ * @param request - Path, content, mode, CAS precondition and dry-run flag.
+ * @param options - Size ceiling, journal sink, tree and timestamp mode.
+ * @returns The new node, previous fingerprint and write metadata.
+ */
+export const writeFile = async (sandbox, sessionId, request, options = {}) => {
+    if (typeof (sessionId) !== "string" || sessionId.length === 0 || sessionId.includes("\u0000")) {
+        return fail("invalid_arguments");
+    }
+    if (typeof (request) !== "object" || request === null) {
+        return fail("invalid_arguments");
+    }
+    const settings = options === (void 0) || options === null ? {} : options;
+    const mode = normalizeMode(request.mode);
+    const maxBytes = positiveInteger(settings.maxBytes, DefaultWriteBytes, MaxWriteBytes);
+    const rooted = sandbox.resolve(request.path, mode === "create" ? "create" : "write");
+    if (rooted.relative === ".") {
+        return fail("not_file");
+    }
+    const content = request.content;
+    const snapshotContent = typeof (content) === "string" ? content : content instanceof Uint8Array ? new Uint8Array(content) : content;
+    const timeZone = settings.timeZone === "utc" ? "utc" : "local";
+    const context = {
+        sandbox,
+        sessionId,
+        rooted,
+        mode,
+        request,
+        content: snapshotContent,
+        options: settings,
+        maxBytes,
+        dryRun: request.dryRun === true,
+        createParents: request.createParents === true,
+        timeZone,
+    };
+    const lockName = `${sessionId}\u0000${rooted.root.id}\u0000${rooted.relative}`;
+    const commit = await WriteLockRegistry.run(lockName, () => writeLocked(context)).catch((error) => mapFsError(error));
+    try {
+        return publishWrite(commit, settings);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+};
+/**
+ * Validate a raw byte offset.
+ */
+const patchByteOffset = (value) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        return fail("invalid_arguments");
+    }
+    return value;
+};
+/**
+ * Validate a 1-based start line.
+ */
+const patchStartLine = (value) => {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        return fail("invalid_arguments");
+    }
+    return value;
+};
+/**
+ * Validate an inclusive end line; `0` is the insertion point before line 1.
+ */
+const patchEndLine = (value) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        return fail("invalid_arguments");
+    }
+    return value;
+};
+/**
+ * A range patch cannot be unsafe: the whole-file fingerprint is mandatory.
+ */
+const requiredFingerprint = (value) => typeof (value) === "string" && value.length > 0 ? value : fail("invalid_arguments");
+/**
+ * Optional secondary range fingerprint.
+ */
+const optionalFingerprint = (value) => value === (void 0) ? (void 0) : requiredFingerprint(value);
+/**
+ * Encode line replacement content in the file's own charset without a BOM. A
+ * BOM belongs to the file, never to an inserted fragment.
+ */
+const encodeLineBody = (text, charset) => {
+    switch (charset) {
+        case "utf-8":
+        case "utf-8-bom": {
+            return new TextEncoder().encode(text);
+        }
+        case "utf-16le": {
+            return new Uint8Array(Buffer.from(text, "utf16le"));
+        }
+        case "utf-16be": {
+            const body = Buffer.from(text, "utf16le");
+            body.swap16();
+            return new Uint8Array(body);
+        }
+        case "latin1": {
+            return encodeText(text, "latin1");
+        }
+        default: {
+            return fail("charset_unsupported");
+        }
+    }
+};
+/**
+ * Replace one validated raw byte span in memory.
+ */
+const spliceBytes = (bytes, startByte, endByte, replacement) => {
+    const result = new Uint8Array(bytes.byteLength - (endByte - startByte) + replacement.byteLength);
+    result.set(bytes.subarray(0, startByte), 0);
+    result.set(replacement, startByte);
+    result.set(bytes.subarray(endByte), startByte + replacement.byteLength);
+    return result;
+};
+/**
+ * Build the node for already-known bytes plus a stat. Used by range patches so
+ * a committed write does not have to read and hash the file a third time.
+ */
+const fileNodeFromBytes = (rooted, bytes, stat, timeZone) => {
+    const detected = detectCharset(bytes);
+    let charset = detected.binary ? "binary" : detected.charset;
+    let lines = 0n;
+    if (charset !== "binary") {
+        try {
+            lines = countLines(decodeText(bytes, charset));
+        }
+        catch {
+            charset = "binary";
+            lines = 0n;
+        }
+    }
+    const described = describeFile(rooted.absolute, rooted.relative, charset, bytes);
+    return {
+        type: "File",
+        path: rooted.relative,
+        name: nameOfPath(rooted.relative),
+        extension: extensionOfPath(rooted.relative),
+        children: [],
+        fingerprint: rawDigest(bytes),
+        charset,
+        lines,
+        bytes: BigInt(bytes.byteLength),
+        create: formatNodeTime(creationTime(stat), timeZone),
+        modify: formatNodeTime(new Date(stat.mtimeMs), timeZone),
+        description: described.description,
+        summary: described.summary,
+        purpose: described.purpose,
+    };
+};
+/**
+ * Execute one patch while the path lock is held. The file must already exist;
+ * the whole-file fingerprint is checked first, then the optional range
+ * fingerprint, then the in-memory splice and the atomic rename.
+ */
+const patchLocked = (context, planner) => {
+    context.sandbox.revalidate(context.rooted);
+    const current = statIfExists(context.rooted.absolute);
+    if (current === (void 0)) {
+        return fail("not_found");
+    }
+    if (current.isSymbolicLink()) {
+        return fail("symlink_denied");
+    }
+    if (!current.isFile()) {
+        return fail("not_file");
+    }
+    if (current.size > MaxWriteBytes) {
+        return fail("quota_exceeded");
+    }
+    const bytes = readRegularFile(context.rooted.absolute);
+    if (bytes.byteLength > MaxWriteBytes) {
+        return fail("quota_exceeded");
+    }
+    const previousFingerprint = rawDigest(bytes);
+    if (previousFingerprint !== context.expectFingerprint) {
+        return fail("fingerprint_mismatch");
+    }
+    const plan = planner(bytes);
+    if (!Number.isSafeInteger(plan.startByte) || plan.startByte < 0 || !Number.isSafeInteger(plan.endByte) || plan.endByte < plan.startByte || plan.endByte > bytes.byteLength) {
+        return fail("invalid_arguments");
+    }
+    const previousRangeFingerprint = byteRangeFingerprint(plan.startByte, plan.endByte, bytes.subarray(plan.startByte, plan.endByte));
+    if (context.expectRangeFingerprint !== (void 0) && previousRangeFingerprint !== context.expectRangeFingerprint) {
+        return fail("fingerprint_mismatch");
+    }
+    const nextBytes = spliceBytes(bytes, plan.startByte, plan.endByte, plan.replacement);
+    if (nextBytes.byteLength > context.maxBytes) {
+        return fail("quota_exceeded");
+    }
+    const nextFingerprint = rawDigest(nextBytes);
+    const nextStartByte = plan.startByte;
+    const nextEndByte = plan.startByte + plan.replacement.byteLength;
+    const nextRangeFingerprint = byteRangeFingerprint(nextStartByte, nextEndByte, nextBytes.subarray(nextStartByte, nextEndByte));
+    const previousTotalBytes = BigInt(bytes.byteLength);
+    const nextTotalBytes = BigInt(nextBytes.byteLength);
+    const baseResult = {
+        node: fileNodeFromBytes(context.rooted, nextBytes, current, context.timeZone),
+        previousFingerprint,
+        created: false,
+        dryRun: context.dryRun,
+        bytesWritten: nextTotalBytes,
+        revision: nextFingerprint,
+        kind: context.kind,
+        startByte: plan.startByte,
+        endByte: plan.endByte,
+        startLine: plan.startLine,
+        endLine: plan.endLine,
+        previousRangeFingerprint,
+        nextRangeFingerprint,
+        nextStartByte,
+        nextEndByte,
+        previousTotalBytes,
+        nextTotalBytes,
+    };
+    if (context.dryRun) {
+        return { result: baseResult, journal: (void 0), patchJournal: (void 0), relative: context.rooted.relative };
+    }
+    context.sandbox.revalidate(context.rooted);
+    atomicWrite(context.rooted.absolute, nextBytes, current.mode & 0o777);
+    context.sandbox.revalidate(context.rooted);
+    const nextStat = statOrFail(context.rooted.absolute);
+    const node = fileNodeFromBytes(context.rooted, nextBytes, nextStat, context.timeZone);
+    const id = `w.${randomBytes(8).toString("hex")}`;
+    const at = formatIsoTime(new Date());
+    const journal = {
+        id,
+        sessionId: context.sessionId,
+        rootId: context.rooted.root.id,
+        path: context.rooted.relative,
+        mode: "overwrite",
+        previousFingerprint,
+        nextFingerprint,
+        bytes: nextTotalBytes,
+        at,
+    };
+    const patchJournal = {
+        ...journal,
+        kind: context.kind,
+        startByte: plan.startByte,
+        endByte: plan.endByte,
+        startLine: plan.startLine,
+        endLine: plan.endLine,
+        previousRangeFingerprint,
+        nextRangeFingerprint,
+        nextStartByte,
+        nextEndByte,
+        previousTotalBytes,
+        nextTotalBytes,
+    };
+    return { result: { ...baseResult, node, revision: node.fingerprint }, journal, patchJournal, relative: context.rooted.relative };
+};
+/**
+ * Publish the journal entries and refresh the tree after the lock is released.
+ * Journal callbacks must not run under the non-reentrant write lock: a callback
+ * that writes the same path would otherwise deadlock.
+ */
+const publishPatch = (commit, options) => {
+    if (commit.result.dryRun) {
+        return commit.result;
+    }
+    if (options.journal !== (void 0) && commit.journal !== (void 0)) {
+        options.journal(commit.journal);
+    }
+    if (options.patchJournal !== (void 0) && commit.patchJournal !== (void 0)) {
+        options.patchJournal(commit.patchJournal);
+    }
+    const tree = options.tree;
+    if (tree === (void 0)) {
+        return commit.result;
+    }
+    return { ...commit.result, revision: tree.refresh(commit.relative).revision };
+};
+/**
+ * Replace a raw byte range of an existing file.
+ *
+ * The whole-file `expectFingerprint` is mandatory and is verified from the bytes
+ * read under the lock; `expectRangeFingerprint` is a secondary check. The new
+ * file is assembled in memory, written through a same-directory temporary file,
+ * `fsync`ed and renamed, so a reader never observes a partial file.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and journal.
+ * @param request - Path, half-open byte range, replacement bytes and CAS guards.
+ * @param options - Size ceiling, journal sinks, tree and timestamp mode.
+ * @returns Patch result with both fingerprint pairs and the new node.
+ */
+export const useByte = async (sandbox, sessionId, request, options = {}) => {
+    if (typeof (sessionId) !== "string" || sessionId.length === 0 || sessionId.includes("\u0000")) {
+        return fail("invalid_arguments");
+    }
+    if (typeof (request) !== "object" || request === null) {
+        return fail("invalid_arguments");
+    }
+    const settings = options === (void 0) || options === null ? {} : options;
+    const expectFingerprint = requiredFingerprint(request.expectFingerprint);
+    const expectRangeFingerprint = optionalFingerprint(request.expectRangeFingerprint);
+    if (!(request.content instanceof Uint8Array)) {
+        return fail("invalid_arguments");
+    }
+    const replacement = new Uint8Array(request.content);
+    const startByte = patchByteOffset(request.startByte);
+    const endByte = patchByteOffset(request.endByte);
+    if (endByte < startByte) {
+        return fail("invalid_arguments");
+    }
+    const maxBytes = positiveInteger(settings.maxBytes, DefaultWriteBytes, MaxWriteBytes);
+    const rooted = sandbox.resolve(request.path, "write");
+    if (rooted.relative === ".") {
+        return fail("not_file");
+    }
+    const context = {
+        sandbox,
+        sessionId,
+        rooted,
+        kind: "byte",
+        expectFingerprint,
+        expectRangeFingerprint,
+        dryRun: request.dryRun === true,
+        maxBytes,
+        timeZone: settings.timeZone === "utc" ? "utc" : "local",
+    };
+    const planner = (bytes) => {
+        if (endByte > bytes.byteLength) {
+            return fail("invalid_arguments");
+        }
+        return { kind: "byte", startByte, endByte, replacement };
+    };
+    const lockName = `${sessionId}\u0000${rooted.root.id}\u0000${rooted.relative}`;
+    const commit = await WriteLockRegistry.run(lockName, () => patchLocked(context, planner)).catch((error) => mapFsError(error));
+    try {
+        return publishPatch(commit, settings);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+};
+/**
+ * Replace a line range of an existing text file.
+ *
+ * Line numbers are 1-based and inclusive. The replaced span starts at the first
+ * character of `startLine` and includes the terminator of `endLine` when one
+ * exists, which means `content` is inserted verbatim: include the desired
+ * newline when more lines follow. Use `endLine = startLine - 1` to insert.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param sessionId - Public session handle used for the lock and journal.
+ * @param request - Path, inclusive line range, replacement text and CAS guards.
+ * @param options - Size ceiling, journal sinks, tree and timestamp mode.
+ * @returns Patch result with both fingerprint pairs and the new node.
+ */
+export const useLine = async (sandbox, sessionId, request, options = {}) => {
+    if (typeof (sessionId) !== "string" || sessionId.length === 0 || sessionId.includes("\u0000")) {
+        return fail("invalid_arguments");
+    }
+    if (typeof (request) !== "object" || request === null) {
+        return fail("invalid_arguments");
+    }
+    const settings = options === (void 0) || options === null ? {} : options;
+    const expectFingerprint = requiredFingerprint(request.expectFingerprint);
+    const expectRangeFingerprint = optionalFingerprint(request.expectRangeFingerprint);
+    if (typeof (request.content) !== "string") {
+        return fail("invalid_arguments");
+    }
+    const content = request.content;
+    const startLine = patchStartLine(request.startLine);
+    const endLine = patchEndLine(request.endLine);
+    if (endLine < startLine - 1) {
+        return fail("invalid_arguments");
+    }
+    const maxBytes = positiveInteger(settings.maxBytes, DefaultWriteBytes, MaxWriteBytes);
+    const rooted = sandbox.resolve(request.path, "write");
+    if (rooted.relative === ".") {
+        return fail("not_file");
+    }
+    const context = {
+        sandbox,
+        sessionId,
+        rooted,
+        kind: "line",
+        expectFingerprint,
+        expectRangeFingerprint,
+        dryRun: request.dryRun === true,
+        maxBytes,
+        timeZone: settings.timeZone === "utc" ? "utc" : "local",
+    };
+    const planner = (bytes) => {
+        const span = locateLineSpan(bytes, startLine, endLine);
+        return {
+            kind: "line",
+            startByte: span.startByte,
+            endByte: span.endByte,
+            replacement: encodeLineBody(content, span.charset),
+            startLine,
+            endLine,
+        };
+    };
+    const lockName = `${sessionId}\u0000${rooted.root.id}\u0000${rooted.relative}`;
+    const commit = await WriteLockRegistry.run(lockName, () => patchLocked(context, planner)).catch((error) => mapFsError(error));
+    try {
+        return publishPatch(commit, settings);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+};
+/**
+ * Create a directory inside a root. `create` requires the parent to exist and
+ * fails when the target is already present; `ensure` creates the whole chain
+ * and treats an existing directory as success. The root itself is always a
+ * valid target for `ensure` and never for `create`.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param path - Root-relative POSIX directory path.
+ * @param mode - `create` or `ensure`; defaults to `ensure`.
+ * @returns The resolved path of the directory.
+ */
+export const ensureDirectory = (sandbox, path, mode = "ensure") => {
+    if (mode !== "create" && mode !== "ensure") {
+        return fail("invalid_arguments");
+    }
+    const rooted = sandbox.resolve(path, "create");
+    if (rooted.relative === ".") {
+        return rooted;
+    }
+    if (mode === "ensure") {
+        makeDirectoryChain(sandbox, rooted.root, rooted.relative);
+        sandbox.revalidate(rooted);
+        return rooted;
+    }
+    if (statIfExists(rooted.absolute) !== (void 0)) {
+        return fail("already_exists");
+    }
+    const parent = dirname(rooted.absolute);
+    if (!sandbox.contains(rooted.root.path, parent)) {
+        return fail("path_escape");
+    }
+    const parentStat = statOrFail(parent);
+    if (!parentStat.isDirectory()) {
+        return fail("not_directory");
+    }
+    try {
+        mkdirSync(rooted.absolute);
+    }
+    catch (error) {
+        return mapFsError(error);
+    }
+    sandbox.revalidate(rooted);
+    return rooted;
+};