@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/commit/repairStaleIndexController.js

@@ -0,0 +1,150 @@
+import { join } from 'node:path';
+/** At most this many repaired paths are named in the log line; the count is always exact. */
+export const MAX_REPAIRED_PATHS_LOGGED = 20;
+const SHORT_SHA_LENGTH = 7;
+/**
+ * Controller: sets back index entries that a person's git command wrote back
+ * from before enmetu's last move of HEAD, its commit or its pull (design
+ * 12.7, Decision 98). A command that read the real index before the move and
+ * writes it after (measured for git merge against enmetu's commit section;
+ * seen in the stress scenario against enmetu's rebase) leaves HEAD at
+ * lastMove.to and lastMove.from's entries in the index, which would revert
+ * the move in the person's next commit.
+ *
+ * 1. HEAD differs from lastMove.to: moved.
+ * 2. Candidates: git.stagedPaths() (index against HEAD), in git's order. A
+ *    path is stale when its index entry equals lastMove.from's (both absent
+ *    for a path the move added) while the working tree does not (absent, or
+ *    a regular file whose filtered blob is not from's; a link or a directory
+ *    is never stale). A path the move did not change has from's entry in
+ *    HEAD, so it differs from HEAD only with another entry and never matches.
+ *    Reverted: index entry and working tree both from's (design 13.2,
+ *    Decision 108). Neither: none. Only reverted: STAGED_REVERT once, nothing
+ *    written, reverted.
+ * 3. Prepare: fs.copy(realIndex, commit index), so every other entry, the
+ *    person's staged selection included, stays unchanged; commitIndex.writer
+ *    .unstage(stale) sets exactly those entries to HEAD's.
+ * 4. Critical section, shaped like the commit's (Decision 81): indexLock.acquire
+ *    (false: busy); an operation in progress or the real index's identity
+ *    differing from before: release, busy; HEAD moved: release, moved;
+ *    indexLock.install(commit index); release on every path.
+ * 5. INDEX_REPAIRED once, naming the paths, then STAGED_REVERT for reverted
+ *    paths; repaired. Busy or moved names nothing, so the next cycle does.
+ */
+export async function repairStaleIndexController(input, deps) {
+    const { cycleId, lastMove, before } = input;
+    // --- Step 1: only while HEAD is still where enmetu moved it ---
+    if ((await deps.git.headCommit()) !== lastMove.to) {
+        return { kind: 'moved' };
+    }
+    // --- Step 2: staged paths with the stale or the reverted signature ---
+    const stale = [];
+    const reverted = [];
+    for (const path of await deps.git.stagedPaths()) {
+        const signature = await classify(path, lastMove, deps);
+        if (signature === 'stale') {
+            stale.push(path);
+        }
+        else if (signature === 'reverted') {
+            reverted.push(path);
+        }
+    }
+    if (stale.length === 0) {
+        if (reverted.length === 0) {
+            return { kind: 'none' };
+        }
+        logReverted(reverted, input, deps);
+        return { kind: 'reverted', paths: reverted };
+    }
+    // --- Step 3: the repaired index, prepared beside the real one ---
+    if (!(await deps.fs.copy(deps.settings.realIndex, deps.commitIndex.path))) {
+        // No real index: a stale write-back always leaves one, so something else happened.
+        return { kind: 'busy' };
+    }
+    await deps.commitIndex.writer.unstage(stale);
+    // --- Step 4: install it under git's own index.lock ---
+    const installed = await install(lastMove.to, before, deps);
+    if (installed !== 'installed') {
+        return { kind: installed };
+    }
+    // --- Step 5: one line per repair, then the reverted paths once it is installed ---
+    deps.logger.log({
+        level: 'WARN',
+        code: 'INDEX_REPAIRED',
+        message: `a git command wrote back the index from before enmetu moved HEAD to ${lastMove.to.slice(0, SHORT_SHA_LENGTH)}; ${stale.length === 1 ? '1 index entry' : `${stale.length} index entries`} set back to HEAD, which a commit would otherwise revert: ${namedPaths(stale)}`,
+        cycleId,
+    });
+    if (reverted.length > 0) {
+        logReverted(reverted, input, deps);
+    }
+    return { kind: 'repaired', paths: stale };
+}
+/**
+ * Each side is a blob id, or null where the path is absent; the index side
+ * must be from's. Stale: the working-tree side is not from's, so a person who
+ * keeps editing the file after the move still matches, which is why the
+ * working tree is compared with from, not with to (stress seed 11 of
+ * follow-up review 2). Reverted: the working tree is from's too, where both
+ * absent count equal (Decision 108): a merge's restore_state, or a deliberate
+ * revert (git checkout HEAD~ -- <path>), which is why it is named and never
+ * repaired. null: neither.
+ */
+async function classify(path, lastMove, deps) {
+    const fromBlob = await deps.git.entryBlobId(path, lastMove.from);
+    if ((await deps.git.entryBlobId(path, null)) !== fromBlob) {
+        return null;
+    }
+    const facts = await deps.fs.facts(join(deps.settings.root, path));
+    if (facts === null) {
+        return fromBlob === null ? 'reverted' : 'stale';
+    }
+    if (facts.kind !== 'file') {
+        // A link, a directory or a special file: never judged, never touched.
+        return null;
+    }
+    return (await deps.git.worktreeBlobId(path)) === fromBlob
+        ? 'reverted'
+        : 'stale';
+}
+/**
+ * STAGED_REVERT (Decision 108): names enmetu's commit by its full id, so the
+ * remedy stays valid after a later commit of enmetu's records the revert.
+ */
+function logReverted(paths, input, deps) {
+    const { to } = input.lastMove;
+    deps.logger.log({
+        level: 'WARN',
+        code: 'STAGED_REVERT',
+        message: `staged and on disk as before enmetu moved HEAD to ${to.slice(0, SHORT_SHA_LENGTH)}, as a git merge refused with "would be overwritten by merge" leaves them: ${namedPaths(paths)}; unless you reverted them yourself, git restore --source=${to} --staged --worktree -- <path> brings back the version enmetu committed`,
+        cycleId: input.cycleId,
+    });
+}
+/** At most MAX_REPAIRED_PATHS_LOGGED paths, then how many more. */
+function namedPaths(paths) {
+    const named = paths.slice(0, MAX_REPAIRED_PATHS_LOGGED).join(', ');
+    const rest = paths.length - MAX_REPAIRED_PATHS_LOGGED;
+    return `${named}${rest > 0 ? ` and ${rest} more` : ''}`;
+}
+async function install(head, before, deps) {
+    // The lock names HEAD, so recovery after a crash in here keeps the
+    // installed index, which matches HEAD better than the stale one.
+    if (!(await deps.indexLock.acquire(head))) {
+        return 'busy';
+    }
+    try {
+        if ((await deps.git.repositoryState()).operation !== null) {
+            return 'busy';
+        }
+        if ((await deps.git.headCommit()) !== head) {
+            return 'moved';
+        }
+        if ((await deps.fs.identity(deps.settings.realIndex)) !== before) {
+            return 'busy';
+        }
+        await deps.indexLock.install(deps.commitIndex.path);
+        return 'installed';
+    }
+    finally {
+        await deps.indexLock.release();
+    }
+}

package/dist/commit/stageGuardedChanges.d.ts

@@ -0,0 +1,30 @@
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { ILogger } from '../contracts/ILogger.js';
+export interface StageGuardedInput {
+    readonly cycleId: string;
+}
+export interface StageGuardedDeps {
+    readonly git: IGitReader;
+    readonly writer: IGitWriter;
+    readonly logger: ILogger;
+    readonly skipJsonCheck: readonly string[];
+}
+export interface StageGuardedResult {
+    readonly staged: boolean;
+}
+/**
+ * Controller: stage everything, inspect the staged blobs with the shared
+ * content rules, unstage what is not fit to commit (F3, F10, F11, D11).
+ *
+ * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
+ * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
+ * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
+ * 4. staged = git.hasStagedChanges().
+ *
+ * Inspecting the staged blobs rather than the working tree means what is
+ * inspected is exactly what the next commit records (Decision 5). The
+ * controller raises no error of its own; git failures propagate unchanged to
+ * the cycle, which owns the busy mapping and threads the cycle id.
+ */
+export declare function stageGuardedChanges(input: StageGuardedInput, deps: StageGuardedDeps): Promise<StageGuardedResult>;

package/dist/commit/stageGuardedChanges.js

@@ -0,0 +1,52 @@
+import { findContentViolation, MAX_SCAN_BYTES, } from '../core/content/contentRules.js';
+/**
+ * Controller: stage everything, inspect the staged blobs with the shared
+ * content rules, unstage what is not fit to commit (F3, F10, F11, D11).
+ *
+ * 1. writer.stageAll(); partial logs STAGE_PARTIAL.
+ * 2. For each git.stagedFiles(MAX_SCAN_BYTES): findContentViolation.
+ * 3. Violations: one writer.unstage(paths) call, EXCLUDED logged per path.
+ * 4. staged = git.hasStagedChanges().
+ *
+ * Inspecting the staged blobs rather than the working tree means what is
+ * inspected is exactly what the next commit records (Decision 5). The
+ * controller raises no error of its own; git failures propagate unchanged to
+ * the cycle, which owns the busy mapping and threads the cycle id.
+ */
+export async function stageGuardedChanges(input, deps) {
+    // --- Step 1: stage the whole tree ---
+    const stage = await deps.writer.stageAll();
+    if (stage.partial) {
+        // One unreadable file is reported and skipped instead of blocking every commit.
+        deps.logger.log({
+            level: 'WARN',
+            code: 'STAGE_PARTIAL',
+            message: stage.detail,
+            cycleId: input.cycleId,
+        });
+    }
+    // --- Step 2: inspect one staged blob at a time ---
+    const violations = [];
+    for await (const file of deps.git.stagedFiles(MAX_SCAN_BYTES)) {
+        const violation = findContentViolation(file, deps.skipJsonCheck);
+        if (violation !== null) {
+            violations.push(violation);
+        }
+    }
+    // --- Step 3: unstage the violations in one call, in git's order ---
+    if (violations.length > 0) {
+        // reset also clears unmerged entries, which git add has already turned
+        // into stage-0 marker text; the bytes stay on disk for the person.
+        await deps.writer.unstage(violations.map((violation) => violation.path));
+        for (const violation of violations) {
+            deps.logger.log({
+                level: 'WARN',
+                code: 'EXCLUDED',
+                message: `${violation.path}: ${violation.rule} (${violation.detail})`,
+                cycleId: input.cycleId,
+            });
+        }
+    }
+    // --- Step 4: report whether anything is left to commit ---
+    return { staged: await deps.git.hasStagedChanges() };
+}

package/dist/contracts/IClock.d.ts

@@ -0,0 +1,7 @@
+export interface TimerHandle {
+    cancel(): void;
+}
+export interface IClock {
+    now(): number;
+    after(ms: number, callback: () => void): TimerHandle;
+}

package/dist/contracts/IClock.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IDaemon.d.ts

@@ -0,0 +1,26 @@
+import type { ExitCode } from './exitCode.js';
+import type { Upstream } from './gitTypes.js';
+import type { HaltCode } from './IHaltStore.js';
+export type RecoveryAction = 'REBASE_ABORTED' | 'STALE_JOURNAL_CLEARED' | 'QUARANTINE_RESTORED'
+/** An index.lock left by a crashed enmetu's commit (design 12.7). */
+ | 'INDEX_LOCK_RELEASED';
+export type RecoveryResult = {
+    readonly kind: 'clean';
+} | {
+    readonly kind: 'recovered';
+    readonly actions: readonly RecoveryAction[];
+} | {
+    readonly kind: 'halted';
+    readonly code: HaltCode;
+};
+/** recoveryController with its deps bound (a closure built by the composition root). */
+export interface IRecovery {
+    recover(): Promise<RecoveryResult>;
+}
+/** repositoryPreflight with its deps bound; throws PreflightError. */
+export interface IPreflight {
+    check(): Promise<Upstream>;
+}
+export interface IDaemon {
+    run(): Promise<ExitCode>;
+}

package/dist/contracts/IDaemon.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IFileSystem.d.ts

@@ -0,0 +1,50 @@
+export interface FileFacts {
+    readonly kind: 'file' | 'directory' | 'symlink' | 'other';
+    readonly executable: boolean;
+}
+export interface WriteOptions {
+    readonly executable: boolean;
+    /**
+     * Where the temp file is created before the rename. A rename across file
+     * systems (EXDEV) retries with the temp file in the target's directory.
+     */
+    readonly tempDir: string;
+}
+export interface IFileSystem {
+    /** null when absent. */
+    readText(path: string): Promise<string | null>;
+    /** Temp file, then rename over the target; creates parent directories. */
+    writeAtomic(path: string, content: string | Buffer, options: WriteOptions): Promise<void>;
+    /** Complete content or nothing: temp file, link(2) to the target, unlink temp; creates parent directories. false when the target exists. */
+    createExclusive(path: string, content: string): Promise<boolean>;
+    /** rename(2); false when the source does not exist; creates the target's parent directory when it is missing. Exactly one of two concurrent renames of one file succeeds. */
+    rename(from: string, to: string): Promise<boolean>;
+    /** No error when absent. */
+    remove(path: string): Promise<void>;
+    /** lstat; null when absent. */
+    facts(path: string): Promise<FileFacts | null>;
+    /**
+     * Copies a file's bytes over the target in one open (copy-on-write where
+     * the file system offers it); false when the source does not exist. The
+     * copy's modification time is the source's, rounded down to the whole
+     * second and read before the copy, so never later than the copied bytes:
+     * git judges an index entry "racily clean" against its index file's own
+     * modification time, in whole seconds, and a fresh time on a copied index
+     * would hide a same-size edit made in the second the source was written.
+     */
+    copy(from: string, to: string): Promise<boolean>;
+    /**
+     * An opaque identity of the file's current version (stat: device, inode,
+     * size, modification and change time); null when absent. Two equal values
+     * mean no rename replaced the file and no write changed it in between (design 12.7).
+     */
+    identity(path: string): Promise<string | null>;
+    /** link(2): a second name for the same file; false when the source does not exist. Fails when the target exists. */
+    link(existing: string, target: string): Promise<boolean>;
+    /**
+     * Whether two existing paths are on one file system (stat's device), so
+     * link(2) and rename(2) between them can work; throws when either is
+     * absent (design 13.11, Decision 117).
+     */
+    sameFileSystem(left: string, right: string): Promise<boolean>;
+}

package/dist/contracts/IFileSystem.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitCommitter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The repository hooks enmetu runs around its own commit when commitHooks is
+ * true (design 12.7). The message hooks (prepare-commit-msg, commit-msg) do
+ * not run, so no hook can put a name into enmetu's message (Decision 80).
+ */
+export type CommitHookName = 'pre-commit' | 'post-commit' | 'post-index-change';
+export type HookRun = {
+    readonly kind: 'passed';
+}
+/**
+ * The hook exited non-zero, outlived hookTimeoutMs or was ended by a signal;
+ * detail is its stderr, or the timeout or signal.
+ */
+ | {
+    readonly kind: 'rejected';
+    readonly detail: string;
+};
+export interface CommitTreeInput {
+    readonly tree: string;
+    /** HEAD at the time the commit index was seeded: the only parent, never MERGE_HEAD. */
+    readonly parent: string;
+    /** The whole message, passed on stdin. */
+    readonly message: string;
+    /** -S when true, --no-gpg-sign when false: commit-tree does not read commit.gpgSign itself. */
+    readonly sign: boolean;
+}
+/**
+ * Runs one repository hook through `git hook run --ignore-missing`, which
+ * honours core.hooksPath; a missing hook passes. The hook gets its own
+ * timeout (hookTimeoutMs) and its output is truncated, never a failure. The
+ * facade it is called on decides GIT_INDEX_FILE: the commit index for
+ * pre-commit, the real index for post-commit and post-index-change.
+ */
+export interface IGitHookRunner {
+    runHook(name: CommitHookName, args: readonly string[]): Promise<HookRun>;
+    /**
+     * Whether `git hook run` would find the hook: the path git itself resolves
+     * (`rev-parse --git-path hooks/<name>`, which honours core.hooksPath) is an
+     * executable file, or a symbolic link, which counts too, so a doubt
+     * costs a redundant check rather than a missed hook.
+     */
+    hookExists(name: CommitHookName): Promise<boolean>;
+}
+/**
+ * Plumbing for enmetu's own commits on the commit index
+ * (<stateDir>/commit-index): nothing here touches the real index, HEAD or a
+ * ref, and nothing here runs a hook but runHook.
+ */
+export interface IGitCommitter extends IGitHookRunner {
+    /**
+     * git read-tree --reset <commit>, hookless: the commit index holds that
+     * commit's tree, stat data kept where content matches. --reset, not -m,
+     * because -m refuses an index with unmerged entries (a conflicted stash pop).
+     */
+    seedFrom(commit: string): Promise<void>;
+    /** git write-tree of the commit index, hookless. */
+    writeTree(): Promise<string>;
+    /** git commit-tree; runs no hook, concludes nothing, moves no ref. */
+    commitTree(input: CommitTreeInput): Promise<string>;
+}

package/dist/contracts/IGitCommitter.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitConfigReader.d.ts

@@ -0,0 +1,5 @@
+/** The one git question the hook installer needs; it cannot write configuration through it. */
+export interface IGitConfigReader {
+    /** null when unset at every scope. */
+    configValue(key: string): Promise<string | null>;
+}

package/dist/contracts/IGitConfigReader.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitIndexLock.d.ts

@@ -0,0 +1,44 @@
+/** What startup found of an index.lock a crashed enmetu left (design 12.7). */
+export type StaleIndexLock = 
+/** No index.lock, one that is not enmetu's, or one whose enmetu is still alive: nothing touched. */
+{
+    readonly kind: 'none';
+}
+/**
+ * Removed. kept: HEAD is the commit the lock names, so the installed index
+ * already matches it. restored: HEAD is not, so index.before went back over
+ * the real index.
+ */
+ | {
+    readonly kind: 'released';
+    readonly index: 'kept' | 'restored';
+};
+/**
+ * git's own lockfile protocol on <gitDir>/index.lock, held by enmetu across
+ * the index install and the branch swap of its commit (design 12.7), so no
+ * git command can write the real index, start a merge or commit a stale index
+ * inside that window. The lock file's content names enmetu, its pid and the
+ * commit it is about to install, so a lock left by a crashed enmetu can be told
+ * from a person's and finished or undone at the next start.
+ */
+export interface IGitIndexLock {
+    /** createExclusive(index.lock, 'enmetu index lock, pid <pid>, commit <commit>\n'); false when another process holds it. */
+    acquire(commit: string): Promise<boolean>;
+    /**
+     * Under the lock: hard-links <gitDir>/index to <stateDir>/index.before (the
+     * person's current index), then renames the prepared index over
+     * <gitDir>/index. A reader sees the old index or the new one, never none.
+     */
+    install(preparedIndex: string): Promise<void>;
+    /** Under the lock, after a failed swap: renames index.before back over <gitDir>/index. */
+    restore(): Promise<void>;
+    /** Removes index.before, then the lock this instance holds; the index stays unchanged. */
+    release(): Promise<void>;
+    /**
+     * Startup only, with the current HEAD: an index.lock with enmetu's content
+     * and a dead pid is finished (HEAD is the named commit: index.before removed)
+     * or undone (index.before renamed back), then removed. Never touches any other
+     * index.lock.
+     */
+    releaseStale(head: string | null): Promise<StaleIndexLock>;
+}

package/dist/contracts/IGitIndexLock.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitReader.d.ts

@@ -0,0 +1,81 @@
+import type { Divergence, HeadMove, RebaseStart, RemoteHead, RepositoryState, StagedFile, StatusEntry, Upstream } from './gitTypes.js';
+import type { IGitConfigReader } from './IGitConfigReader.js';
+export interface IGitReader extends IGitConfigReader {
+    repositoryState(): Promise<RepositoryState>;
+    /** null when HEAD is unborn. */
+    headCommit(): Promise<string | null>;
+    hasCommitterIdentity(): Promise<boolean>;
+    /** null when the branch has no upstream. */
+    upstream(branchRef: string): Promise<Upstream | null>;
+    /** Whole tree, or only the given root-relative paths. */
+    status(paths?: readonly string[] | undefined): Promise<readonly StatusEntry[]>;
+    /**
+     * Staged regular files, read one cat-file batch chunk at a time, so at most
+     * one chunk of content is held while the consumer inspects it.
+     */
+    stagedFiles(maxBytes: number): AsyncIterable<StagedFile>;
+    hasStagedChanges(): Promise<boolean>;
+    /** Root-relative paths whose index entry differs from HEAD's, a rename being a delete plus an add (Decision 98). */
+    stagedPaths(): Promise<readonly string[]>;
+    remoteHead(remote: string, remoteRef: string): Promise<RemoteHead>;
+    /** null when the ref does not exist. */
+    resolveCommit(ref: string): Promise<string | null>;
+    isAncestor(ancestor: string, descendant: string): Promise<boolean>;
+    divergence(upstreamSha: string): Promise<Divergence>;
+    hasUnmergedPaths(): Promise<boolean>;
+    /** orig-head of a rebase in progress, null when none is in progress. */
+    rebaseOrigHead(): Promise<string | null>;
+    /** onto of a rebase in progress, null when none is in progress. */
+    rebaseOnto(): Promise<string | null>;
+    /**
+     * The branch a rebase in progress returns to: its head-name file
+     * (`refs/heads/main`), which `git rebase --abort` resets to orig-head with
+     * no old-value check. null when no rebase is in progress or it started on a
+     * detached HEAD (head-name `detached HEAD`). Design 14.4, Decision 122.
+     */
+    rebaseHeadName(): Promise<string | null>;
+    /**
+     * HEAD's newest "(start)" reflog entry: `git reflog exists HEAD` (exit 1:
+     * unlogged), then `git log -g -1 --format=%gs --grep-reflog=" (start): "
+     * HEAD` (empty: none). rebaseOwner (src/core/git/rebaseOwnership.ts) turns
+     * it and the journal into the owner of the rebase in progress (design
+     * 13.2, Decision 104).
+     */
+    rebaseStart(): Promise<RebaseStart>;
+    /**
+     * HEAD's move since the rebase run under reflogAction (its
+     * GIT_REFLOG_ACTION) last moved it, read from HEAD's newest reflog entries
+     * (`git log -g -n <bound> --format="%H %gs" HEAD`). null when the newest
+     * entry is the rebase's own (`<reflogAction> (`), when none of the read
+     * entries is, or when HEAD has no reflog (design 14.14, Decision 124).
+     */
+    headMovedSince(reflogAction: string): Promise<HeadMove | null>;
+    /** The commit's subject line (`git log -1 --format=%s <commit>`), design 14.15. */
+    commitSubject(commit: string): Promise<string>;
+    /**
+     * Whether an orphaned commit was dealt with (design 14.15): a local branch
+     * contains it (`git for-each-ref --count=1 --contains <commit> refs/heads/`,
+     * after a merge or a branch made at it), or a commit on a local branch
+     * committed since `since` records picking it (`git log --branches -F
+     * --grep="(cherry picked from commit <commit>)"`, which `git cherry-pick -x`
+     * writes, also after a resolved conflict). The commit must resolve.
+     */
+    onLocalBranch(commit: string, since: string): Promise<boolean>;
+    readBlob(blobId: string): Promise<Buffer>;
+    /** Blob id the file's current bytes would get, without filters, without writing. */
+    hashFile(path: string): Promise<string>;
+    /** Blob id `git add` would stage for the file's current bytes, filters applied, without writing an object. */
+    worktreeBlobId(path: string): Promise<string>;
+    /** Blob id of the path in a commit's tree, or in the index's stage-0 entry when commit is null; null when there is none. */
+    entryBlobId(path: string, commit: string | null): Promise<string | null>;
+    /**
+     * git merge-file -p of three files given by absolute path: the merged bytes
+     * when the three-way merge is clean, null when it conflicts or git cannot
+     * merge them (binary). Writes nothing, no conflict marker ever leaves it.
+     */
+    mergeFile(current: string, base: string, other: string): Promise<Buffer | null>;
+    /** The best common ancestor of two commits; null when they share none (design 12.3). */
+    mergeBase(left: string, right: string): Promise<string | null>;
+    /** Root-relative paths that differ between two commits, a rename being a delete plus an add, in git's order. */
+    changedPaths(from: string, to: string): Promise<readonly string[]>;
+}

package/dist/contracts/IGitReader.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitRunner.d.ts

@@ -0,0 +1,49 @@
+export interface GitRunOptions {
+    /** Written to git's stdin, then stdin is closed. */
+    readonly stdin?: string | undefined;
+    /**
+     * Replaces the adapter's per-command timeout for this call: a repository
+     * hook's own budget (design 12.7). The call runs git, leading its own
+     * process group and the timeout ends the whole group (SIGTERM, then SIGKILL
+     * after 2 s), so a hook git started never outlives it.
+     */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Keeps at most this many bytes of stdout and of stderr and drops the rest
+     * instead of failing (a repository hook's output, design 12.7).
+     */
+    readonly outputCapBytes?: number | undefined;
+    /**
+     * Ends the call like its timeout once aborted (the whole process group,
+     * SIGTERM, then SIGKILL after 2 s), and the call throws GIT_ABORTED; an
+     * already aborted signal spawns nothing. A stop request ends a running
+     * repository hook this way (design 12.7, Decision 92).
+     */
+    readonly abort?: AbortSignal | undefined;
+    /**
+     * Sets GIT_REFLOG_ACTION for this call only, so the entries git writes to
+     * HEAD's reflog carry this action instead of the command's name: enmetu's
+     * rebase writes "enmetu <cycleId> <at> (start): checkout <sha>", the
+     * attempt's own token, which tells it from a person's rebase with the same
+     * orig-head and onto and from an earlier attempt of enmetu's (design 13.2,
+     * Decision 104).
+     */
+    readonly reflogAction?: string | undefined;
+}
+export interface GitRunResult {
+    readonly exitCode: number;
+    readonly stdout: Buffer;
+    readonly stderr: string;
+}
+/**
+ * Runs the git binary with an argument array (execFile, never a shell).
+ * Never throws for a non-zero exit code: the caller interprets it.
+ * Throws GitCommandError GIT_NOT_FOUND when the binary cannot be spawned and
+ * GIT_TIMEOUT when the per-command timeout elapses (git is killed with SIGTERM),
+ * and GIT_ABORTED when options.abort ends the call.
+ */
+export interface IGitRunner {
+    run(args: readonly string[], options?: GitRunOptions): Promise<GitRunResult>;
+}
+/** Builds a runner for a working directory; the locator needs one before the root is known. */
+export type GitRunnerFactory = (cwd: string) => IGitRunner;

package/dist/contracts/IGitRunner.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IGitWriter.d.ts

@@ -0,0 +1,39 @@
+import type { FetchResult, PushResult, RebaseResult, StageResult } from './gitTypes.js';
+export interface IGitWriter {
+    stageAll(): Promise<StageResult>;
+    unstage(paths: readonly string[]): Promise<void>;
+    /** Fetches remoteRef into intoRef only; no other ref moves. */
+    fetch(remote: string, remoteRef: string, intoRef: string): Promise<FetchResult>;
+    /**
+     * Compare-and-swap: moves ref to newSha only while it still points at oldSha
+     * (oldSha null: only while the ref does not exist). A mismatch throws GIT_FAILED.
+     */
+    updateRef(ref: string, newSha: string, oldSha: string | null): Promise<void>;
+    /**
+     * reflogAction: GIT_REFLOG_ACTION for this rebase only, the attempt's own
+     * token (rebaseReflogAction of its journal entry), so HEAD's reflog names
+     * this attempt in its "(start)" entry (design 13.2, Decision 104).
+     */
+    rebase(ontoSha: string, reflogAction: string): Promise<RebaseResult>;
+    /** Exit code ignored on purpose: the caller verifies the outcome. */
+    abortRebase(): Promise<void>;
+    /**
+     * Ends enmetu's own rebase at the branch's current tip instead of at
+     * orig-head: `git rebase --quit` (removes the rebase state, writes no ref,
+     * index entry or file), then `git switch --discard-changes <branch>` (index
+     * and tree to the branch's tip, whatever they hold, as the abort's reset
+     * does). For a branch a commit moved during the rebase, which
+     * `git rebase --abort` would reset to orig-head and so drop that commit
+     * (design 14.4, Decision 122). Exit codes ignored: the caller verifies.
+     */
+    endRebaseAtBranch(branchRef: string): Promise<void>;
+    /**
+     * Pushes exactly this commit to remoteRef (`<sha>:<remoteRef>`), never a
+     * ref git resolves at push time, so the caller knows what it pushed
+     * (design 13.11, Decision 111).
+     */
+    push(remote: string, sha: string, remoteRef: string): Promise<PushResult>;
+    /** Writes the file's bytes into the object store without filters; returns the blob id. */
+    storeBlob(path: string): Promise<string>;
+    restoreFromIndex(paths: readonly string[]): Promise<void>;
+}

package/dist/contracts/IGitWriter.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/IHaltStore.d.ts

@@ -0,0 +1,14 @@
+export type HaltCode = 'REBASE_ABORT_UNVERIFIED' | 'UPSTREAM_REWRITTEN' | 'QUARANTINE_RESTORE_FAILED' | 'HALT_MARKER_UNREADABLE';
+export interface HaltRecord {
+    readonly code: HaltCode;
+    readonly message: string;
+    readonly cycleId: string | null;
+    /** ISO-8601 UTC; 'unknown' for a marker that cannot be parsed (HALT_MARKER_UNREADABLE). */
+    readonly at: string;
+}
+export interface IHaltStore {
+    /** An unparseable marker means halted, with code HALT_MARKER_UNREADABLE (fail-safe). */
+    read(): Promise<HaltRecord | null>;
+    set(record: HaltRecord): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/contracts/IHaltStore.js

@@ -0,0 +1 @@
+export {};