@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/teardown.js

@@ -0,0 +1,422 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { MACHINE_IDENTITY_EMAIL, MACHINE_IDENTITY_NAME } from "./commands/init.js";
+import { guardSharedRegister } from "./exclusion.js";
+import { poolDestroy, readPoolRecord, reconstructPoolRecord, worktreePath, } from "./pool.js";
+import { checkHoldership, metaPath, readTaskMeta, reportPath, runStep, setTaskStatus, singleLine, } from "./task.js";
+/**
+ * Local git runner. It is deliberately not the pool's: src/pool.ts is
+ * explicitly out of this phase's edit scope, and teardown needs no
+ * contention retry, because nothing in M1 runs teardown concurrently
+ * with anything else (parallelism is off until M5). The locale is pinned
+ * for the same reason the pool pins it: reproducible output.
+ */
+function runGit(cwd, args, extraEnv) {
+    const result = spawnSync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C", ...extraEnv },
+    });
+    if (result.error !== undefined) {
+        return { status: null, stdout: "", stderr: String(result.error) };
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/** The commit-message prefix every salvaged commit carries (R-081a). */
+export const SALVAGE_PREFIX = "WIP-UNREVIEWED (do not treat as reviewed):";
+/**
+ * Is branchRef landed on defaultRef? Both are resolved in contextDir,
+ * and defaultRef is always the just-fetched remote-tracking ref.
+ */
+export function landedness(contextDir, branchRef, defaultRef) {
+    const ancestor = runGit(contextDir, [
+        "merge-base",
+        "--is-ancestor",
+        branchRef,
+        defaultRef,
+    ]);
+    if (ancestor.status === 0) {
+        return { kind: "landed", how: "ancestor" };
+    }
+    if (ancestor.status !== 1) {
+        return {
+            kind: "inconclusive",
+            detail: `git merge-base --is-ancestor exited ${String(ancestor.status)}: ${singleLine(ancestor.stderr)}`,
+        };
+    }
+    const defaultTree = runGit(contextDir, ["rev-parse", "--verify", `${defaultRef}^{tree}`]);
+    if (defaultTree.status !== 0) {
+        return {
+            kind: "inconclusive",
+            detail: `cannot resolve the tree of ${defaultRef}: ${singleLine(defaultTree.stderr)}`,
+        };
+    }
+    const merged = runGit(contextDir, ["merge-tree", "--write-tree", defaultRef, branchRef]);
+    if (merged.status === 1) {
+        // Conflicts: merging is not a no-op, so the branch is not landed.
+        return { kind: "unlanded" };
+    }
+    if (merged.status !== 0) {
+        return {
+            kind: "inconclusive",
+            detail: `git merge-tree --write-tree exited ${String(merged.status)}: ${singleLine(merged.stderr)}`,
+        };
+    }
+    const mergedTree = merged.stdout.split("\n")[0]?.trim() ?? "";
+    if (mergedTree === "") {
+        return {
+            kind: "inconclusive",
+            detail: "git merge-tree --write-tree produced no tree id",
+        };
+    }
+    return mergedTree === defaultTree.stdout.trim()
+        ? { kind: "landed", how: "squash" }
+        : { kind: "unlanded" };
+}
+/**
+ * Resolve everything teardown needs, and perform the mandatory fetch.
+ * Read-only with respect to the task: the fetch updates only the
+ * project's remote-tracking ref.
+ */
+function resolveContext(fleet, taskId, fromReconstructed) {
+    const meta = readTaskMeta(fleet, taskId);
+    if (meta === undefined) {
+        return {
+            ok: false,
+            reason: `no readable task meta for task id ${taskId}; teardown needs tasks/${taskId}/meta.json`,
+        };
+    }
+    let record = readPoolRecord(fleet, taskId);
+    let reconstructed = false;
+    if (record === undefined) {
+        if (!fromReconstructed) {
+            return {
+                ok: false,
+                reason: `no readable pool record for task id ${taskId}; teardown needs it for the ` +
+                    `project remote and default branch, and refuses rather than guessing them; ` +
+                    `pass --from-reconstructed to rebuild them from tasks/${taskId}/meta.json ` +
+                    `and git, which keeps every other refusal in force`,
+            };
+        }
+        // NETWORK ALLOWED here and nowhere else in this kernel's
+        // reconstruction (M4-P19 fix round). Teardown is a command the
+        // operator invoked in order to destroy something, it is about to
+        // fetch from this remote on the next line regardless, and it is
+        // allowed to take as long as that fetch takes. `pool list` and
+        // doctor are not, and they pass `{ network: false }`.
+        const rebuilt = reconstructPoolRecord(fleet, taskId, { network: true });
+        if (rebuilt.kind === "absent") {
+            return {
+                ok: false,
+                reason: `cannot reconstruct the pool record for task id ${taskId}: ${rebuilt.reason}`,
+            };
+        }
+        if (rebuilt.kind === "incomplete") {
+            // The missing FIELD is named, not merely the failure, because the
+            // remedy differs per field: `remote` is a git configuration repair
+            // in the clone, `branch` is usually an origin/HEAD that was never
+            // set or a remote that cannot be reached to advertise it.
+            return {
+                ok: false,
+                reason: `cannot reconstruct the pool record for task id ${taskId}: unresolved ` +
+                    `field(s) ${rebuilt.unresolved.join(", ")} (${rebuilt.detail}); teardown ` +
+                    `refuses rather than guessing them`,
+            };
+        }
+        record = rebuilt.record;
+        reconstructed = true;
+    }
+    const worktree = worktreePath(fleet, taskId);
+    const defaultRef = `refs/remotes/${record.remote}/${record.branch}`;
+    // PR-001: fetch first, always, and judge landed-ness only against this.
+    const fetched = runGit(record.project, [
+        "fetch",
+        record.remote,
+        `+refs/heads/${record.branch}:${defaultRef}`,
+    ]);
+    if (fetched.status !== 0) {
+        return {
+            ok: false,
+            reason: `fetch of ${record.remote}/${record.branch} failed, so landed-ness cannot ` +
+                `be judged against fresh remote state: ${singleLine(fetched.stderr)}`,
+        };
+    }
+    return { ok: true, value: { meta, record, reconstructed, worktree, defaultRef } };
+}
+/** Uncommitted changes or untracked files in the task worktree. */
+function worktreeDirty(worktree) {
+    const status = runGit(worktree, ["status", "--porcelain"]);
+    if (status.status !== 0) {
+        return {
+            ok: false,
+            reason: `cannot verify worktree cleanliness at ${worktree}: ${singleLine(status.stderr)}`,
+        };
+    }
+    return { ok: true, dirty: status.stdout.trim() !== "" };
+}
+/** Commit the leavings under the WIP label and push the branch (R-081a). */
+function salvageLeavings(context) {
+    const { worktree, record } = context;
+    const added = runGit(worktree, ["add", "-A"]);
+    if (added.status !== 0) {
+        return { ok: false, reason: `salvage failed at git add: ${singleLine(added.stderr)}` };
+    }
+    const message = `${SALVAGE_PREFIX} leavings salvaged by tiphys teardown for task ${context.meta.id}`;
+    // CI runners have no git identity, and the fleet never reads or writes
+    // user or global git configuration (EXT-F-02 option B): the machine
+    // identity is set command-scoped, exactly as init's bootstrap commit
+    // does it.
+    const committed = runGit(worktree, ["commit", "-m", message], {
+        GIT_AUTHOR_NAME: MACHINE_IDENTITY_NAME,
+        GIT_AUTHOR_EMAIL: MACHINE_IDENTITY_EMAIL,
+        GIT_COMMITTER_NAME: MACHINE_IDENTITY_NAME,
+        GIT_COMMITTER_EMAIL: MACHINE_IDENTITY_EMAIL,
+    });
+    if (committed.status !== 0) {
+        return {
+            ok: false,
+            reason: `salvage failed at git commit: ${singleLine(committed.stderr) || singleLine(committed.stdout)}`,
+        };
+    }
+    const pushed = runGit(record.project, [
+        "push",
+        record.remote,
+        `refs/heads/${record.branchName}:refs/heads/${record.branchName}`,
+    ]);
+    if (pushed.status !== 0) {
+        return {
+            ok: false,
+            reason: `salvage committed the leavings as "${SALVAGE_PREFIX} ..." but the push of ` +
+                `${record.branchName} failed: ${singleLine(pushed.stderr)}; the commit is local only`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Remove the worktree and close the task. Never called before every
+ * refusal rule has passed.
+ */
+async function finish(fleet, context, options) {
+    const destroyed = await poolDestroy(fleet, {
+        taskId: context.meta.id,
+        discard: options.discard,
+        deleteBranchForce: options.deleteBranchForce,
+        // M4-P19: in memory only, and only when the record was rebuilt. This
+        // makes the destroy's own base-sha gate ABLE to judge instead of
+        // abstaining with its "pool record missing" refusal; it does not
+        // create a file and it does not relax a gate.
+        ...(context.reconstructed ? { reconstructed: context.record } : {}),
+    });
+    if (!destroyed.ok) {
+        // The destroy's own reason distinguishes a stage-2 refusal (a true
+        // no-op) from a stage-3 partial failure (worktree already removed,
+        // survivors enumerated). It is passed through verbatim, and the only
+        // thing added is what this layer knows for certain.
+        return {
+            ok: false,
+            reason: `pool destroy did not complete: ${destroyed.reason}; task ${context.meta.id} stays open`,
+        };
+    }
+    // F-1. The worktree is GONE by this point, so a raised write here is
+    // not a refusal and must never crash the command: an uncaught throw
+    // left meta.json reading "open" beside a worktree that no longer
+    // exists, which is the single state authority (C-1) telling a later
+    // reader, and the M1-P5 watcher, something false. It is the same
+    // partial-failure shape M1-P3 defined for destroy, reported in the
+    // same vocabulary, with the manual remedy named.
+    const closed = runStep(`marking task ${context.meta.id} closed`, () => {
+        setTaskStatus(fleet, context.meta, "closed");
+    });
+    if (!closed.ok) {
+        const removed = destroyed.value.deletedBranch === undefined
+            ? `worktree ${context.worktree} HAS BEEN REMOVED`
+            : `worktree ${context.worktree} HAS BEEN REMOVED and branch ` +
+                `${destroyed.value.deletedBranch} was deleted (it was ` +
+                `${destroyed.value.deletedSha ?? "unknown"})`;
+        return {
+            ok: false,
+            reason: `partial teardown of task id ${context.meta.id}: ${removed}, but ` +
+                `${metaPath(fleet, context.meta.id)} could not be marked closed ` +
+                `(${closed.reason}); the task record still reads status open although its ` +
+                `worktree is gone, so repair that file and set "status": "closed" by hand`,
+        };
+    }
+    return { ok: true, value: { taskId: context.meta.id, salvaged: options.salvaged } };
+}
+export async function teardownTask(fleet, options) {
+    const holdership = checkHoldership(fleet);
+    if (!holdership.ok) {
+        return { ok: false, reason: holdership.reason };
+    }
+    /* THE CROSS-ENVIRONMENT HALF (M4-P22 criterion 3), rule 0's second limb.
+       `checkHoldership` above returns OK when this environment holds the local
+       lease, and the local lease is evidence about this filesystem alone
+       (src/lock.ts:63). With the shared register naming another environment,
+       the old guard is green and teardown would remove a worktree the other
+       orchestrator is working in. One reason line, nonzero exit, and NOTHING
+       REMOVED: it runs before `resolveContext`, so no pool record is read, no
+       worktree is probed and no branch is deleted. A teardown that refuses
+       after deleting something has failed in the way that matters. */
+    const sharedGuard = guardSharedRegister(fleet.root, "teardown");
+    if (sharedGuard.kind === "refused") {
+        return { ok: false, reason: sharedGuard.reason };
+    }
+    const resolved = resolveContext(fleet, options.taskId, options.fromReconstructed);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    const context = resolved.value;
+    const { meta, record, worktree } = context;
+    if (meta.shape === "scout") {
+        // M4-P19 FIX ROUND, finding F-5. THE RECONSTRUCTED PATH IS STRICTER
+        // THAN THE WITH-RECORD PATH FOR A SCOUT, DELIBERATELY.
+        //
+        // The scout arm below discards a dirty scratch tree by design
+        // (PR-010: a scout is judged by its report and never pushes), and it
+        // reaches `finish` without ever probing cleanliness. That was
+        // reachable only by an operator who had the pool record in front of
+        // them. This phase made it reachable from a RECLAIM, where the
+        // record is the one thing that did not survive, and measured at head
+        // abde402: `teardown --task s1 --from-reconstructed` against a scout
+        // worktree holding ` M readme.md` and `?? important.md` exited 0 and
+        // removed the worktree, where the same fixture on the phase base
+        // exited 1 and left it standing. Plan criterion 4 states the refusal
+        // with no shape qualifier, so the plan is what is followed here.
+        //
+        // WHY NOT INSTEAD MAKE THE WITH-RECORD SCOUT PATH REFUSE TOO. That
+        // is a change to a decided scout policy (PR-010) which this phase
+        // does not own and which the plan does not ask for. The asymmetry is
+        // therefore REAL and is stated rather than smoothed over: the
+        // difference in force is the difference in what the operator knows.
+        // With the record present they are tearing down a scout they are
+        // tracking; arriving here from a reclaim they are recovering a fleet
+        // whose bookkeeping is already known to be incomplete, and the
+        // leavings in that tree may be the only copy.
+        //
+        // --salvage is NOT the escape, because salvage pushes (PR-010: a
+        // scout never pushes), so the remedy named is the one that works.
+        if (context.reconstructed) {
+            const scoutDirty = worktreeDirty(worktree);
+            if (!scoutDirty.ok) {
+                return { ok: false, reason: scoutDirty.reason };
+            }
+            if (scoutDirty.dirty) {
+                return {
+                    ok: false,
+                    reason: `scout worktree ${worktree} has uncommitted changes or untracked ` +
+                        `files and its pool record did not survive, so teardown is running ` +
+                        `on a reconstruction and refuses to discard them: copy anything ` +
+                        `worth keeping out of ${worktree}, then re-run once ` +
+                        `"git -C ${worktree} status --porcelain" is empty`,
+                };
+            }
+        }
+        // (a) A scout is judged by its report, never by its scratch tree.
+        if (!existsSync(reportPath(fleet, options.taskId))) {
+            return {
+                ok: false,
+                reason: `scout task ${options.taskId} has no report: ${reportPath(fleet, options.taskId)} ` +
+                    `is absent, and a scout is torn down only once it has reported`,
+            };
+        }
+        // Scout worktrees are scratch and scouts never push (PR-010), so the
+        // dirty tree is discarded. --delete-branch-force is deliberately NOT
+        // passed: --discard's plan-defined meaning is the dirty-tree
+        // override only, and a scout that committed to its scratch branch is
+        // refused rather than having those commits deleted silently, which is
+        // exactly the M1-P3 V-1 defect.
+        //
+        // CR-304: teardown answers that question ITSELF, before calling
+        // destroy, because the pool's own refusal advises passing
+        // --delete-branch-force, a flag teardown does not accept, so the
+        // operator was told to do something impossible through the command
+        // that printed it and the task could never reach closed. This
+        // refusal is a true no-op and names a route that works; the pool's
+        // gate stays behind it as the enforcer.
+        const tip = runGit(record.project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `refs/heads/${record.branchName}^{commit}`,
+        ]);
+        if (tip.status === 0 && tip.stdout.trim() !== record.baseSha) {
+            return {
+                ok: false,
+                reason: `scout task ${options.taskId} has commits on its scratch branch ` +
+                    `${record.branchName} (tip ${tip.stdout.trim()}, base ${record.baseSha}) and ` +
+                    `teardown never deletes committed work: copy or push them somewhere ` +
+                    `durable, then release the branch with "git -C ${record.project} update-ref ` +
+                    `refs/heads/${record.branchName} ${record.baseSha}" and re-run teardown`,
+            };
+        }
+        return finish(fleet, context, {
+            discard: true,
+            deleteBranchForce: false,
+            salvaged: false,
+        });
+    }
+    // (b) ship.
+    const dirty = worktreeDirty(worktree);
+    if (!dirty.ok) {
+        return { ok: false, reason: dirty.reason };
+    }
+    if (dirty.dirty && !options.salvage) {
+        return {
+            ok: false,
+            reason: `worktree ${worktree} has uncommitted changes or untracked files; commit ` +
+                `or land them first, or pass --salvage to commit them as ` +
+                `"${SALVAGE_PREFIX} ..." and push`,
+        };
+    }
+    const branchRef = `refs/heads/${record.branchName}`;
+    const landed = landedness(record.project, branchRef, context.defaultRef);
+    if (landed.kind === "inconclusive") {
+        return {
+            ok: false,
+            reason: `cannot determine whether ${record.branchName} is landed on ` +
+                `${record.remote}/${record.branch} (${landed.detail}); refusing`,
+        };
+    }
+    if (landed.kind === "unlanded") {
+        // M4-P19 criterion 5: the refusal NAMES THE TIP. That sha is the
+        // operator's recovery handle, exactly as the deleted-branch sha is on
+        // the success path (V-1), and it is the one fact that makes this
+        // refusal actionable: it says which commit is at risk, not merely
+        // that something is. It is named on every unlanded refusal rather
+        // than only the reconstructed one, so there is one message and not
+        // two that can drift apart.
+        const tip = runGit(record.project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `${branchRef}^{commit}`,
+        ]);
+        const tipSha = tip.status === 0 ? tip.stdout.trim() : "unresolvable";
+        return {
+            ok: false,
+            reason: `branch ${record.branchName} (tip ${tipSha}) is not landed on ` +
+                `${record.remote}/${record.branch}; land it before tearing the task down` +
+                (options.salvage ? " (--salvage rescues leavings, it never lands work)" : ""),
+        };
+    }
+    let salvaged = false;
+    if (dirty.dirty) {
+        const rescue = salvageLeavings(context);
+        if (!rescue.ok) {
+            return rescue;
+        }
+        salvaged = true;
+    }
+    // The landed judgement is what authorizes deleting the task branch
+    // (V-1's explicit flag, which src/pool.ts documents as coming from
+    // exactly here). After a salvage the branch carries the WIP commit,
+    // which is on the remote, so the local branch is safe to remove.
+    return finish(fleet, context, {
+        discard: false,
+        deleteBranchForce: true,
+        salvaged,
+    });
+}

package/dist/src/tuition.d.ts

@@ -0,0 +1,159 @@
+/**
+ * THE TUITION FEED AND THE MECHANISM INDEX (kernel plan M3, M3-P8; R-091).
+ *
+ * A tuition entry records one failure mode a delivery paid for. The MECHANISM
+ * INDEX is a PROJECTION of the `mechanisms[]` field of every entry in the
+ * feed, keyed by mechanism, and it is generated rather than authored. T-005 is
+ * why both halves exist and why they are one artifact rather than two: a rule
+ * M1-P3 paid for did not reach M1-P5, which reimplemented the same claim-file
+ * mechanism silently and produced the most severe defect found in M1, and a
+ * second hand-maintained copy of a rule is the state that produced it.
+ *
+ * THE TWO LAYERS ARE STRUCTURALLY DISTINCT, which is the plan's compaction
+ * model (step 2c). The index is the READ layer: dense, consulted at every
+ * dispatch under the `mechanism-lookup` obligation. The entries are the
+ * ARCHIVE layer: longer, read when a rule is disputed. `tuition index --check`
+ * is what keeps the first honest about the second.
+ *
+ * PATHS THIS MODULE READS ARE NOT ITS OWN (D-M3-27, the mechanism index's own
+ * row "Reading a path whose type is not established"). Every read goes through
+ * `readOperatorPath`, so a named pipe at an entry path is refused with the
+ * observed entry type instead of blocking the command forever.
+ */
+/** The generated index, relative to a tuition directory. */
+export declare const MECHANISM_INDEX_FILE = "mechanism-index.yaml";
+/** One mechanism as a tuition entry declares it. */
+export interface MechanismDeclaration {
+    mechanism: string;
+    rule: string;
+    siblings?: string[];
+    "machine-readable-form"?: {
+        path: string;
+        key: string;
+    };
+    evidence: string[];
+}
+/** One tuition entry, after schema validation. */
+export interface TuitionEntry {
+    kind: "tuition";
+    version: number;
+    id: string;
+    project: string;
+    date: string;
+    stage: string;
+    "kernel-relevant": boolean;
+    "what-happened": string;
+    lesson: string[];
+    mechanisms?: MechanismDeclaration[];
+    "structural-consequence"?: {
+        target: string;
+        status: "proposed" | "applied" | "ticketed";
+        change: string;
+        record?: string;
+    }[];
+    evidence: string[];
+}
+/** One row of the generated index, plus the entry it was projected from. */
+export interface IndexRow {
+    key: string;
+    name: string;
+    rule: string;
+    siblings?: string[];
+    "machine-readable-form"?: {
+        path: string;
+        key: string;
+    };
+    evidence: string[];
+    /** The tuition id this row came from. Not part of the rendered document. */
+    source: string;
+}
+/**
+ * THE KEY IS DERIVED FROM THE NAME, NEVER INVENTED: lowercase, every run of
+ * characters outside [a-z0-9] collapsed to one hyphen, ends trimmed. The same
+ * derivation `schemas/mechanism-index.schema.json` documents and M3-P6's
+ * registered test applies, stated once in code so the generator and the check
+ * cannot disagree about it.
+ */
+export declare function mechanismKey(name: string): string;
+export type EntryFileListing = {
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Every tuition ENTRY file in a directory, sorted by name.
+ *
+ * The generated index lives in the same directory and is EXCLUDED BY NAME: it
+ * is the projection's output, and a projection that reads its own output is a
+ * loop rather than a check. Anything that is not a `.yaml` file is ignored, so
+ * a README beside the feed is not an entry.
+ */
+export declare function listEntryFiles(directory: string): EntryFileListing;
+export type EntryLoad = {
+    ok: true;
+    entry: TuitionEntry;
+    body: string;
+} | {
+    ok: false;
+    reason: string;
+    diagnostics: string[];
+};
+/**
+ * Read, decode and schema-validate one tuition entry.
+ *
+ * THE RAW BYTES COME BACK WITH THE ENTRY, and that is not a convenience. An
+ * earlier version had `tuition add` call this and then read the same path a
+ * second time for the bytes to write. Two reads meant two independent
+ * refusals of a non-regular path, and a refusal that another refusal shadows
+ * cannot be witnessed: mutating either left the other rejecting the same
+ * input, which is exactly the shape T-018 records. One read, one
+ * classification, one guard.
+ */
+export declare function loadEntry(path: string): EntryLoad;
+export type Projection = {
+    ok: true;
+    rows: IndexRow[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Project the mechanism index out of a set of entries, sorted by key.
+ *
+ * A KEY CLAIMED BY TWO ENTRIES IS AN ERROR NAMING BOTH, never a silent
+ * first-wins. Two entries stating the same mechanism differently is exactly
+ * the divergence this document exists to prevent, and the projection cannot
+ * decide which of the two rules the project actually learned. The resolution
+ * is an editorial one: merge the two entries' rules by hand into whichever one
+ * owns the mechanism.
+ */
+export declare function projectIndex(entries: readonly TuitionEntry[]): Projection;
+/**
+ * Emit a YAML scalar, quoting only when a plain one would not round trip.
+ *
+ * THE CONDITION IS THE POINT: this generator's output is re-read by
+ * `--check`, so a scalar that YAML would decode as something other than the
+ * string handed in makes the projection disagree with itself. The reserved
+ * leading indicators, an embedded `: ` or ` #`, and a trailing colon are the
+ * cases; everything else is emitted plain, which is what keeps the document
+ * readable.
+ */
+export declare function yamlScalar(value: string): string;
+/** Render the index document. The bytes are what `--check` compares. */
+export declare function renderIndex(rows: readonly IndexRow[]): string;
+/**
+ * Compare a committed index document against a fresh projection.
+ *
+ * NAMES THE MECHANISM AND THE ENTRY IT CAME FROM, which is the criterion's
+ * letter (4): a reader of a red `--check` must be able to go straight to the
+ * file that changed. Both directions are reported, because a row DELETED from
+ * the feed and a row ADDED to it are different faults with the same symptom.
+ *
+ * The field comparison is over the DECODED values rather than the bytes, so a
+ * rewrap of a folded scalar is not reported as a rule change; a byte
+ * comparison is done by the caller afterwards and reported as formatting,
+ * which keeps "the rule changed" and "the file was hand-edited" apart.
+ */
+export declare function driftLines(committed: unknown, rows: readonly IndexRow[]): string[];