@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/quarantine/pathQuarantine.js

@@ -0,0 +1,504 @@
+import { join } from 'node:path';
+import { errorMessage } from '../core/errors/errorMessage.js';
+import { parseQuarantineMemento } from '../core/state/stateGuards.js';
+export const QUARANTINE_FILE_NAME = 'quarantine.json';
+/** Temp files of restored worktree paths, outside the tree so a crash cannot leave one to be committed. */
+export const QUARANTINE_TEMP_DIR_NAME = 'tmp';
+/** The inputs of a merge at restore (Decisions 94, 99), in the temp directory; one restore runs at a time, under the instance lock. */
+const MERGE_BASE_FILE_NAME = 'quarantine-merge-base';
+const MERGE_HELD_FILE_NAME = 'quarantine-merge-held';
+const MERGE_HEAD_FILE_NAME = 'quarantine-merge-head';
+/** The version a restore writes, flushed before the swap, and the second name of the file it replaces (Decision 117). */
+const STAGED_FILE_NAME = 'quarantine-staged';
+const PREVIOUS_FILE_NAME = 'quarantine-previous';
+/** How often a restore judges an entry again when the file changed between its decision and its write. */
+export const MAX_RESTORE_REJUDGES = 2;
+/** What observe reads for an absent path, and for one that is not a regular file; never a blob id. */
+const OBSERVED_ABSENT = 'absent';
+const OBSERVED_OTHER = 'not a regular file';
+function isRegularFile(observed) {
+    return observed !== OBSERVED_ABSENT && observed !== OBSERVED_OTHER;
+}
+const RESTORED = { kind: 'restored', overwritten: null };
+/** The last entry per path: a later capture (extend) supersedes an earlier hold. */
+function latestEntryByPath(entries) {
+    const latest = new Map();
+    for (const entry of entries) {
+        latest.set(entry.path, entry);
+    }
+    return latest;
+}
+/**
+ * Service and Memento caretaker (D4): holds tracked paths that are still
+ * dirty after the commit step aside for the duration of a rebase, without a
+ * stash, and captures writes that land while enmetu's rebase is stopped
+ * before the abort resets them (Decision 45). The memento
+ * (<stateDir>/quarantine.json) is persisted before the tree changes and
+ * removed only after every entry was handled.
+ */
+export class PathQuarantine {
+    git;
+    writer;
+    fs;
+    paths;
+    constructor(git, writer, fs, paths) {
+        this.git = git;
+        this.writer = writer;
+        this.fs = fs;
+        this.paths = paths;
+    }
+    async hold(paths) {
+        // --- Step 1: never overwrite an earlier hold ---
+        if (await this.hasPending()) {
+            return { kind: 'pending' };
+        }
+        // An empty pathspec list must never reach restoreFromIndex: there is
+        // nothing to hold, so nothing is written either.
+        if (paths.length === 0) {
+            return { kind: 'held', count: 0 };
+        }
+        // --- Step 2: refuse what cannot be held byte for byte, before touching anything ---
+        const inspected = await this.inspect(paths);
+        if (inspected.kind === 'unsupported') {
+            return inspected;
+        }
+        // --- Step 3: store every held file's raw bytes in the object store ---
+        const entries = await this.storeEntries(inspected.files);
+        // --- Step 4: persist the memento before the tree changes ---
+        // A crash after this line leaves a record the next cycle restores from.
+        await this.writeMemento({ version: 1, entries });
+        // --- Step 5: a file written since step 3 is stored again (Decision 114) ---
+        await this.storeAgainIfWritten(entries, []);
+        // --- Step 6: the held paths now match the index, so the rebase may run ---
+        await this.writer.restoreFromIndex(paths);
+        return { kind: 'held', count: entries.length };
+    }
+    async extend(paths) {
+        // --- Step 1: nothing captured, nothing written ---
+        if (paths.length === 0) {
+            return { kind: 'held', count: 0 };
+        }
+        // --- Step 2: the entries already held; an unreadable memento is never overwritten ---
+        const text = await this.fs.readText(this.mementoPath());
+        let earlier = [];
+        if (text !== null) {
+            const memento = parseQuarantineMemento(text);
+            if (memento === null) {
+                return { kind: 'pending' };
+            }
+            earlier = memento.entries;
+        }
+        // --- Step 3: refuse what cannot be held byte for byte, before touching anything ---
+        const inspected = await this.inspect(paths);
+        if (inspected.kind === 'unsupported') {
+            return inspected;
+        }
+        // --- Step 4: store every captured file's raw bytes in the object store ---
+        const entries = await this.storeEntries(inspected.files);
+        // --- Step 5: append and persist before the tree changes ---
+        // A path held earlier keeps its older entry: restore writes the later one
+        // and lists the older blob in kept, so neither version goes unrecorded.
+        await this.writeMemento({ version: 1, entries: [...earlier, ...entries] });
+        // --- Step 6: a file written since step 4 is stored again (Decision 114) ---
+        await this.storeAgainIfWritten(entries, earlier);
+        // --- Step 7: the captured paths now match the index ---
+        await this.writer.restoreFromIndex(paths);
+        return { kind: 'held', count: entries.length };
+    }
+    /**
+     * git's checkout writes the index's version over a file whatever the file
+     * holds, so a write that landed after storeEntries read it would be gone
+     * without a record. Each file is read once more right before the checkout;
+     * one whose bytes changed (or that appeared or went) is stored again and the
+     * memento rewritten first (design 13.11, Decision 114). What stays open is
+     * the time between this read and git's own write, the few milliseconds of
+     * one spawn. A path that is no longer a regular file keeps its entry.
+     */
+    async storeAgainIfWritten(entries, earlier) {
+        const written = [];
+        for (const entry of entries) {
+            const target = join(this.paths.root, entry.path);
+            const seen = await this.observe(entry.path, target);
+            if (seen === OBSERVED_OTHER ||
+                seen === (entry.blobId ?? OBSERVED_ABSENT)) {
+                continue;
+            }
+            const facts = await this.fs.facts(target);
+            if (facts === null || facts.kind === 'file') {
+                written.push({ path: entry.path, facts });
+            }
+        }
+        if (written.length === 0) {
+            return;
+        }
+        const stored = new Map((await this.storeEntries(written)).map((entry) => [entry.path, entry]));
+        await this.writeMemento({
+            version: 1,
+            entries: [
+                ...earlier,
+                ...entries.map((entry) => stored.get(entry.path) ?? entry),
+            ],
+        });
+    }
+    async restore() {
+        try {
+            // --- Step 1: nothing pending ---
+            const text = await this.fs.readText(this.mementoPath());
+            if (text === null) {
+                return { kind: 'nothing' };
+            }
+            const memento = parseQuarantineMemento(text);
+            if (memento === null) {
+                // Kept in place: the blobs it names are the only pointer to the held bytes.
+                return {
+                    kind: 'failed',
+                    detail: `the quarantine memento ${this.mementoPath()} cannot be parsed`,
+                };
+            }
+            // --- Step 2: every entry, one at a time ---
+            let count = 0;
+            const kept = [];
+            const changedUnderHold = [];
+            const overwritten = [];
+            const latest = latestEntryByPath(memento.entries);
+            const reported = new Set();
+            for (const entry of memento.entries) {
+                const last = latest.get(entry.path);
+                if (last !== entry) {
+                    // Superseded by a later capture of the same path: the later bytes
+                    // win, and an older version that differs is reported by its blob.
+                    const key = `${entry.path}\0${entry.blobId ?? ''}`;
+                    if (entry.blobId !== null &&
+                        entry.blobId !== last?.blobId &&
+                        !reported.has(key)) {
+                        reported.add(key);
+                        kept.push({ path: entry.path, blobId: entry.blobId });
+                    }
+                    continue;
+                }
+                const outcome = await this.restoreEntry(entry);
+                if (outcome.kind === 'kept') {
+                    kept.push(outcome.blob);
+                }
+                else if (outcome.kind !== 'left') {
+                    count += 1;
+                    if (outcome.kind === 'restored-over-change') {
+                        changedUnderHold.push(entry.path);
+                    }
+                    if (outcome.overwritten !== null) {
+                        overwritten.push(outcome.overwritten);
+                    }
+                }
+            }
+            // --- Step 3: only now is the memento no longer needed ---
+            await this.fs.remove(this.mementoPath());
+            return { kind: 'restored', count, kept, changedUnderHold, overwritten };
+        }
+        catch (error) {
+            // --- Step 4: the memento stays, so a later restore can finish the job ---
+            return {
+                kind: 'failed',
+                detail: errorMessage(error),
+            };
+        }
+    }
+    async hasPending() {
+        // An unparseable memento still counts: ignoring it would let a new hold
+        // overwrite the only record of held bytes.
+        return (await this.fs.readText(this.mementoPath())) !== null;
+    }
+    /**
+     * "Written during the hold" is judged by the working tree alone: the held
+     * version goes back when the file still holds what enmetu left there. The
+     * index is never the judge, because a person may stage the held path during
+     * the hold (git add, git apply --cached) without touching the file, and
+     * keeping the held bytes aside then would take the unstaged part off disk.
+     */
+    async restoreEntry(entry, attempt = 0) {
+        const target = join(this.paths.root, entry.path);
+        // The file is read before the status that decides, so every write-back
+        // checks against bytes the decision covers. Read after a clean status, a
+        // person's write landing in between (a partial commit's two hunks, the
+        // first staged) would pass for what enmetu left and be overwritten with
+        // the held version, the unstaged hunk lost.
+        const facts = await this.fs.facts(target);
+        const raw = facts?.kind === 'file' ? await this.git.hashFile(entry.path) : null;
+        const seen = facts === null ? OBSERVED_ABSENT : (raw ?? OBSERVED_OTHER);
+        // A clean status means the file equals HEAD's version through git's own
+        // filters, which is what the rebase or its abort left: the common case.
+        if ((await this.git.status([entry.path])).length === 0) {
+            return this.putBackOnHead(entry, target, seen, attempt);
+        }
+        if (facts?.kind !== 'file' || raw === null) {
+            // Absent while HEAD or the index has the path, or no longer a file: a
+            // deletion or a replacement during the window wins, and an entry with
+            // bytes keeps them in a blob.
+            return entry.blobId === null
+                ? facts === null
+                    ? RESTORED
+                    : { kind: 'left' }
+                : { kind: 'kept', blob: { path: entry.path, blobId: entry.blobId } };
+        }
+        if (entry.blobId !== null && raw === entry.blobId) {
+            // A previous restore wrote this file and stopped before the memento went.
+            return RESTORED;
+        }
+        const filtered = await this.git.worktreeBlobId(entry.path);
+        if (await this.stillAsLeft(entry, filtered)) {
+            return this.putBackOnHead(entry, target, raw, attempt);
+        }
+        if (entry.blobId === null) {
+            // Written during the window while held for a deletion: the write wins.
+            return { kind: 'left' };
+        }
+        // Written during the window (an editor that reloaded the held file and
+        // saved on top of it): both edits survive when they merge cleanly onto
+        // what the hold left, the common ancestor of both (Decision 94). Only
+        // where no filter applies, so the three inputs are the same kind of bytes.
+        if (entry.heldOver !== null && raw === filtered) {
+            const merged = await this.mergeHeld(target, entry.heldOver, entry.blobId);
+            // A write after the merge read the file wins: it is never overwritten.
+            if (merged !== null) {
+                const written = await this.writeOver(entry, target, raw, merged, facts.executable);
+                if (written.kind === 'written') {
+                    return { kind: 'restored', overwritten: written.overwritten };
+                }
+            }
+        }
+        return { kind: 'kept', blob: { path: entry.path, blobId: entry.blobId } };
+    }
+    /** The file holds what the hold's checkout wrote, or HEAD's version (what a rebase or its abort wrote). */
+    async stillAsLeft(entry, current) {
+        if (entry.heldOver !== null && current === entry.heldOver) {
+            return true;
+        }
+        const head = await this.git.headCommit();
+        return (head !== null &&
+            current === (await this.git.entryBlobId(entry.path, head)));
+    }
+    /**
+     * The file still holds what enmetu left (Decision 99). When HEAD's version
+     * of the path is no longer heldOver, a rebase changed the path under the
+     * hold and the held bytes are based on the old version: written back as
+     * they are, enmetu's next commit would undo that change. Then the clean
+     * three-way merge of HEAD's version and the held bytes, base heldOver, goes
+     * back, only where no filter applies (raw hash equals filtered hash) and
+     * only while the file is still unchanged; a newer write wins and the held
+     * bytes are kept in a blob. Without a clean merge (a conflict, binary
+     * input, a filter, a deletion on either side) the held version goes back
+     * and the path is reported, so the undo is never silent. seen is the file
+     * the way the decision read it (observe); every write-back is skipped when the
+     * file changed since.
+     */
+    async putBackOnHead(entry, target, seen, attempt) {
+        if (entry.heldOver === null) {
+            // A memento from before heldOver existed: nothing to compare HEAD with.
+            return this.putBackUnlessChanged(entry, target, seen, attempt, 'restored');
+        }
+        const head = await this.git.headCommit();
+        const headBlob = head === null ? null : await this.git.entryBlobId(entry.path, head);
+        if (headBlob === entry.heldOver) {
+            return this.putBackUnlessChanged(entry, target, seen, attempt, 'restored');
+        }
+        if (entry.blobId !== null &&
+            headBlob !== null &&
+            isRegularFile(seen) &&
+            seen === (await this.git.worktreeBlobId(entry.path))) {
+            const merged = await this.mergeOntoHead(headBlob, entry.heldOver, entry.blobId);
+            if (merged !== null) {
+                const written = await this.writeOver(entry, target, seen, merged, entry.executable);
+                return written.kind === 'written'
+                    ? { kind: 'restored', overwritten: written.overwritten }
+                    : { kind: 'kept', blob: { path: entry.path, blobId: entry.blobId } };
+            }
+        }
+        return this.putBackUnlessChanged(entry, target, seen, attempt, 'restored-over-change');
+    }
+    /**
+     * Writes the held version back only while the file is still what the
+     * decision saw. A write that landed since (a person's editor saving
+     * during the restore's own spawns) is judged again from the top, at most
+     * MAX_RESTORE_REJUDGES times; after that the write wins and the held bytes
+     * stay a blob, so a restore never overwrites what it did not judge. The
+     * held bytes are read before the check, so no spawn runs between the check
+     * and the write (Decision 117).
+     */
+    async putBackUnlessChanged(entry, target, seen, attempt, kind) {
+        const content = entry.blobId === null ? null : await this.git.readBlob(entry.blobId);
+        const written = await this.writeOver(entry, target, seen, content, entry.executable);
+        if (written.kind === 'written') {
+            return { kind, overwritten: written.overwritten };
+        }
+        if (attempt < MAX_RESTORE_REJUDGES) {
+            return this.restoreEntry(entry, attempt + 1);
+        }
+        return entry.blobId === null
+            ? { kind: 'left' }
+            : { kind: 'kept', blob: { path: entry.path, blobId: entry.blobId } };
+    }
+    /**
+     * Writes content over the file (null: removes it) only while the file is
+     * what the decision saw (seen), and names a write that lands after that
+     * check (design 13.11, Decision 117). No git command can write a file only
+     * while it is unchanged, so the version being replaced is kept under a
+     * second name in the same step that replaces it:
+     *
+     * 1. content is written and flushed to a staged file first;
+     * 2. the file is checked against seen (one hashFile spawn);
+     * 3. link(2) gives the file's current version a second name, then rename(2)
+     *    puts the staged file in its place (a removal is one rename(2) to the
+     *    second name);
+     * 4. the second name is read: a version other than seen was written after
+     *    step 2, and is stored in a blob and reported, never lost unrecorded.
+     *
+     * What stays open is enmetu's own: a save that replaces the file by
+     * rename(2) between the link and the rename of step 3 (two consecutive
+     * system calls), and a write into the replaced version through a file
+     * descriptor opened before step 3 that lands after step 4's read. Where the
+     * state directory is on another file system than the working tree (a
+     * linked worktree of a repository on another volume), or the file is not a
+     * regular file, link(2) cannot keep it and the plain write runs, with the
+     * window of steps 2 and 3.
+     */
+    async writeOver(entry, target, seen, content, executable) {
+        const tempDir = this.tempDir();
+        if (seen === OBSERVED_OTHER ||
+            !(await this.fs.sameFileSystem(this.paths.root, this.paths.stateDir))) {
+            if ((await this.observe(entry.path, target)) !== seen) {
+                return { kind: 'changed' };
+            }
+            if (content === null) {
+                await this.fs.remove(target);
+            }
+            else {
+                await this.fs.writeAtomic(target, content, { executable, tempDir });
+            }
+            return { kind: 'written', overwritten: null };
+        }
+        const staged = join(tempDir, STAGED_FILE_NAME);
+        const previous = join(tempDir, PREVIOUS_FILE_NAME);
+        try {
+            // --- Step 1: the version to write, flushed before the check ---
+            if (content !== null) {
+                await this.fs.writeAtomic(staged, content, { executable, tempDir });
+            }
+            // --- Step 2: the decision's file, still there ---
+            if ((await this.observe(entry.path, target)) !== seen) {
+                return { kind: 'changed' };
+            }
+            // --- Step 3: replace, keeping what is replaced under a second name ---
+            await this.fs.remove(previous);
+            if (content === null) {
+                await this.fs.rename(target, previous);
+            }
+            else {
+                const linked = await this.fs.link(target, previous);
+                if (!linked && isRegularFile(seen)) {
+                    // Deleted since step 2: the deletion is newer than the decision.
+                    return { kind: 'changed' };
+                }
+                await this.fs.rename(staged, target);
+            }
+            // --- Step 4: a version written after step 2 is named ---
+            const replaced = await this.observe(previous, previous);
+            if (replaced === seen || !isRegularFile(replaced)) {
+                return { kind: 'written', overwritten: null };
+            }
+            const blobId = await this.writer.storeBlob(previous);
+            return { kind: 'written', overwritten: { path: entry.path, blobId } };
+        }
+        finally {
+            await this.fs.remove(staged);
+            await this.fs.remove(previous);
+        }
+    }
+    /** The file's raw blob id, or a marker for an absent path or one that is not a regular file. */
+    async observe(path, target) {
+        const facts = await this.fs.facts(target);
+        if (facts === null) {
+            return OBSERVED_ABSENT;
+        }
+        if (facts?.kind !== 'file') {
+            return OBSERVED_OTHER;
+        }
+        return this.git.hashFile(path);
+    }
+    /** Three-way merge of HEAD's blob with the held bytes on the base the hold left; null unless clean. */
+    async mergeOntoHead(headBlob, base, held) {
+        const headPath = join(this.tempDir(), MERGE_HEAD_FILE_NAME);
+        try {
+            await this.fs.writeAtomic(headPath, await this.git.readBlob(headBlob), {
+                executable: false,
+                tempDir: this.tempDir(),
+            });
+            return await this.mergeHeld(headPath, base, held);
+        }
+        finally {
+            await this.fs.remove(headPath);
+        }
+    }
+    /** Three-way merge of a file with the held bytes on the base the hold left; null unless clean. */
+    async mergeHeld(current, base, held) {
+        const basePath = join(this.tempDir(), MERGE_BASE_FILE_NAME);
+        const heldPath = join(this.tempDir(), MERGE_HELD_FILE_NAME);
+        const options = { executable: false, tempDir: this.tempDir() };
+        try {
+            await this.fs.writeAtomic(basePath, await this.git.readBlob(base), options);
+            await this.fs.writeAtomic(heldPath, await this.git.readBlob(held), options);
+            return await this.git.mergeFile(current, basePath, heldPath);
+        }
+        finally {
+            await this.fs.remove(basePath);
+            await this.fs.remove(heldPath);
+        }
+    }
+    tempDir() {
+        return join(this.paths.stateDir, QUARANTINE_TEMP_DIR_NAME);
+    }
+    async inspect(paths) {
+        const files = [];
+        for (const path of paths) {
+            const facts = await this.fs.facts(join(this.paths.root, path));
+            // Only a regular file round-trips through a blob and writeAtomic; a
+            // symlink, a directory or a special file would not come back unchanged.
+            if (facts !== null && facts.kind !== 'file') {
+                return { kind: 'unsupported', path };
+            }
+            files.push({ path, facts });
+        }
+        return { kind: 'files', files };
+    }
+    async storeEntries(files) {
+        const entries = [];
+        for (const { path, facts } of files) {
+            // Read before the checkout that writes it, so restore can tell the
+            // checkout's bytes from a person's write.
+            const heldOver = await this.git.entryBlobId(path, null);
+            entries.push(facts === null
+                ? { path, blobId: null, executable: false, heldOver }
+                : {
+                    path,
+                    blobId: await this.writer.storeBlob(path),
+                    executable: facts.executable,
+                    heldOver,
+                });
+        }
+        return entries;
+    }
+    async writeMemento(memento) {
+        // Built field by field in interface order, so the file is byte-stable.
+        const persisted = {
+            version: memento.version,
+            entries: memento.entries.map((entry) => ({
+                path: entry.path,
+                blobId: entry.blobId,
+                executable: entry.executable,
+                heldOver: entry.heldOver,
+            })),
+        };
+        await this.fs.writeAtomic(this.mementoPath(), `${JSON.stringify(persisted)}\n`, { executable: false, tempDir: this.paths.stateDir });
+    }
+    mementoPath() {
+        return join(this.paths.stateDir, QUARANTINE_FILE_NAME);
+    }
+}

package/dist/recovery/enmetuRebaseAbort.d.ts

@@ -0,0 +1,108 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHaltStore } from '../contracts/IHaltStore.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { IOperationJournal } from '../contracts/IOperationJournal.js';
+import type { IPathQuarantine } from '../contracts/IPathQuarantine.js';
+import type { IOrphanedCommitRecorder } from '../contracts/IStateRecorder.js';
+import { type RecordHaltDeps } from '../halt/recordHalt.js';
+export interface EnmetuRebaseAbortInput {
+    readonly cycleId: string;
+    /**
+     * The HEAD enmetu's rebase started from; the verification expects HEAD back
+     * there, unless a commit moved the branch off it (branchMovedTo).
+     */
+    readonly origHead: string;
+    readonly onto: string;
+    /**
+     * The attempt's GIT_REFLOG_ACTION (rebaseReflogAction of its journal entry),
+     * which tells the rebase's own HEAD moves from a commit made on its detached
+     * HEAD (Decision 124); null when no attempt token is known.
+     */
+    readonly reflogAction: string | null;
+}
+export interface EnmetuRebaseAbortDeps {
+    readonly git: IGitReader;
+    readonly writer: IGitWriter;
+    readonly journal: IOperationJournal;
+    readonly quarantine: IPathQuarantine;
+    readonly halt: IHaltStore;
+    readonly logger: ILogger;
+    readonly clock: IClock;
+    /** Told of each commit step 1a names, for the state file and `enmetu status` (design 14.15). */
+    readonly orphans?: IOrphanedCommitRecorder | undefined;
+}
+export type AbortVerdict = 'verified' | 'unverified';
+export interface EnmetuRebaseAbortResult {
+    readonly verdict: AbortVerdict;
+    /** Writes made during the stop went into the quarantine; the caller restores them. */
+    readonly captured: boolean;
+    /**
+     * The branch's tip when a commit moved the branch the rebase returns to off
+     * orig-head while the rebase ran: the rebase was ended at that tip
+     * (endRebaseAtBranch), never aborted to orig-head, and the verdict checks
+     * HEAD names the branch at that tip. null otherwise (design 14.4, Decision 122).
+     */
+    readonly branchMovedTo: string | null;
+}
+/** What the verification reads; the deps of the check alone, so it halts nothing. */
+export interface RebaseAbortCheckDeps {
+    readonly git: IGitReader;
+}
+/**
+ * Capture, abort and verify (1.11 abort-and-verify, 1.14 step 2): the one
+ * implementation for the live cycle and for startup recovery. The caller has
+ * already proven the rebase in progress is enmetu's (HEAD's reflog carries the
+ * attempt's token, or, without a reflog, orig-head and onto match; Decision 104).
+ *
+ * 0a. branchRef = git.rebaseHeadName(): the branch the rebase returns to,
+ *    null for a rebase started on a detached HEAD (Decision 122).
+ * 0. Read the writes that landed during the stop (Decision 45).
+ * 0b. Name: every staged path the abort resets that is not written, not
+ *    changed by the stopped commit and not orig-head's version is logged
+ *    STAGED_RESET with its stage-0 blob (Decisions 105, 115); nothing is
+ *    written for it.
+ * 0c. Capture, the last step before the abort: the status is read again, the
+ *    writes go through quarantine.extend, and the status is read again after
+ *    each capture, up to MAX_CAPTURE_ROUNDS captures, so a write that landed
+ *    while enmetu was naming or capturing is held too (Decision 113). A
+ *    written path the stopped commit changes that holds git's conflict
+ *    markers is not captured but named, and the abort resets it (Decision
+ *    118). A refused capture halts REBASE_ABORT_UNVERIFIED with the rebase
+ *    left in progress.
+ * 1a. A commit made on the rebase's detached HEAD (HEAD's newest reflog
+ *    entry is not the attempt's, and the attempt's last HEAD is an ancestor
+ *    of HEAD) is left on no branch by step 1 and its changes leave the disk:
+ *    COMMIT_ORPHANED names it with the remedy (Decision 124), and deps.orphans
+ *    records it for `enmetu status` (design 14.15).
+ * 1. tip = git.resolveCommit(branchRef), the last read before git's write. A
+ *    tip other than origHead (a commit moved the branch while the rebase
+ *    ran): writer.endRebaseAtBranch(branchRef) and REBASE_BRANCH_MOVED;
+ *    otherwise writer.abortRebase() (Decision 122).
+ * 2. Verify: no operation, nothing unmerged, HEAD at the moved tip or at
+ *    origHead and, with a branchRef, HEAD naming it; a failure halts
+ *    REBASE_ABORT_UNVERIFIED, none clears the journal. branchMovedTo carries
+ *    the tip step 1 ended at.
+ */
+export declare function abortEnmetuRebase(input: EnmetuRebaseAbortInput, deps: EnmetuRebaseAbortDeps): Promise<EnmetuRebaseAbortResult>;
+/**
+ * How many captures step 0c runs at most before the abort. Each capture takes
+ * a few git spawns; a write that lands during one is found by the next status
+ * read. The bound keeps a file saved over and over from holding the abort
+ * back for ever; what stays open is the time between the last status read and
+ * the reset inside `git rebase --abort` (design 13.11).
+ */
+export declare const MAX_CAPTURE_ROUNDS = 3;
+/**
+ * The verification's checks, read without halting: no operation in progress, nothing
+ * unmerged, HEAD back at origHead. Returns the failure's detail, or null when
+ * all three hold. It records nothing, so a caller can ask who started the
+ * rebase before it decides on a halt (design 13.2).
+ */
+export declare function rebaseAbortFailure(input: EnmetuRebaseAbortInput, deps: RebaseAbortCheckDeps): Promise<string | null>;
+/**
+ * Halts REBASE_ABORT_UNVERIFIED and keeps the journal and any memento, which
+ * are what a person needs to finish by hand.
+ */
+export declare function recordAbortUnverified(input: EnmetuRebaseAbortInput, failure: string, deps: RecordHaltDeps): Promise<void>;