humanish 0.107.0 → 0.109.0

package/dist/study/migrate.d.ts

@@ -0,0 +1,48 @@
+import type { StudyRoute } from "./routing.js";
+import { type DroppedKey, type MovedKey } from "./convert.js";
+/** The schema of `humanish migrate --json`. */
+declare const MIGRATE_SCHEMA = "humanish.migrate-result.v1";
+/** One file migrate looked at. Paths are relative to the project. */
+export interface MigrateFile {
+    readonly source: string;
+    /** `move` to a studies/ directory, `rewrite` in place, or `skip` a v3 file. */
+    readonly action: "move" | "rewrite" | "skip";
+    readonly destination?: string;
+    readonly route?: StudyRoute;
+    readonly moved: readonly MovedKey[];
+    readonly dropped: readonly DroppedKey[];
+}
+/** What migrate did, or would do with `--dry-run`. */
+export interface MigrateResult {
+    readonly schema: typeof MIGRATE_SCHEMA;
+    readonly ok: boolean;
+    readonly cwd: string;
+    readonly dryRun: boolean;
+    readonly files: readonly MigrateFile[];
+    /** Files left behind after a clean-up step found them changed: sources, backups or temp files. */
+    readonly unresolved?: readonly string[];
+    readonly error?: {
+        readonly code: "HUMANISH_MIGRATE_REFUSED" | "HUMANISH_MIGRATE_FAILED";
+        readonly phase: "plan" | "stage" | "commit" | "clean-up";
+        readonly file?: string;
+        readonly message: string;
+    };
+}
+/** How to run migrate. */
+export interface MigrateOptions {
+    readonly cwd: string;
+    /** Files to convert. Without any, the six study directories are scanned. */
+    readonly paths?: readonly string[];
+    readonly dryRun?: boolean;
+    /** Called with the plan before anything is written, so a caller can print every destination. */
+    readonly onPlan?: (files: readonly MigrateFile[]) => void;
+    /** Replaces `fs.link`. Tests use it to stand in for a filesystem without hard links. */
+    readonly link?: (from: string, to: string) => Promise<void>;
+    /** Called between stage and commit, and between commit and clean-up. Tests change files there. */
+    readonly onPhase?: (finished: "stage" | "commit") => void;
+    /** Called for each file after its last check and before its commit changes anything. Tests race it. */
+    readonly onCommit?: (source: string) => Promise<void> | void;
+}
+/** Convert the selected v2 study files to v3. */
+export declare function migrateStudies(options: MigrateOptions): Promise<MigrateResult>;
+export {};

package/dist/study/migrate.js

@@ -0,0 +1,408 @@
+// `humanish migrate`: convert humanish.lab.v2 study files to humanish.study.v3. A file under a
+// labs/ directory moves to the matching studies/ directory; any other file is rewritten in place.
+// It runs in four phases, and a phase that fails leaves every source file where it was:
+// 1. Plan: read, convert and plan-check every file, and record each source's identity. No writes.
+// 2. Stage: write each output to a new temp file beside its destination. A failure removes them.
+// 3. Commit: recheck each source. A rewritten source is first renamed to a random hidden name and
+//    checked there. Then the new file is linked into place, which fails if anything holds that
+//    name, so no file this run did not write is ever overwritten. A failure undoes the commits.
+// 4. Clean up: delete each moved source and each rewrite's original, once checked (owned-files.ts).
+//    A file that changed since the plan is kept and listed; a rewrite's original as <name>.v2.bak.
+import { randomUUID } from "node:crypto";
+import { link, lstat, readdir, readFile, realpath, rename, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { isNodeError } from "../run/type-guards.js";
+import { convertStudyText, isStudyV3 } from "./convert.js";
+import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "./files.js";
+import { assertDirectory, bindDirectory, exists, fileIdentity, NO_HARD_LINKS, removeChecked, removeOwned, restoreName, sameFile, sha256, writeOwned, } from "./owned-files.js";
+/** The schema of `humanish migrate --json`. */
+const MIGRATE_SCHEMA = "humanish.migrate-result.v1";
+class MigrateError extends Error {
+    phase;
+    file;
+    refused;
+    unresolved;
+    constructor(phase, file, message, refused = false, unresolved = []) {
+        super(message);
+        this.phase = phase;
+        this.file = file;
+        this.refused = refused;
+        this.unresolved = unresolved;
+    }
+}
+const LABS_TO_STUDIES = new Map(STUDY_DIRECTORIES.filter((directory) => directory.family === "labs").map((directory) => [
+    directory.relativeDir,
+    directory.relativeDir.replace(/labs$/, "studies"),
+]));
+async function scanTargets(root) {
+    const found = [];
+    for (const directory of STUDY_DIRECTORIES) {
+        const bound = await bindDirectory(root, directory.relativeDir);
+        if (bound === undefined)
+            continue;
+        for (const name of (await readdir(bound.physicalPath)).sort()) {
+            if (studyFileStem(name) !== undefined)
+                found.push(path.join(directory.relativeDir, name));
+        }
+    }
+    return found;
+}
+async function givenTargets(root, paths) {
+    const seen = new Map();
+    for (const given of paths) {
+        const absolute = path.resolve(root, given);
+        const relative = path.relative(root, absolute);
+        if (relative.startsWith("..") || path.isAbsolute(relative))
+            throw new MigrateError("plan", given, `${given} is outside the project.`, true);
+        let real;
+        try {
+            real = await realpath(absolute);
+        }
+        catch {
+            throw new MigrateError("plan", given, `${given} does not exist.`, true);
+        }
+        if (!seen.has(real))
+            seen.set(real, relative);
+    }
+    return [...seen.values()];
+}
+async function planWrites(root, options) {
+    const targets = options.paths && options.paths.length > 0
+        ? await givenTargets(root, options.paths)
+        : await scanTargets(root);
+    const files = [];
+    const writes = [];
+    for (const source of targets) {
+        const sourcePath = path.join(root, source);
+        let sourceDirectory;
+        let identity;
+        let mode;
+        let bytes;
+        try {
+            sourceDirectory = await bindDirectory(root, path.dirname(source));
+            if (sourceDirectory === undefined)
+                throw new Error("its directory is missing");
+            identity = await fileIdentity(sourcePath);
+            mode = Number((await lstat(sourcePath)).mode & 0o777);
+            bytes = await readFile(sourcePath);
+            if (sha256(bytes) !== identity.sha256)
+                throw new Error("it changed while it was read");
+        }
+        catch (error) {
+            throw new MigrateError("plan", source, `${source}: ${error.message}.`, true);
+        }
+        const text = bytes.toString("utf8");
+        if (isStudyV3(parseDocument(text).toJS())) {
+            files.push({ source, action: "skip", moved: [], dropped: [] });
+            continue;
+        }
+        const converted = convertStudyText(text, root);
+        if (!converted.ok)
+            throw new MigrateError("plan", source, `${source} was not converted: ${converted.reason}`, true);
+        const studiesDir = LABS_TO_STUDIES.get(path.dirname(source));
+        const destination = studiesDir === undefined ? source : path.join(studiesDir, path.basename(source));
+        const file = {
+            source,
+            action: studiesDir === undefined ? "rewrite" : "move",
+            destination,
+            route: converted.conversion.route,
+            moved: converted.conversion.moved,
+            dropped: converted.conversion.dropped,
+        };
+        files.push(file);
+        writes.push({
+            file,
+            sourcePath,
+            sourceDirectory: sourceDirectory,
+            sourceIdentity: identity,
+            sourceMode: mode,
+            destinationPath: path.join(root, destination),
+            asidePath: path.join(path.dirname(sourcePath), `.${path.basename(sourcePath)}.migrate-${randomUUID()}.orig`),
+            backupPath: `${sourcePath}.v2.bak`,
+            text: converted.conversion.text,
+            expected: sha256(Buffer.from(converted.conversion.text)),
+        });
+    }
+    await refuseCollisions(root, writes);
+    return { files, writes };
+}
+// A destination two files share, or a name another file already uses, would leave discovery two
+// files for one study. Files that move together are not collisions with each other.
+async function refuseCollisions(root, writes) {
+    const sources = new Set(writes.map((write) => write.file.source));
+    const destinations = new Map();
+    for (const write of writes) {
+        const destination = write.file.destination;
+        const stem = studyFileStem(path.basename(destination));
+        // A file without a study extension has no stem, so only its exact path can collide.
+        const sameStem = stem === undefined
+            ? undefined
+            : [...destinations.entries()].find(([other]) => path.dirname(other) === path.dirname(destination) &&
+                studyFileStem(path.basename(other)) === stem);
+        if (destinations.has(destination) || sameStem) {
+            const other = destinations.get(destination) ?? sameStem[1];
+            const clash = destinations.has(destination)
+                ? `would both become ${destination}`
+                : `would share the name ${studyFileStem(path.basename(destination))} in ${path.dirname(destination)}`;
+            throw new MigrateError("plan", write.file.source, `${write.file.source} and ${other} ${clash}. Remove one, then migrate.`, true);
+        }
+        destinations.set(destination, write.file.source);
+        const others = await collisions(root, write, sources);
+        const blocking = write.file.action === "move" && (await exists(write.destinationPath))
+            ? [write.file.destination, ...others]
+            : others;
+        if (blocking.length > 0) {
+            throw new MigrateError("plan", write.file.source, `${write.file.source} and ${blocking[0]} share the name ${stem ?? path.basename(destination)}. Keep one, then migrate.`, true);
+        }
+    }
+}
+async function stage(root, writes, created) {
+    for (const write of writes) {
+        try {
+            write.destinationDirectory = await bindDirectory(root, path.dirname(write.file.destination), created);
+            write.temp = {
+                path: path.join(path.dirname(write.destinationPath), `.${path.basename(write.destinationPath)}.migrate-${randomUUID()}.tmp`),
+            };
+            await writeOwned(write.temp, write.text, write.sourceMode);
+        }
+        catch (error) {
+            throw new MigrateError("stage", write.file.source, `${write.file.source}: ${error.message}.`);
+        }
+    }
+}
+// After a failed stage or commit: remove each temp file. One this run did not write, or that
+// changed, is kept and listed.
+async function unstage(root, writes, created, linkFile) {
+    const kept = [];
+    for (const write of writes) {
+        if (write.temp === undefined)
+            continue;
+        const left = await removeOwned(write.temp, linkFile).catch(() => write.temp.path);
+        if (left !== undefined)
+            kept.push(path.relative(root, left));
+    }
+    for (const directory of [...created].reverse())
+        await rmdir(directory).catch(() => undefined);
+    return kept;
+}
+// Put the staged file at its destination without replacing anything there.
+async function placeNew(root, write, linkFile) {
+    const taken = () => new Error(`${path.relative(root, write.destinationPath)} appeared while ${write.file.source} was migrated; both are kept`);
+    try {
+        await linkFile(write.temp.path, write.destinationPath);
+        // The temp file's name goes once every file is committed (commit), checked like any removal.
+        write.committed = write.temp.identity;
+        return;
+    }
+    catch (error) {
+        if (write.committed !== undefined)
+            throw error;
+        if (isNodeError(error) && error.code === "EEXIST")
+            throw taken();
+        if (!(isNodeError(error) && NO_HARD_LINKS.has(error.code ?? "")))
+            throw error;
+        const copy = { path: write.destinationPath };
+        try {
+            await writeOwned(copy, write.text, write.sourceMode);
+        }
+        catch (copyError) {
+            if (copy.inode === undefined && isNodeError(copyError) && copyError.code === "EEXIST")
+                throw taken();
+            // A copy this run created but could not finish or read back is removed, if it is unchanged.
+            if (copy.inode !== undefined)
+                await removeOwned(copy, linkFile).catch(() => undefined);
+            throw copyError;
+        }
+        write.committed = copy.identity;
+    }
+}
+// Every name that would collide with this write's destination, other than the files this run moves
+// or writes. Checked at plan time and again just before each commit.
+async function collisions(root, write, ours) {
+    if (!STUDY_DIRECTORIES.some((directory) => directory.relativeDir === path.dirname(write.file.destination)))
+        return [];
+    // Discovery reads only .yaml and .yml files, so a file without that extension shares no name.
+    const stem = studyFileStem(path.basename(write.file.destination));
+    if (stem === undefined)
+        return [];
+    return (await otherStudyFiles(stem, (candidate) => exists(path.join(root, candidate)), write.file.source)).filter((other) => !ours.has(other));
+}
+// Move a rewrite's source to its aside name, then check that the file moved is the one the plan
+// read. An edit saved in between is given its name back, never overwritten.
+async function moveAside(write, linkFile) {
+    await rename(write.sourcePath, write.asidePath);
+    write.movedAside = true;
+    const moved = await fileIdentity(write.asidePath).catch(() => undefined);
+    if (moved !== undefined && sameFile(moved, write.sourceIdentity))
+        return;
+    if (await restoreName(write.asidePath, write.sourcePath, linkFile))
+        write.movedAside = false;
+    throw new Error(`${write.file.source} changed after it was planned`);
+}
+// A rewrite's source that cannot get its name back is kept as <name>.v2.bak, or under its aside
+// name when that is taken too. Returns where it is.
+async function keepOriginal(write, linkFile) {
+    const kept = (await restoreName(write.asidePath, write.backupPath, linkFile).catch(() => false))
+        ? write.backupPath
+        : write.asidePath;
+    write.movedAside = false;
+    return kept;
+}
+async function commit(root, writes, linkFile, onCommit) {
+    const ours = new Set(writes.flatMap((write) => [write.file.source, write.file.destination]));
+    try {
+        for (const write of writes) {
+            await assertDirectory(write.sourceDirectory, root);
+            await assertDirectory(write.destinationDirectory, root);
+            if (!sameFile(await fileIdentity(write.temp.path, true), write.temp.identity))
+                throw new Error(`the staged copy of ${write.file.source} changed`);
+            const other = (await collisions(root, write, ours))[0];
+            if (other !== undefined)
+                throw new Error(`${other} appeared with the name of ${write.file.destination}`);
+            if (!sameFile(await fileIdentity(write.sourcePath), write.sourceIdentity))
+                throw new Error(`${write.file.source} changed after it was planned`);
+            await onCommit?.(write.file.source);
+            if (write.file.action === "rewrite")
+                await moveAside(write, linkFile);
+            await placeNew(root, write, linkFile);
+        }
+        for (const write of writes) {
+            if (write.temp === undefined)
+                continue;
+            write.leftover = await removeOwned(write.temp, linkFile).catch(() => write.temp.path);
+            write.temp = undefined;
+        }
+    }
+    catch (error) {
+        const unrestored = await undoCommits(root, writes, linkFile);
+        throw new MigrateError("commit", undefined, unrestored.length === 0
+            ? `${error.message}. Every source is where it was.`
+            : `${error.message}. These files could not be put back: ${unrestored.join(", ")}.`, false, unrestored);
+    }
+}
+// Undo each commit, last first: remove each new file that is still the one this run wrote, and give
+// each rewritten source its name back. A name another file now holds is left alone, and the source
+// is kept beside it. One failure does not stop the rest. Returns the paths it could not put back.
+async function undoCommits(root, writes, linkFile) {
+    const unrestored = [];
+    const keep = (file) => unrestored.push(path.relative(root, file));
+    for (const write of [...writes].reverse()) {
+        try {
+            const committed = write.committed;
+            if (committed !== undefined) {
+                const kept = await removeChecked(write.destinationPath, (current) => sameFile(current, committed), linkFile);
+                write.committed = undefined;
+                if (kept !== undefined) {
+                    keep(kept);
+                    if (write.movedAside === true)
+                        keep(await keepOriginal(write, linkFile));
+                    continue;
+                }
+            }
+            if (write.movedAside !== true)
+                continue;
+            if (await restoreName(write.asidePath, write.sourcePath, linkFile))
+                write.movedAside = false;
+            else
+                keep(await keepOriginal(write, linkFile));
+        }
+        catch {
+            keep(write.committed !== undefined
+                ? write.destinationPath
+                : write.movedAside === true
+                    ? write.asidePath
+                    : write.sourcePath);
+        }
+    }
+    return unrestored;
+}
+// Delete each moved source and each rewrite's original, but only once the v3 file is in place as
+// written, and only if the old file is still the one the plan read (removeChecked). Anything kept
+// is listed; a rewrite's original is kept as <name>.v2.bak.
+async function cleanUp(root, writes, linkFile) {
+    const unresolved = [];
+    for (const write of writes) {
+        if (write.leftover !== undefined)
+            unresolved.push(path.relative(root, write.leftover));
+        const old = write.file.action === "move" ? write.sourcePath : write.asidePath;
+        let kept = old;
+        try {
+            const placed = await fileIdentity(write.destinationPath, true);
+            if (!sameFile(placed, write.committed))
+                throw new Error("the new file changed");
+            await assertDirectory(write.sourceDirectory, root);
+            // A rename keeps the inode, so a rewrite's original still has its source's identity.
+            kept = await removeChecked(old, (current) => sameFile(current, write.sourceIdentity), linkFile);
+        }
+        catch {
+            kept = old;
+        }
+        if (kept === undefined)
+            continue;
+        if (kept === write.asidePath)
+            kept = await keepOriginal(write, linkFile);
+        unresolved.push(path.relative(root, kept));
+    }
+    return unresolved;
+}
+/** Convert the selected v2 study files to v3. */
+export async function migrateStudies(options) {
+    const root = await realpath(path.resolve(options.cwd)).catch(() => path.resolve(options.cwd));
+    const base = { schema: MIGRATE_SCHEMA, cwd: root, dryRun: options.dryRun === true };
+    let files = [];
+    const created = [];
+    let writes = [];
+    const linkFile = options.link ?? link;
+    try {
+        ({ files, writes } = await planWrites(root, options));
+        options.onPlan?.(files);
+        if (options.dryRun === true || writes.length === 0)
+            return { ...base, ok: true, files };
+        try {
+            await stage(root, writes, created);
+            options.onPhase?.("stage");
+            await commit(root, writes, linkFile, options.onCommit);
+        }
+        catch (error) {
+            const kept = await unstage(root, writes, created, linkFile);
+            if (kept.length > 0 && error instanceof MigrateError) {
+                throw new MigrateError(error.phase, error.file, `${error.message} Kept for you to check: ${kept.join(", ")}.`, error.refused, [...error.unresolved, ...kept]);
+            }
+            throw error;
+        }
+        options.onPhase?.("commit");
+        const unresolved = await cleanUp(root, writes, linkFile);
+        if (unresolved.length > 0) {
+            return {
+                ...base,
+                ok: false,
+                files,
+                unresolved,
+                error: {
+                    code: "HUMANISH_MIGRATE_FAILED",
+                    phase: "clean-up",
+                    message: `Every study was written, but these files changed since the plan and were kept: ${unresolved.join(", ")}. Check them, then delete them.`,
+                },
+            };
+        }
+        return { ...base, ok: true, files };
+    }
+    catch (error) {
+        const failure = error instanceof MigrateError
+            ? error
+            : new MigrateError("plan", undefined, error.message);
+        return {
+            ...base,
+            ok: false,
+            files,
+            ...(failure.unresolved.length === 0 ? {} : { unresolved: failure.unresolved }),
+            error: {
+                code: failure.refused ? "HUMANISH_MIGRATE_REFUSED" : "HUMANISH_MIGRATE_FAILED",
+                phase: failure.phase,
+                ...(failure.file === undefined ? {} : { file: failure.file }),
+                message: failure.message,
+            },
+        };
+    }
+}

package/dist/study/owned-files.d.ts

@@ -0,0 +1,38 @@
+export interface FileIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly size: bigint;
+    readonly sha256: string;
+}
+export interface DirectoryIdentity {
+    readonly physicalPath: string;
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+interface Inode {
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+/**
+ * A file this run creates. `inode` is set the moment the exclusive create succeeds, so a name that
+ * was already taken is never treated as this run's. `identity` is set once the bytes are written
+ * and read back through the same descriptor.
+ */
+export interface OwnedFile {
+    readonly path: string;
+    inode?: Inode | undefined;
+    identity?: FileIdentity | undefined;
+}
+export type LinkFile = (from: string, to: string) => Promise<void>;
+export declare function sha256(bytes: Buffer): string;
+export declare function fileIdentity(absolutePath: string, ours?: boolean): Promise<FileIdentity>;
+export declare function sameFile(left: FileIdentity, right: FileIdentity): boolean;
+export declare function bindDirectory(root: string, relativeDir: string, created?: string[]): Promise<DirectoryIdentity | undefined>;
+export declare function assertDirectory(directory: DirectoryIdentity, root: string): Promise<void>;
+export declare function exists(absolutePath: string): Promise<boolean>;
+export declare function writeOwned(owned: OwnedFile, bytes: Buffer | string, mode: number): Promise<void>;
+export declare function removeChecked(file: string, matches: (current: FileIdentity) => boolean, linkFile: LinkFile): Promise<string | undefined>;
+export declare function removeOwned(owned: OwnedFile, linkFile: LinkFile): Promise<string | undefined>;
+export declare const NO_HARD_LINKS: Set<string>;
+export declare function restoreName(from: string, to: string, linkFile: LinkFile): Promise<boolean>;
+export {};

package/dist/study/owned-files.js

@@ -0,0 +1,182 @@
+// File operations for humanish migrate that never replace or delete a file the run did not create.
+// A new name is taken with an exclusive create or link(), which fail when the name is in use. A
+// file is removed by renaming it to a random name first and checking it there, so a file saved over
+// the name in the meantime keeps it.
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { isNodeError } from "../run/type-guards.js";
+export function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// A source must be a single-link regular file. A file this run wrote may briefly have two links
+// while a move is committed, so `ours` relaxes that.
+export async function fileIdentity(absolutePath, ours = false) {
+    const stats = await lstat(absolutePath, { bigint: true });
+    if (!stats.isFile() || (!ours && stats.nlink !== 1n))
+        throw new Error("not a single-link regular file");
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        size: stats.size,
+        sha256: sha256(await readFile(absolutePath)),
+    };
+}
+export function sameFile(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.sha256 === right.sha256);
+}
+// Walk a directory below the project root one segment at a time, refusing a symbolic link or a
+// non-directory. `create` makes missing segments and records each one it made.
+export async function bindDirectory(root, relativeDir, created) {
+    let current = root;
+    for (const segment of relativeDir.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = await lstat(current, { bigint: true });
+        }
+        catch (error) {
+            if (!(isNodeError(error) && error.code === "ENOENT") || created === undefined) {
+                if (isNodeError(error) && error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            }
+            await mkdir(current, { mode: 0o755 });
+            created.push(current);
+            stats = await lstat(current, { bigint: true });
+        }
+        if (stats.isSymbolicLink() || !stats.isDirectory())
+            throw new Error(`${path.relative(root, current)} is not a plain directory`);
+    }
+    const stats = await lstat(current, { bigint: true });
+    return { physicalPath: current, dev: stats.dev, ino: stats.ino };
+}
+export async function assertDirectory(directory, root) {
+    const again = await bindDirectory(root, path.relative(root, directory.physicalPath));
+    if (again === undefined || again.dev !== directory.dev || again.ino !== directory.ino)
+        throw new Error(`${path.relative(root, directory.physicalPath)} changed`);
+}
+export async function exists(absolutePath) {
+    try {
+        await lstat(absolutePath);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        return true;
+    }
+}
+// Create a file exclusively and write it. Its inode is recorded the moment the create succeeds, so
+// a failed write is still known to be this run's and a taken name never is. The bytes are read back
+// through the same descriptor, so the identity recorded is this file's, whatever holds the name.
+export async function writeOwned(owned, bytes, mode) {
+    const data = Buffer.from(bytes);
+    const handle = await open(owned.path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, mode);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        owned.inode = { dev: opened.dev, ino: opened.ino };
+        await handle.writeFile(data);
+        await handle.sync();
+        const stats = await handle.stat({ bigint: true });
+        const back = Buffer.alloc(Number(stats.size));
+        await handle.read(back, 0, back.length, 0);
+        owned.identity = { dev: stats.dev, ino: stats.ino, size: stats.size, sha256: sha256(back) };
+    }
+    finally {
+        await handle.close();
+    }
+    if (owned.identity.sha256 !== sha256(data))
+        throw new Error(`${path.basename(owned.path)} did not read back as written`);
+}
+// Remove the file at `file` only if `matches` says it is the expected one. The name is first renamed
+// to a random one and the file checked there, so a file saved over the name in between is never
+// deleted: it gets its name back, or keeps the random one. Returns the path kept, or undefined once
+// the file is removed or was already gone.
+export async function removeChecked(file, matches, linkFile) {
+    const aside = `${file}.migrate-${randomUUID()}.del`;
+    try {
+        await rename(file, aside);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const current = await fileIdentity(aside, true).catch(() => undefined);
+    if (current !== undefined && matches(current)) {
+        await unlink(aside);
+        return undefined;
+    }
+    return (await restoreName(aside, file, linkFile)) ? file : aside;
+}
+// Remove a file this run created if it still holds this run's bytes, or was cut short while being
+// written. Returns the path kept, if any.
+export async function removeOwned(owned, linkFile) {
+    const inode = owned.inode;
+    if (inode === undefined)
+        return undefined;
+    return removeChecked(owned.path, (current) => current.dev === inode.dev &&
+        current.ino === inode.ino &&
+        (owned.identity === undefined || sameFile(current, owned.identity)), linkFile);
+}
+// Hard links need filesystem support. Without it a file is created exclusively and read back.
+export const NO_HARD_LINKS = new Set(["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV"]);
+// Give the file at `from` the name `to` without replacing anything there: link() fails on a taken
+// name, and so does the exclusive create a filesystem without hard links gets instead. True once
+// `to` holds the file and `from` is gone. False when `to` was taken, or was replaced before `from`
+// could go, which leaves `from` as the file's only name.
+export async function restoreName(from, to, linkFile) {
+    let placed;
+    let copied;
+    let owned;
+    try {
+        await linkFile(from, to);
+        const stats = await lstat(from, { bigint: true });
+        placed = { dev: stats.dev, ino: stats.ino };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST")
+            return false;
+        if (!(isNodeError(error) && NO_HARD_LINKS.has(error.code ?? "")))
+            throw error;
+        // Without hard links the file is copied. What was copied is recorded, so an edit made to
+        // `from` during the copy keeps `from`.
+        const stats = await lstat(from, { bigint: true });
+        // Only a regular file is copied; anything else keeps the name it has.
+        if (!stats.isFile())
+            return false;
+        const bytes = await readFile(from);
+        copied = { dev: stats.dev, ino: stats.ino, size: BigInt(bytes.length), sha256: sha256(bytes) };
+        const copy = { path: to };
+        try {
+            await writeOwned(copy, bytes, Number(stats.mode & 511n));
+        }
+        catch (copyError) {
+            if (copy.inode === undefined && isNodeError(copyError) && copyError.code === "EEXIST")
+                return false;
+            if (copy.inode !== undefined)
+                await removeOwned(copy, linkFile).catch(() => undefined);
+            throw copyError;
+        }
+        placed = copy.inode;
+        owned = copy;
+    }
+    const now = await lstat(to, { bigint: true }).catch(() => undefined);
+    if (now === undefined || now.dev !== placed.dev || now.ino !== placed.ino)
+        return false;
+    if (copied === undefined) {
+        await unlink(from);
+        return true;
+    }
+    const expected = copied;
+    if ((await removeChecked(from, (current) => sameFile(current, expected), linkFile)) === undefined)
+        return true;
+    // `from` changed during the copy: it stays, and the stale copy goes.
+    await removeOwned(owned, linkFile).catch(() => undefined);
+    return false;
+}