approval-md 0.0.1 → 0.2.0

package/dist/src/cli/log-sync.js

@@ -0,0 +1,849 @@
+/**
+ * `approval log sync` (APRV-125) — the pull half of the log ritual, as a verb.
+ *
+ * ## The ritual this replaces
+ *
+ * Bringing the committed log up to date used to be a hand-run sequence: stash
+ * the working `events.jsonl`, pull, pop the stash, hope. It was our own
+ * sanctioned runbook and it was dangerous three ways.
+ *
+ * 1. It rewound the working log through git while a daemon held it open for
+ *    append. That is fork 2 of 2026-08-20 (APRV-104's notes): a rewound file
+ *    under a live appender, and two chains where there was one.
+ * 2. It reached the approver's phone as `policy.edit` over a protected path —
+ *    a true label that told the human nothing about what was happening.
+ * 3. `git stash pop` can conflict, and on the day it did, it left conflict
+ *    markers inside the log file mid-ceremony.
+ *
+ * The precedent for turning it into a verb is `policy amend` after the seq 2
+ * incident: when a hand-ritual proves dangerous, it becomes deterministic code
+ * the gate can read.
+ *
+ * ## The sequence, and why each step is where it is
+ *
+ * Everything below runs inside ONE hold of the append lockfile. The lock is
+ * usually taken per-append; here it spans the whole operation, because an
+ * append landing between the snapshot and the restore is precisely the
+ * interleaving that forks a chain.
+ *
+ *  1. **Primary checkout only.** The committed log has one home. A worktree has
+ *     no business synchronizing it, and `log-sync-not-primary` says so.
+ *  2. **Verify before touching anything.** The working chain is walked and its
+ *     head recorded. Nothing is decided from a log that does not verify.
+ *  3. **Snapshot, not stash.** The working log is copied aside, atomically, to
+ *     a file inside `.approval/`. `git stash` is never used, and the log never
+ *     routes through git state mutation.
+ *  4. **Baseline.** The working LOG is set to the bytes git has at `HEAD`, so
+ *     the path is clean and a fast-forward merge can move over it. This is a
+ *     plain write of bytes we already hold, not a checkout: the snapshot from
+ *     step 3 is the only copy that matters and it is already safe. The queue
+ *     projection is deliberately NOT baselined here; see the section below.
+ *  5. **Fetch, then a fast-forward CHECK, then the projections are discarded,
+ *     then the merge.** A non-fast-forward is named and refused rather than
+ *     merged; a merge commit over a log is a merge of two hash chains, which is
+ *     not a thing that exists.
+ *  6. **Payload reconciliation, between the check and the merge.** See the
+ *     section below: untracked payload files the incoming tree also carries are
+ *     proved byte-identical and then removed, so the fast-forward has a clean
+ *     path to write them onto.
+ *  7. **Reconcile.** The committed chain must be a prefix of the snapshot, or
+ *     equal to it, or an extension of it. Anything else is a fork:
+ *     `log-diverged`, both heads, the first divergent seq, snapshot restored,
+ *     nothing else touched. The comparison is `core/log-reconcile.ts`, shared
+ *     with doctor's `log-drift` check.
+ *  8. **Projections are REBUILT, never copied back.** QUEUE.md is re-rendered
+ *     from the reconciled log and the index is reindexed from it. The direction
+ *     is load-bearing: a projection restored from before the pull would be a
+ *     screenshot asserting something the log no longer says.
+ *  9. **Post-verify**, and only then is the snapshot removed.
+ *
+ * Any failure at any step restores the snapshot before returning. The working
+ * log is never left in a half state, and the snapshot outlives every failure
+ * path that could need it.
+ *
+ * ## Untracked payload files, and why the merge used to stop on them (APRV-225)
+ *
+ * On 2026-09-02, after a records advance to seq 11361 merged, `log sync` in the
+ * primary checkout refused `log-sync-git-failed`: `git merge --ff-only` will not
+ * write over an untracked working-tree file, and the advance had committed 33
+ * payload files that this checkout already held untracked. Every one of them was
+ * byte-identical to the incoming blob — they are content-addressed, so identical
+ * by construction — and the only way forward was a hand step: move them aside,
+ * sync, put them back.
+ *
+ * That hand step is now step 6, on the same reasoning as the whole verb: when a
+ * hand-ritual is provably safe, it becomes deterministic code, and when it is
+ * NOT provably safe it refuses rather than guessing. The proof is per file, and
+ * every part of it runs before a single byte is removed:
+ *
+ * - the local file is **self-addressed** — SHA-256 of its bytes is its own name
+ *   (the store writes RFC 8785 canonical bytes, so this holds for anything
+ *   `storePayload` wrote); the `{"$ref": …}` reference form is the store's
+ *   documented exception and is carried on byte equality alone.
+ * - the local bytes **equal the incoming blob**, compared as bytes read through
+ *   `git show`. Not git's blob id: that is SHA-1 over a header plus the content
+ *   and has nothing to do with the SHA-256 content address the store uses, so
+ *   comparing names to blob ids would be comparing two different hashes of two
+ *   different things and calling the disagreement a fork.
+ *
+ * A payload that fails either test refuses `log-sync-payload-mismatch`, naming
+ * the file. A payload is the material evidence an approval bound to: two
+ * different versions of one is not a merge conflict to be resolved, it is a
+ * question about which bytes a human said yes to. Nothing is merged, nothing is
+ * appended, and the working tree is left as it was found.
+ *
+ * A local payload the incoming tree does **not** carry is not this verb's
+ * business and is not touched: it blocks nothing, and it is very likely a
+ * payload this checkout has recorded and not yet advanced.
+ *
+ * ## The queue projection is disposable, and discarded LATE (APRV-292)
+ *
+ * On 2026-09-07, after a records pull request that carried `.approval/QUEUE.md`
+ * as well as the log, `log sync` refused twice with git's "local changes to
+ * .approval/QUEUE.md would be overwritten", the second time immediately after a
+ * hand-run `git checkout -- .approval/QUEUE.md`. The hand step was not wrong,
+ * it was just early: the running daemon re-rendered the projection again before
+ * the fast-forward reached it.
+ *
+ * The two files are exposed to different writers, which is why they are handled
+ * differently. Nothing can append to the log while this verb runs — sync holds
+ * the append lock for the whole ceremony, and every appender takes it. Nothing
+ * at all holds the projection: `channels/render-queue.ts`'s `writeQueue` renders
+ * and renames `QUEUE.md` on every daemon tick, under no lock, by design (the
+ * TTL countdowns in it move even when the log does not, so the file is rewritten
+ * whether or not anything was appended). A
+ * projection baselined at step 4 can therefore be dirty again by the time `git
+ * merge --ff-only` looks at it, and a stale render is enough to stop a pull of
+ * the log.
+ *
+ * So the projection is not baselined with the log. It is **discarded** as the
+ * last statement before the merge, which is the narrowest window this verb can
+ * offer, and when the merge fails with a projection dirty again the discard and
+ * the merge are retried exactly once. What is discarded is a rendering of the
+ * log, rebuilt at step 8 from the reconciled log, so there is nothing here to
+ * weigh: a projection carries no truth of its own and losing the last render
+ * costs nothing but the render. A projection git neither has at `HEAD` nor
+ * carries in the incoming tree is left alone, because it can stop no merge —
+ * `.approval/index.sqlite` is gitignored, and clearing a cache that blocks
+ * nothing would only make the next reader rebuild it.
+ *
+ * The snapshot the queue still gets is for the REFUSAL path alone: a refusal
+ * leaves the whole working tree as it was found, log and projection together.
+ * No success path ever copies it back — see step 8.
+ *
+ * ## This verb appends no event
+ *
+ * The log records decisions with real-world consequence. A fast-forward pull of
+ * the file the log lives in is housekeeping on the container, not a decision
+ * about the world, and an event for it would be the log narrating its own
+ * filesystem. Nothing here calls `appendEvent`, and the tests pin that the head
+ * seq is unchanged by a successful sync (SPEC §10.1, amended APRV-125).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { writeQueue } from "../channels/render-queue.js";
+import { withAppendLock } from "../core/log.js";
+import { compareChains, describeHead, } from "../core/log-reconcile.js";
+import { isPayloadHash } from "../core/payload.js";
+import { payloadStoreDirFor } from "../core/payload-store.js";
+import { reindex } from "../core/reindex.js";
+import { verify } from "../core/verify.js";
+import { currentBranch, failureText, git, outputLines, primaryCheckout, repoPath, showBlob, } from "./git-scope.js";
+import { DEFAULT_INDEX_PATH, DEFAULT_LOG_PATH } from "./paths.js";
+import { DEFAULT_QUEUE_PATH } from "./render.js";
+/**
+ * The steps, named. They are a public shape because the failure-injection hook
+ * takes one, and because a refusal says which step it stopped at.
+ */
+export const LOG_SYNC_STEPS = [
+    "primary",
+    "verify",
+    "snapshot",
+    "baseline",
+    "fetch",
+    "ff-check",
+    "payloads",
+    "merge",
+    "reconcile",
+    "projections",
+    "post-verify",
+];
+/**
+ * Machine-readable refusal codes. Frozen public API, printed in the help.
+ *
+ * `log-diverged` is the one that matters and the one the runbook is written
+ * for: it is the only outcome here that means a human has to reconcile two
+ * chains by hand, because nothing in this codebase may do it for them.
+ */
+export const LOG_SYNC_REFUSAL_CODES = [
+    "log-sync-not-primary",
+    "log-sync-no-branch",
+    "log-sync-unverified",
+    "log-sync-not-fast-forward",
+    "log-sync-payload-mismatch",
+    "log-diverged",
+    "log-sync-locked",
+    "log-sync-git-failed",
+    "log-sync-projection-failed",
+    "log-sync-restore-failed",
+    "log-sync-io",
+];
+/** Where the snapshot of a file lives while the ritual runs. */
+function snapshotPathFor(path) {
+    return `${path}.sync-snapshot`;
+}
+function detail(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Place `bytes` at `path` atomically: write a sibling temp file, then rename.
+ *
+ * A rename within a directory is atomic on every filesystem this runtime
+ * supports, so a reader sees the whole previous file or the whole new one. A
+ * log half-overwritten by a crash mid-restore would be the exact damage this
+ * verb exists to prevent.
+ */
+function placeAtomically(path, bytes) {
+    const temp = `${path}.tmp-${String(process.pid)}-${String(Date.now())}`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(temp, bytes, { flag: "wx" });
+    renameSync(temp, path);
+}
+/** The bytes at `path`, or `null` when there is no such file. */
+function readIfPresent(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return null;
+        throw cause;
+    }
+}
+/**
+ * `approval log sync`, as a function.
+ *
+ * The CLI wrapper does argv, exit codes, and formatting; everything that could
+ * damage a log is here, in one sequence, with one restore path.
+ */
+export function logSync(options) {
+    const { cwd, hooks } = options;
+    const remote = options.remote ?? "origin";
+    /**
+     * Arrive at a step: run any injected interference for it, and answer whether
+     * a failure was injected before it. Both seams are test-only and both are
+     * inert unless a caller passed `hooks`.
+     */
+    const enter = (step) => {
+        if (hooks?.interfere?.step === step)
+            hooks.interfere.run();
+        return hooks?.failBefore === step;
+    };
+    // ---- step 1: the primary checkout, before anything is read ----
+    if (enter("primary")) {
+        return {
+            ok: false,
+            code: "log-sync-io",
+            message: "injected failure before the primary-checkout check",
+            step: "primary",
+            restored: true,
+        };
+    }
+    const primary = primaryCheckout(cwd);
+    if (!primary.ok) {
+        return {
+            ok: false,
+            code: "log-sync-not-primary",
+            message: `log sync runs in the PRIMARY checkout only: ${primary.reason}. The committed log has one home, and a worktree that synchronized it would be advancing a chain it is not the writer of. Run this in ${primary.primary ?? "the primary checkout"}.`,
+            step: "primary",
+            restored: true,
+        };
+    }
+    const root = primary.root;
+    const logPath = join(root, DEFAULT_LOG_PATH);
+    const queuePath = join(root, DEFAULT_QUEUE_PATH);
+    const indexPath = join(root, DEFAULT_INDEX_PATH);
+    const branch = options.branch ?? currentBranch(root);
+    if (branch === null) {
+        return {
+            ok: false,
+            code: "log-sync-no-branch",
+            message: `HEAD in ${root} is detached, so there is no branch to fast-forward. Check out the branch the log lives on and run this again.`,
+            step: "primary",
+            restored: true,
+        };
+    }
+    // Everything from here runs under the append lock: no daemon, no hook, and no
+    // other CLI verb can append while the working log is moved aside.
+    const held = withAppendLock(logPath, () => syncUnderLock({ cwd, root, logPath, queuePath, indexPath, remote, branch, enter }));
+    if (held.ok)
+        return held.value;
+    return {
+        ok: false,
+        code: held.error.code === "lock-timeout" ? "log-sync-locked" : "log-sync-io",
+        message: held.error.code === "lock-timeout"
+            ? `${held.error.message}. Another writer holds the append lock; sync takes it for the WHOLE operation, because an append landing mid-sync is how a chain forks. Stop the daemon (or wait for the append to finish) and run this again.`
+            : held.error.message,
+        step: "primary",
+        restored: true,
+    };
+}
+/**
+ * The ceremony proper, with the lock already held.
+ *
+ * Written as one linear sequence on purpose. Splitting it into a step-runner
+ * would hide the ordering, and the ordering IS the safety property.
+ */
+function syncUnderLock(ctx) {
+    const { root, logPath, queuePath, indexPath, remote, branch, enter } = ctx;
+    // ---- step 2: verify before touching anything ----
+    if (enter("verify")) {
+        return refuseBefore("verify", "log-sync-io", "injected failure before the pre-verify");
+    }
+    const before = verify(logPath);
+    if (before.status !== "clean") {
+        return {
+            ok: false,
+            code: "log-sync-unverified",
+            message: before.status === "torn-tail"
+                ? `${logPath} ends without a newline: the final record is truncated, the signature of a crashed write. Sync touches nothing until a human has accounted for it; run \`approval log verify\`.`
+                : `${logPath} does not verify (${before.reason}${before.firstBadSeq === null ? "" : ` at seq ${String(before.firstBadSeq)}`}): ${before.message}. Nothing is synchronized from a log that does not verify.`,
+            step: "verify",
+            restored: true,
+        };
+    }
+    const headBefore = before.head;
+    // ---- step 3: the snapshot ----
+    if (enter("snapshot")) {
+        return refuseBefore("snapshot", "log-sync-io", "injected failure before the snapshot");
+    }
+    const guarded = [];
+    try {
+        for (const { path, disposable } of [
+            { path: logPath, disposable: false },
+            { path: queuePath, disposable: true },
+        ]) {
+            const snapshot = snapshotPathFor(path);
+            rmSync(snapshot, { force: true });
+            const existed = existsSync(path);
+            // A plain copy rather than a rename: the original stays in place until
+            // the baseline step deliberately replaces it, so a crash between the two
+            // leaves the working file untouched rather than absent.
+            if (existed)
+                copyFileSync(path, snapshot);
+            guarded.push({ path, snapshot, existed, disposable });
+        }
+    }
+    catch (cause) {
+        restoreAll(guarded);
+        return {
+            ok: false,
+            code: "log-sync-io",
+            message: `the snapshot could not be taken: ${detail(cause)}. Nothing was pulled and nothing was changed.`,
+            step: "snapshot",
+            restored: true,
+        };
+    }
+    /**
+     * Payload files this run removed so the fast-forward had a clean path, with
+     * the bytes they held. Every one of them was proved identical to the incoming
+     * blob before it was removed, so putting them back is putting back exactly
+     * what was found — and {@link abort} does, on every failure after step 6.
+     */
+    const removedPayloads = [];
+    /**
+     * Put everything back and refuse. Every failure path below goes through here,
+     * which is what makes "the working log is never left in a half state" a
+     * property of the code rather than of the author's diligence.
+     */
+    const abort = (step, code, message, extra = {}) => {
+        restorePayloads(removedPayloads);
+        const restored = restoreAll(guarded);
+        if (!restored) {
+            return {
+                ok: false,
+                code: "log-sync-restore-failed",
+                message: `${message} — AND THE SNAPSHOT COULD NOT BE PUT BACK. The working log may not be what you left; the snapshot is still at ${snapshotPathFor(logPath)} and nothing has removed it. Copy it back by hand and run \`approval log verify\` before anything appends.`,
+                step,
+                restored: false,
+                ...extra,
+            };
+        }
+        return { ok: false, code, message, step, restored: true, ...extra };
+    };
+    // ---- step 4: the baseline, so a fast-forward can move over the log ----
+    //
+    // The LOG only. It can be baselined this early because nothing can dirty it
+    // between here and the merge: this verb holds the append lock, and appending
+    // is the only thing that writes it. The projections have no such protection
+    // and are discarded at the merge instead (APRV-292).
+    if (enter("baseline")) {
+        return abort("baseline", "log-sync-io", "injected failure before the baseline");
+    }
+    try {
+        for (const entry of guarded) {
+            if (entry.disposable)
+                continue;
+            const blob = showBlob(root, "HEAD", repoPath(root, entry.path));
+            if (blob === null)
+                rmSync(entry.path, { force: true });
+            else
+                placeAtomically(entry.path, blob);
+        }
+    }
+    catch (cause) {
+        return abort("baseline", "log-sync-io", `the working log could not be set to its committed bytes: ${detail(cause)}. Nothing was pulled.`);
+    }
+    const commitBefore = revision(root, "HEAD");
+    // ---- step 5a: fetch ----
+    if (enter("fetch")) {
+        return abort("fetch", "log-sync-git-failed", "injected failure before the fetch");
+    }
+    const fetched = git(["fetch", remote, branch], root);
+    if (!fetched.ok) {
+        return abort("fetch", "log-sync-git-failed", `\`git fetch ${remote} ${branch}\` failed: ${failureText(fetched)}. Nothing was pulled and the working log is back as it was.`, { quote: outputLines(fetched.stderr, fetched.stdout) });
+    }
+    // ---- step 5b: the fast-forward CHECK, before the merge is attempted ----
+    if (enter("ff-check")) {
+        return abort("ff-check", "log-sync-git-failed", "injected failure before the fast-forward check");
+    }
+    const target = revision(root, "FETCH_HEAD");
+    const ancestor = git(["merge-base", "--is-ancestor", "HEAD", "FETCH_HEAD"], root);
+    if (!ancestor.ok) {
+        return abort("ff-check", "log-sync-not-fast-forward", `${remote}/${branch} (${short(target)}) is not a fast-forward of HEAD (${short(commitBefore)}): this checkout carries commits the remote does not. Sync only fast-forwards, because a merge commit over ${DEFAULT_LOG_PATH} is a merge of two hash chains, and chains do not merge. Land your commits first (\`approval log advance\`), then sync.`);
+    }
+    // ---- step 6: untracked payload files the incoming tree also carries ----
+    //
+    // Here and not earlier: the fast-forward is known to be possible, so removing
+    // a file the merge is about to write is a step towards a merge that WILL run.
+    // Here and not later: `git merge --ff-only` is what stops on these, so they
+    // have to be gone before it is asked.
+    if (enter("payloads")) {
+        return abort("payloads", "log-sync-io", "injected failure before the payload reconciliation");
+    }
+    const overlapping = overlappingPayloads(root, logPath, "FETCH_HEAD");
+    if (!overlapping.ok) {
+        return abort("payloads", "log-sync-git-failed", overlapping.message, { quote: overlapping.quote });
+    }
+    // Two passes, and the order is the safety property: every file is proved
+    // before any file is removed, so a mismatch in the last one cannot have
+    // deleted the first.
+    const confirmed = [];
+    for (const relative of overlapping.paths) {
+        const checked = checkPayload(root, relative, "FETCH_HEAD");
+        if (!checked.ok) {
+            return abort("payloads", "log-sync-payload-mismatch", checked.message);
+        }
+        confirmed.push({ relative, path: join(root, relative), bytes: checked.bytes });
+    }
+    for (const entry of confirmed) {
+        try {
+            rmSync(entry.path, { force: true });
+            removedPayloads.push({ path: entry.path, bytes: entry.bytes });
+        }
+        catch (cause) {
+            return abort("payloads", "log-sync-io", `the untracked payload ${entry.relative} could not be moved out of the fast-forward's way: ${detail(cause)}. Nothing was pulled.`);
+        }
+    }
+    const payloadsReconciled = confirmed.length;
+    // ---- step 5c: the projections are discarded, and then the merge ----
+    //
+    // The discard is the last statement before the merge, and that placement is
+    // the fix APRV-292 is: a projection has no lock, so the daemon can re-render
+    // it at any instant, and every statement between the discard and the merge is
+    // a window in which a stale render stops a pull of the log.
+    if (enter("merge")) {
+        return abort("merge", "log-sync-git-failed", "injected failure before the merge");
+    }
+    const disposable = disposableProjections(root, [queuePath, indexPath]);
+    const discarded = discardProjections(root, disposable);
+    if (!discarded.ok)
+        return abort("merge", "log-sync-io", discarded.message);
+    let merged = git(["merge", "--ff-only", "FETCH_HEAD"], root);
+    let retried = false;
+    if (!merged.ok && dirtyProjections(root, disposable)) {
+        // The renderer beat the merge to the file. One retry, and only for this
+        // reason: any other failure is a real one, and repeating it would refuse
+        // twice as slowly.
+        retried = true;
+        const again = discardProjections(root, disposable);
+        if (!again.ok)
+            return abort("merge", "log-sync-io", again.message);
+        merged = git(["merge", "--ff-only", "FETCH_HEAD"], root);
+    }
+    if (!merged.ok) {
+        const racing = retried && dirtyProjections(root, disposable);
+        return abort("merge", "log-sync-git-failed", `\`git merge --ff-only FETCH_HEAD\` failed: ${failureText(merged)}. The working log is back as it was.${racing
+            ? ` ${disposable.join(", ")} was dirty again on both attempts: something is rewriting the projection faster than the fast-forward can run. Stop the writer (usually the daemon) and run this again.`
+            : ""}`, { quote: outputLines(merged.stderr, merged.stdout) });
+    }
+    const commitAfter = revision(root, "HEAD");
+    // ---- step 6: reconcile ----
+    if (enter("reconcile")) {
+        return abort("reconcile", "log-sync-io", "injected failure before the reconcile");
+    }
+    const snapshotText = textOf(snapshotPathFor(logPath));
+    const committedText = textOf(logPath);
+    const compared = compareChains({ label: `the working log ${logPath}`, text: snapshotText }, { label: `the committed log at ${short(commitAfter)}`, text: committedText });
+    if (!compared.ok) {
+        return abort("reconcile", "log-sync-unverified", compared.message);
+    }
+    const drift = compared.drift;
+    if (drift.relation === "diverged") {
+        return abort("reconcile", "log-diverged", `the committed log and the working log are two different chains. They agree through seq ${String((drift.firstDivergentSeq ?? 1) - 1)} and part at seq ${String(drift.firstDivergentSeq)}: working head ${describeHead(drift.workingHead)}, committed head ${describeHead(drift.committedHead)}. Nothing was merged and nothing was re-chained — re-chaining is fabrication, and hash chains do not survive a merge. Your working log has been restored exactly as it was found; the pull DID advance the git checkout to ${short(commitAfter)}. A human has to decide which chain is the log.`, { drift });
+    }
+    // A prefix relationship in either direction is safe, and the two directions
+    // are handled differently for one reason: whichever chain is LONGER contains
+    // the other whole, so adopting it extends and never rewinds.
+    //   ahead  — the committed baseline is a prefix of ours: put the snapshot back.
+    //   behind — the pull brought records we did not have: keep the pulled file.
+    //   equal  — nothing to do; the file on disk is already the chain.
+    let restored = false;
+    if (drift.relation === "ahead") {
+        const snapshot = readIfPresent(snapshotPathFor(logPath));
+        if (snapshot === null) {
+            return abort("reconcile", "log-sync-io", `the snapshot at ${snapshotPathFor(logPath)} disappeared before it could be restored.`);
+        }
+        try {
+            placeAtomically(logPath, snapshot);
+            restored = true;
+        }
+        catch (cause) {
+            return abort("reconcile", "log-sync-io", `the snapshot could not be restored over ${logPath}: ${detail(cause)}.`);
+        }
+    }
+    // ---- step 7: projections, REBUILT from the reconciled log ----
+    //
+    // Rebuilt, never copied back from the snapshot taken at step 3: that snapshot
+    // is the refusal path's, and a projection restored on a SUCCESS would be a
+    // screenshot asserting something the log no longer says.
+    if (enter("projections")) {
+        return abort("projections", "log-sync-projection-failed", "injected failure before the projection rebuild");
+    }
+    const rendered = writeQueue(logPath, queuePath, { policy: { dir: root } }, new Date().toISOString());
+    if (!rendered.ok) {
+        return abort("projections", "log-sync-projection-failed", `the queue projection could not be rebuilt from the reconciled log (${rendered.code}): ${rendered.message}`);
+    }
+    let index = "absent";
+    if (existsSync(indexPath)) {
+        const reindexed = reindex(logPath, indexPath, { force: true });
+        if (!reindexed.ok) {
+            return abort("projections", "log-sync-projection-failed", `the index could not be rebuilt from the reconciled log (${reindexed.error.code}): ${reindexed.error.message}`);
+        }
+        index = "rebuilt";
+    }
+    // ---- step 8: post-verify, and only then is the snapshot let go ----
+    if (enter("post-verify")) {
+        return abort("post-verify", "log-sync-unverified", "injected failure before the post-verify");
+    }
+    const after = verify(logPath);
+    if (after.status !== "clean") {
+        return abort("post-verify", "log-sync-unverified", `the reconciled log does not verify (${after.status === "torn-tail" ? "torn-tail" : after.reason}). The working log has been restored to what it was before the sync.`);
+    }
+    for (const entry of guarded)
+        rmSync(entry.snapshot, { force: true });
+    return {
+        ok: true,
+        report: {
+            root,
+            logPath,
+            remote,
+            branch,
+            commitBefore,
+            commitAfter,
+            pulled: countCommits(root, commitBefore, commitAfter),
+            headBefore,
+            headAfter: after.head,
+            relation: drift.relation,
+            ahead: drift.ahead,
+            behind: drift.behind,
+            restored,
+            payloadsReconciled,
+            queue: { path: rendered.path, bytes: rendered.bytes },
+            index,
+        },
+    };
+}
+/**
+ * Put back every payload file this run removed.
+ *
+ * Deliberately quiet, and deliberately not part of `restoreAll`'s success
+ * answer: each of these was proved byte-identical to a blob the remote holds
+ * before it was removed, so the worst case of a failure here is a file that has
+ * to be checked out again, never a byte anyone can no longer obtain. The log's
+ * restore is the one that must be loud, and it stays the one that is.
+ */
+function restorePayloads(removed) {
+    for (const entry of removed) {
+        if (existsSync(entry.path))
+            continue;
+        try {
+            placeAtomically(entry.path, entry.bytes);
+        }
+        catch {
+            // See above: recoverable from the remote, and never worth masking the
+            // refusal that brought us here.
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// The projections in the fast-forward's way (APRV-292)
+// ---------------------------------------------------------------------------
+/**
+ * The projections a fast-forward could collide with, as repo-relative paths.
+ *
+ * A projection git neither has at `HEAD` nor carries in the incoming tree can
+ * stop no merge, so it is not in this list and nothing below touches it. That
+ * is the whole reason `.approval/index.sqlite` — gitignored, a cache, and
+ * potentially large — is passed in here rather than special-cased: whether it
+ * is disposable in the git sense is a question about the repository, and the
+ * repository is asked.
+ */
+function disposableProjections(root, paths) {
+    const found = [];
+    for (const path of paths) {
+        const relative = repoPath(root, path);
+        // A projection outside the repository is not something a fast-forward can
+        // collide with either.
+        if (relative.startsWith(".."))
+            continue;
+        if (!carries(root, "HEAD", relative) && !carries(root, "FETCH_HEAD", relative))
+            continue;
+        found.push(relative);
+    }
+    return found;
+}
+/** Does `rev` carry a blob at `relative`? `-e` asks and reads nothing. */
+function carries(root, rev, relative) {
+    return git(["cat-file", "-e", `${rev}:${relative}`], root).ok;
+}
+/**
+ * Throw the working copy of every disposable projection away.
+ *
+ * "Throw away" is a projection's whole relationship to this verb. It is a
+ * rendering of the log, it is rebuilt from the reconciled log two steps later,
+ * and whatever the renderer wrote into it a millisecond ago says nothing the
+ * log does not. So there is nothing to weigh here and no proof to demand — the
+ * opposite of the payload reconciliation above, where every byte is evidence
+ * and every removal is proved first.
+ *
+ * The bytes written are the ones git has at `HEAD`, which leaves the path clean
+ * for the merge. A projection only the incoming tree carries has no `HEAD`
+ * bytes and is removed instead: an existing untracked file is the other thing
+ * `git merge --ff-only` refuses to write over.
+ */
+function discardProjections(root, relatives) {
+    for (const relative of relatives) {
+        const path = join(root, relative);
+        try {
+            const blob = showBlob(root, "HEAD", relative);
+            if (blob === null)
+                rmSync(path, { force: true });
+            else
+                placeAtomically(path, blob);
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                message: `the projection ${relative} could not be moved out of the fast-forward's way: ${detail(cause)}. Nothing was pulled and the working log is back as it was.`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Is any disposable projection dirty in the working tree right now?
+ *
+ * Asked after a failed merge, to tell the one failure worth retrying (the
+ * renderer wrote the file again in the microseconds since the discard) from
+ * every other failure, which a retry would only repeat.
+ */
+function dirtyProjections(root, relatives) {
+    if (relatives.length === 0)
+        return false;
+    const status = git(["status", "--porcelain", "-z", "--", ...relatives], root);
+    return status.ok && pathLines(status.stdout).length > 0;
+}
+/**
+ * Repo-relative paths out of a NUL-separated git listing.
+ *
+ * `-z` on both listings, so the two sets are spelled the same way. Without it
+ * git quotes any path it considers unusual, and a quoted name on one side would
+ * simply fail to match its unquoted self on the other — dropping the file out of
+ * the intersection, which is to say handling it by not noticing it.
+ */
+function pathLines(stdout) {
+    return stdout.split("\0").filter((line) => line.length > 0);
+}
+/**
+ * Untracked, non-ignored payload files that `rev` also carries.
+ *
+ * The intersection is the whole point. An untracked payload the incoming tree
+ * does not have blocks nothing and is left alone; a tracked one is git's
+ * business and rides the fast-forward like any other file. What is left is
+ * exactly the set `git merge --ff-only` refuses to write over.
+ *
+ * `--exclude-standard` is on: an ignored file is not one git would refuse to
+ * overwrite, so including it here would make sync stricter than the merge it is
+ * clearing the way for.
+ */
+function overlappingPayloads(root, logPath, rev) {
+    const storeRelative = repoPath(root, payloadStoreDirFor(logPath));
+    // A store outside the repository is not something a fast-forward can collide
+    // with, so there is nothing here to reconcile.
+    if (storeRelative.startsWith(".."))
+        return { ok: true, paths: [] };
+    const untracked = git(["ls-files", "--others", "--exclude-standard", "-z", "--", storeRelative], root);
+    if (!untracked.ok) {
+        return {
+            ok: false,
+            message: `\`git ls-files --others\` over ${storeRelative} failed: ${failureText(untracked)}. Nothing was pulled and the working log is back as it was.`,
+            quote: outputLines(untracked.stderr, untracked.stdout),
+        };
+    }
+    const local = new Set(pathLines(untracked.stdout));
+    if (local.size === 0)
+        return { ok: true, paths: [] };
+    const incoming = git(["ls-tree", "-r", "--name-only", "-z", rev, "--", storeRelative], root);
+    if (!incoming.ok) {
+        return {
+            ok: false,
+            message: `\`git ls-tree ${rev}\` over ${storeRelative} failed: ${failureText(incoming)}. Nothing was pulled and the working log is back as it was.`,
+            quote: outputLines(incoming.stderr, incoming.stdout),
+        };
+    }
+    const carried = new Set(pathLines(incoming.stdout));
+    return { ok: true, paths: [...local].filter((path) => carried.has(path)).sort() };
+}
+/** SHA-256 of some bytes, lowercase hex: the store's content address. */
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Is this the store's `{"$ref": "<uri>"}` form, and nothing else? */
+function isReferenceForm(bytes) {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === "$ref" && typeof value.$ref === "string";
+}
+/**
+ * Prove one untracked payload safe to remove, and answer the bytes it holds.
+ *
+ * Two independent facts, both required, neither inferred from the other:
+ * the file is self-addressed, and its bytes are the incoming bytes. The second
+ * is what makes removal safe; the first is what catches a local file that was
+ * already wrong before any of this started, so that sync is not the step that
+ * quietly discards it.
+ */
+function checkPayload(root, relative, rev) {
+    const path = join(root, relative);
+    const name = relative.slice(relative.lastIndexOf("/") + 1);
+    const stem = name.endsWith(".json") ? name.slice(0, -".json".length) : name;
+    const local = readIfPresent(path);
+    if (local === null) {
+        return {
+            ok: false,
+            message: `the untracked payload ${relative} disappeared while sync was reading it. Nothing was pulled and the working log is back as it was.`,
+        };
+    }
+    if (!isPayloadHash(stem)) {
+        return {
+            ok: false,
+            message: `${relative} sits in the payload store and is not named by a payload hash (SHA-256, lowercase hex). The store is addressed by hash and nothing else, so sync will not clear this file out of a fast-forward's way. Move it somewhere that is not the payload store and run \`approval log sync\` again.`,
+        };
+    }
+    const digest = sha256(local);
+    if (digest !== stem && !isReferenceForm(local)) {
+        return {
+            ok: false,
+            message: `the untracked payload ${relative} does not hash to its own name: its bytes are ${digest}. A payload file is the material evidence an approval bound to, and one that is not what it says it is has to be accounted for by a human before anything overwrites it. Nothing was pulled, nothing was appended, and the working tree is as you left it.`,
+        };
+    }
+    const incoming = showBlob(root, rev, relative);
+    if (incoming === null) {
+        return {
+            ok: false,
+            message: `the incoming commit lists ${relative} and git could not read its bytes. Nothing was pulled and the working log is back as it was.`,
+        };
+    }
+    if (!incoming.equals(local)) {
+        return {
+            ok: false,
+            message: `the untracked payload ${relative} is not the payload the incoming commit carries: local bytes hash to ${digest}, incoming bytes to ${sha256(incoming)}. Two different versions of one content-addressed payload is a question about which bytes an approval bound to, not a merge conflict, so sync removes neither. Nothing was pulled, nothing was appended, and the working tree is as you left it.`,
+        };
+    }
+    return { ok: true, bytes: local };
+}
+/** A refusal from before the snapshot exists: there is nothing to put back. */
+function refuseBefore(step, code, message) {
+    return { ok: false, code, message, step, restored: true };
+}
+/**
+ * Put every guarded file back exactly as it was found, and drop the snapshots.
+ *
+ * Returns false when any file could not be restored, which is the one outcome
+ * that must never be reported quietly: the caller turns it into
+ * `log-sync-restore-failed` and leaves the snapshot on disk.
+ */
+function restoreAll(guarded) {
+    let ok = true;
+    for (const entry of guarded) {
+        try {
+            if (entry.existed) {
+                const bytes = readIfPresent(entry.snapshot);
+                if (bytes === null) {
+                    ok = false;
+                    continue;
+                }
+                placeAtomically(entry.path, bytes);
+            }
+            else {
+                rmSync(entry.path, { force: true });
+            }
+        }
+        catch {
+            ok = false;
+            continue;
+        }
+        try {
+            rmSync(entry.snapshot, { force: true });
+        }
+        catch {
+            // The file is back; a leftover snapshot is untidy, never unsafe.
+        }
+    }
+    return ok;
+}
+/** A file's text, or the empty string when it is not there. */
+function textOf(path) {
+    const bytes = readIfPresent(path);
+    return bytes === null ? "" : bytes.toString("utf8");
+}
+/** `git rev-parse <rev>`, or the empty string. */
+function revision(root, rev) {
+    const result = git(["rev-parse", rev], root);
+    return result.ok ? result.stdout.trim() : "";
+}
+/** How many commits `to` carries beyond `from`. */
+function countCommits(root, from, to) {
+    if (from.length === 0 || to.length === 0 || from === to)
+        return 0;
+    const result = git(["rev-list", "--count", `${from}..${to}`], root);
+    if (!result.ok)
+        return 0;
+    const parsed = Number.parseInt(result.stdout.trim(), 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/** A commit, as a human reads one. */
+export function short(commit) {
+    return commit.length === 0 ? "none" : commit.slice(0, 12);
+}
+//# sourceMappingURL=log-sync.js.map