@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/staging/snapshot/snapshot.js

@@ -0,0 +1,196 @@
+/**
+ * The undo snapshot: the bytes `archive` is about to overwrite, parked inside
+ * the feature directory so they travel with it into `features/archive/`.
+ *
+ * Separate from the commit because the merge is not invertible — a MODIFIED
+ * requirement's previous text appears nowhere in the delta, and a landscape
+ * rewritten by hand since cannot be un-rewritten by re-reading one. `unarchive`
+ * puts bytes back; it does not recompute them. Nothing on the commit path reads
+ * this module: only `archive` writes a snapshot and only `unarchive` honours one.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { repoPath } from "../../envelope/json.js";
+import { acrossRename, resolvePortableFileInsideLexically, UnsafePathError } from "../../kernel/path-safety.js";
+// Every `isRecord` below guards the manifest loam itself wrote, read back inside
+// a REFUSAL path — `../lock.ts` records why that is where a thrown `TypeError`
+// costs the most.
+import { isRecord } from "../../kernel/records.js";
+import { isDigest, sha256 } from "../writes.js";
+import { message, quietRm } from "../commit.js";
+import { isReadableSnapshotVersion, preImageRel, SNAPSHOT_DIR, SNAPSHOT_MANIFEST, SNAPSHOT_VERSION, snapshotDir, } from "./manifest.js";
+/** A snapshot directory that must not be replaced, because it is the only copy of the true pre-images. */
+export class SnapshotClobberError extends Error {
+    dir;
+    name = "SnapshotClobberError";
+    constructor(dir, detail) {
+        super(`${dir} already holds an undo snapshot that does NOT match the living docs (${detail}) — a previous archive of ` +
+            `this feature wrote to the living docs and never took them back, and these are the only copies of what they ` +
+            `said before. Overwriting them would make that merge permanent and unreportable. Run \`loam archive\` again ` +
+            `after restoring the living docs from version control, or delete ${SNAPSHOT_DIR}/ if you know the merge never landed.`);
+        this.dir = dir;
+    }
+}
+export async function writeSnapshot(request) {
+    const { featureDir, docsDir, staged } = request;
+    const { featureId, dirName } = request.feature;
+    const dir = snapshotDir(featureDir);
+    await assertSnapshotReplaceable(request);
+    // A leftover from a rolled-back run would describe a merge that never happened.
+    await quietRm(dir);
+    const files = [];
+    for (const s of staged) {
+        // The feature's own documents by where the move leaves them; everything
+        // else by where it is written (`SnapshotRequest.movesTo` says why).
+        const rel = repoPath(docsDir, acrossRename(s.write.path, featureDir, request.movesTo));
+        // services/ entries are re-keyed by (service, artifact) so they survive the
+        // service directory moving between archive and unarchive; the literal path
+        // is still recorded — it keys the pre-image below, and it is the fallback.
+        const key = request.serviceKeyOf(rel);
+        files.push({
+            path: rel,
+            ...key,
+            existed: s.before !== null,
+            after: sha256(s.content ?? Buffer.alloc(0)),
+            before: s.before === null ? null : sha256(s.before),
+        });
+        if (s.before !== null) {
+            // Under the suffixed name (`./manifest.ts`, version 4): a pre-image kept
+            // under its living name is a second living document to every tool that
+            // reads by extension.
+            const dest = join(dir, "files", preImageRel(SNAPSHOT_VERSION, rel));
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, s.before);
+        }
+    }
+    const manifest = {
+        version: SNAPSHOT_VERSION,
+        feature: featureId,
+        dirName,
+        archivedAt: new Date().toISOString(),
+        ...(request.checklist === undefined ? {} : { checklist: request.checklist }),
+        files,
+    };
+    // Manifest last: its presence is what says the pre-images beside it are complete.
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, SNAPSHOT_MANIFEST), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+/**
+ * Refuse to replace a snapshot whose pre-images are still the only record of
+ * what the living docs said.
+ *
+ * A snapshot in an ACTIVE feature directory means a previous archive of this
+ * same feature wrote it — and since a clean rollback deletes it, finding one
+ * means that run either died mid-commit or reported `rollback-incomplete`. If
+ * its pre-images still match the living docs, nothing of that run landed and
+ * the snapshot is stale bookkeeping. If they do not, the living docs carry
+ * that run's writes, these files are the only way back, and the unconditional
+ * clear turned a repairable half-merge into a permanent one — after which
+ * `unarchive` restored the half-merged text and said the docs were back.
+ *
+ * Version 2 and 3 manifests are graded by the same staleness question — version
+ * 2 over its literal paths — because refusing them as "a different loam" would
+ * turn every leftover snapshot an older loam wrote into a permanent archive
+ * refusal on upgrade. The question reads only the manifest and the living docs,
+ * never a pre-image, so where each layout stores its pre-images does not enter
+ * into it.
+ */
+async function assertSnapshotReplaceable(request) {
+    const { docsDir, serviceDirOf } = request;
+    const dir = snapshotDir(request.featureDir);
+    const manifestPath = join(dir, SNAPSHOT_MANIFEST);
+    // The manifest is written LAST, so a `files/` tree without one is a snapshot
+    // whose run died before it could swap anything: it describes no merge.
+    if (!existsSync(manifestPath))
+        return;
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch {
+        throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);
+    }
+    // The cast that used to stand here asserted the shape rather than checking
+    // it: well-formed JSON that is not an object answered `undefined` to every
+    // field below and slipped through as "a different loam", and a bare `null`
+    // threw a TypeError out of the refusal itself. Both left this directory —
+    // which may hold the only copies of what the living docs said — one step from
+    // being replaced, without the staleness question ever having been asked.
+    if (!isRecord(manifest)) {
+        throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);
+    }
+    if (!isReadableSnapshotVersion(manifest.version) || !Array.isArray(manifest.files)) {
+        throw new SnapshotClobberError(dir, `it was written by a different loam and cannot be checked against the living docs`);
+    }
+    // `Array.isArray` narrows to `any[]`; naming the element type here is what
+    // keeps that `any` from spreading past the one row being read.
+    const rows = manifest.files;
+    const landed = [];
+    for (const row of rows) {
+        const entry = readSnapshotClaim(row);
+        if (entry === null) {
+            throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} is malformed, so nothing can say whether it is stale`);
+        }
+        let target;
+        try {
+            // These paths are data, and they are the ones this function goes and
+            // reads. They name living documents, so containment is lexical: a docs
+            // repo may legitimately mount a service directory through a symlink, and
+            // `unarchive` resolves the same field the same way before it writes back.
+            target = resolvePortableFileInsideLexically(docsDir, entry.path, `snapshot path '${entry.path}'`);
+            // A re-keyed entry's CURRENT location is wherever the enumeration says
+            // its service lives today — grading staleness at the old address would
+            // call a merely-moved file a landed merge. The literal path was still
+            // resolved above on purpose: its containment is part of what "loam wrote
+            // this manifest" means, and it stays the pre-image's key. An id the
+            // enumeration no longer answers falls back to that literal path.
+            if (entry.service !== undefined && entry.artifact !== undefined) {
+                const current = serviceDirOf(entry.service);
+                if (current !== null) {
+                    target = resolvePortableFileInsideLexically(docsDir, `${current}/${entry.artifact}`, `snapshot path '${entry.path}'`);
+                }
+            }
+        }
+        catch (err) {
+            if (!(err instanceof UnsafePathError))
+                throw err;
+            throw new SnapshotClobberError(dir, `${message(err)}, so nothing can say whether it is stale`);
+        }
+        // A row of the feature's own documents names where the move WOULD have
+        // left it, and a snapshot found here is one whose feature never moved: the
+        // bytes to grade are still under this feature directory. Graded at the
+        // literal path instead, every such row read as absent — a landed merge —
+        // and an archive that a crash or a rollback interrupted could never be
+        // retried over its own leftover. Named where it was graded, too: the
+        // refusal sends a person to restore the file from version control, and
+        // the archived path names a directory that does not exist yet.
+        const graded = acrossRename(target, request.movesTo, request.featureDir);
+        const now = existsSync(graded) ? sha256(await readFile(graded)) : null;
+        // `existed: false` means archive created the file, so "nothing landed"
+        // means it is still absent.
+        const untouched = entry.existed ? now === entry.before : now === null;
+        if (!untouched)
+            landed.push(graded === target ? entry.path : repoPath(docsDir, graded));
+    }
+    if (landed.length > 0)
+        throw new SnapshotClobberError(dir, `${landed.length} file(s) already carry that merge: ${landed.join(", ")}`);
+}
+function readSnapshotClaim(value) {
+    if (!isRecord(value))
+        return null;
+    const { path, existed, before, service, artifact } = value;
+    if (typeof path !== "string" || typeof existed !== "boolean")
+        return null;
+    let key;
+    if (service === undefined && artifact === undefined)
+        key = {};
+    else if (typeof service === "string" && typeof artifact === "string")
+        key = { service, artifact };
+    else
+        return null;
+    if (existed)
+        return isDigest(before) ? { path, existed, before, ...key } : null;
+    return before === null ? { path, existed, before, ...key } : null;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/core/staging/snapshot/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../src/core/staging/snapshot/snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The undo snapshot: the bytes `archive` is about to overwrite, parked inside\n * the feature directory so they travel with it into `features/archive/`.\n *\n * Separate from the commit because the merge is not invertible — a MODIFIED\n * requirement's previous text appears nowhere in the delta, and a landscape\n * rewritten by hand since cannot be un-rewritten by re-reading one. `unarchive`\n * puts bytes back; it does not recompute them. Nothing on the commit path reads\n * this module: only `archive` writes a snapshot and only `unarchive` honours one.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { acrossRename, resolvePortableFileInsideLexically, UnsafePathError } from \"../../kernel/path-safety.js\";\n// Every `isRecord` below guards the manifest loam itself wrote, read back inside\n// a REFUSAL path — `../lock.ts` records why that is where a thrown `TypeError`\n// costs the most.\nimport { isRecord } from \"../../kernel/records.js\";\nimport { isDigest, sha256, type StagedWrite } from \"../writes.js\";\nimport { message, quietRm } from \"../commit.js\";\nimport {\n  isReadableSnapshotVersion,\n  preImageRel,\n  SNAPSHOT_DIR,\n  SNAPSHOT_MANIFEST,\n  SNAPSHOT_VERSION,\n  snapshotDir,\n  type SnapshotEntry,\n  type SnapshotManifest,\n} from \"./manifest.js\";\n\n/** A snapshot directory that must not be replaced, because it is the only copy of the true pre-images. */\nexport class SnapshotClobberError extends Error {\n  override readonly name = \"SnapshotClobberError\";\n\n  constructor(readonly dir: string, detail: string) {\n    super(\n      `${dir} already holds an undo snapshot that does NOT match the living docs (${detail}) — a previous archive of ` +\n        `this feature wrote to the living docs and never took them back, and these are the only copies of what they ` +\n        `said before. Overwriting them would make that merge permanent and unreportable. Run \\`loam archive\\` again ` +\n        `after restoring the living docs from version control, or delete ${SNAPSHOT_DIR}/ if you know the merge never landed.`,\n    );\n  }\n}\n\n/** The (service, artifact) key a `services/` path decomposes into. */\nexport interface ServiceKey {\n  service: string;\n  artifact: string;\n}\n\n/**\n * Everything `writeSnapshot` needs, as one object. The resolvers are INJECTED\n * by the caller — `archive` builds them from its view of the tree — because\n * how a path decomposes into a service identity is repo-layout knowledge, and\n * this module's subject is parking and checking bytes.\n */\nexport interface SnapshotRequest {\n  featureDir: string;\n  /**\n   * Where the archive moves `featureDir` — the directory this snapshot is\n   * about to travel into. A staged write INSIDE `featureDir` is one of the\n   * feature's own documents (the archive re-expresses their links for the\n   * move), and it is recorded at its image under here: that is where its bytes\n   * sit whenever an undo can be asked for, so `unarchive` restores it by its\n   * literal path before moving the directory back, exactly as it restores\n   * every other row. The other reader, the clobber guard below, meets a\n   * snapshot BEFORE its feature moved and grades such a row at its image back\n   * under `featureDir`.\n   */\n  movesTo: string;\n  docsDir: string;\n  feature: { featureId: string; dirName: string };\n  staged: StagedWrite[];\n  /** Docs-relative path → the service it belongs to; null for landscape/features paths. */\n  serviceKeyOf: (rel: string) => ServiceKey | null;\n  /** Service id → its CURRENT docs-relative directory; null when not enumerated. */\n  serviceDirOf: (service: string) => string | null;\n  /**\n   * Recorded verbatim as the manifest's `checklist` when given. Opaque here —\n   * this module parks bytes and never learns what a checklist is; `archive`\n   * derives it and `gate --since` reads it back (`./manifest.ts`).\n   */\n  checklist?: string;\n}\n\nexport async function writeSnapshot(request: SnapshotRequest): Promise<void> {\n  const { featureDir, docsDir, staged } = request;\n  const { featureId, dirName } = request.feature;\n  const dir = snapshotDir(featureDir);\n  await assertSnapshotReplaceable(request);\n  // A leftover from a rolled-back run would describe a merge that never happened.\n  await quietRm(dir);\n\n  const files: SnapshotEntry[] = [];\n  for (const s of staged) {\n    // The feature's own documents by where the move leaves them; everything\n    // else by where it is written (`SnapshotRequest.movesTo` says why).\n    const rel = repoPath(docsDir, acrossRename(s.write.path, featureDir, request.movesTo));\n    // services/ entries are re-keyed by (service, artifact) so they survive the\n    // service directory moving between archive and unarchive; the literal path\n    // is still recorded — it keys the pre-image below, and it is the fallback.\n    const key = request.serviceKeyOf(rel);\n    files.push({\n      path: rel,\n      ...key,\n      existed: s.before !== null,\n      after: sha256(s.content ?? Buffer.alloc(0)),\n      before: s.before === null ? null : sha256(s.before),\n    });\n    if (s.before !== null) {\n      // Under the suffixed name (`./manifest.ts`, version 4): a pre-image kept\n      // under its living name is a second living document to every tool that\n      // reads by extension.\n      const dest = join(dir, \"files\", preImageRel(SNAPSHOT_VERSION, rel));\n      await mkdir(dirname(dest), { recursive: true });\n      await writeFile(dest, s.before);\n    }\n  }\n\n  const manifest: SnapshotManifest = {\n    version: SNAPSHOT_VERSION,\n    feature: featureId,\n    dirName,\n    archivedAt: new Date().toISOString(),\n    ...(request.checklist === undefined ? {} : { checklist: request.checklist }),\n    files,\n  };\n  // Manifest last: its presence is what says the pre-images beside it are complete.\n  await mkdir(dir, { recursive: true });\n  await writeFile(join(dir, SNAPSHOT_MANIFEST), JSON.stringify(manifest, null, 2) + \"\\n\", \"utf8\");\n}\n\n/**\n * Refuse to replace a snapshot whose pre-images are still the only record of\n * what the living docs said.\n *\n * A snapshot in an ACTIVE feature directory means a previous archive of this\n * same feature wrote it — and since a clean rollback deletes it, finding one\n * means that run either died mid-commit or reported `rollback-incomplete`. If\n * its pre-images still match the living docs, nothing of that run landed and\n * the snapshot is stale bookkeeping. If they do not, the living docs carry\n * that run's writes, these files are the only way back, and the unconditional\n * clear turned a repairable half-merge into a permanent one — after which\n * `unarchive` restored the half-merged text and said the docs were back.\n *\n * Version 2 and 3 manifests are graded by the same staleness question — version\n * 2 over its literal paths — because refusing them as \"a different loam\" would\n * turn every leftover snapshot an older loam wrote into a permanent archive\n * refusal on upgrade. The question reads only the manifest and the living docs,\n * never a pre-image, so where each layout stores its pre-images does not enter\n * into it.\n */\nasync function assertSnapshotReplaceable(request: SnapshotRequest): Promise<void> {\n  const { docsDir, serviceDirOf } = request;\n  const dir = snapshotDir(request.featureDir);\n  const manifestPath = join(dir, SNAPSHOT_MANIFEST);\n  // The manifest is written LAST, so a `files/` tree without one is a snapshot\n  // whose run died before it could swap anything: it describes no merge.\n  if (!existsSync(manifestPath)) return;\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(await readFile(manifestPath, \"utf8\"));\n  } catch {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  // The cast that used to stand here asserted the shape rather than checking\n  // it: well-formed JSON that is not an object answered `undefined` to every\n  // field below and slipped through as \"a different loam\", and a bare `null`\n  // threw a TypeError out of the refusal itself. Both left this directory —\n  // which may hold the only copies of what the living docs said — one step from\n  // being replaced, without the staleness question ever having been asked.\n  if (!isRecord(manifest)) {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  if (!isReadableSnapshotVersion(manifest.version) || !Array.isArray(manifest.files)) {\n    throw new SnapshotClobberError(dir, `it was written by a different loam and cannot be checked against the living docs`);\n  }\n  // `Array.isArray` narrows to `any[]`; naming the element type here is what\n  // keeps that `any` from spreading past the one row being read.\n  const rows: unknown[] = manifest.files;\n  const landed: string[] = [];\n  for (const row of rows) {\n    const entry = readSnapshotClaim(row);\n    if (entry === null) {\n      throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} is malformed, so nothing can say whether it is stale`);\n    }\n    let target: string;\n    try {\n      // These paths are data, and they are the ones this function goes and\n      // reads. They name living documents, so containment is lexical: a docs\n      // repo may legitimately mount a service directory through a symlink, and\n      // `unarchive` resolves the same field the same way before it writes back.\n      target = resolvePortableFileInsideLexically(docsDir, entry.path, `snapshot path '${entry.path}'`);\n      // A re-keyed entry's CURRENT location is wherever the enumeration says\n      // its service lives today — grading staleness at the old address would\n      // call a merely-moved file a landed merge. The literal path was still\n      // resolved above on purpose: its containment is part of what \"loam wrote\n      // this manifest\" means, and it stays the pre-image's key. An id the\n      // enumeration no longer answers falls back to that literal path.\n      if (entry.service !== undefined && entry.artifact !== undefined) {\n        const current = serviceDirOf(entry.service);\n        if (current !== null) {\n          target = resolvePortableFileInsideLexically(\n            docsDir,\n            `${current}/${entry.artifact}`,\n            `snapshot path '${entry.path}'`,\n          );\n        }\n      }\n    } catch (err) {\n      if (!(err instanceof UnsafePathError)) throw err;\n      throw new SnapshotClobberError(dir, `${message(err)}, so nothing can say whether it is stale`);\n    }\n    // A row of the feature's own documents names where the move WOULD have\n    // left it, and a snapshot found here is one whose feature never moved: the\n    // bytes to grade are still under this feature directory. Graded at the\n    // literal path instead, every such row read as absent — a landed merge —\n    // and an archive that a crash or a rollback interrupted could never be\n    // retried over its own leftover. Named where it was graded, too: the\n    // refusal sends a person to restore the file from version control, and\n    // the archived path names a directory that does not exist yet.\n    const graded = acrossRename(target, request.movesTo, request.featureDir);\n    const now = existsSync(graded) ? sha256(await readFile(graded)) : null;\n    // `existed: false` means archive created the file, so \"nothing landed\"\n    // means it is still absent.\n    const untouched = entry.existed ? now === entry.before : now === null;\n    if (!untouched) landed.push(graded === target ? entry.path : repoPath(docsDir, graded));\n  }\n  if (landed.length > 0) throw new SnapshotClobberError(dir, `${landed.length} file(s) already carry that merge: ${landed.join(\", \")}`);\n}\n\n/**\n * One manifest row read back as the record `writeSnapshot` wrote, or null when\n * the file does not actually say.\n *\n * Every field the staleness question consumes is checked, because an unchecked\n * field does not read as missing here — it reads as an ANSWER. An `existed`\n * that is not a boolean is falsy, and a `false` claim is graded by asking\n * whether the file is ABSENT: a manifest recording a pre-image for a deleted\n * file therefore graded as stale bookkeeping and was cleared, taking the only\n * copy of that pre-image with it. A `before` of the wrong type equals no digest\n * at all, so the opposite row accused an untouched file of carrying a merge.\n *\n * `unarchive` asks a stricter version of the same question of the same file\n * (`after`, `archivedAt`, the feature name, no duplicates) because it is about\n * to write THROUGH it; that check stays where it is, with its own refusals.\n *\n * `service`/`artifact` are read when present (a keyed `services/` row) and\n * must arrive as a pair: half a key is a manifest that does not say where the\n * file lives, and grading through the literal path anyway would be a guess.\n */\ninterface SnapshotClaim {\n  path: string;\n  existed: boolean;\n  before: string | null;\n  service?: string;\n  artifact?: string;\n}\n\nfunction readSnapshotClaim(value: unknown): SnapshotClaim | null {\n  if (!isRecord(value)) return null;\n  const { path, existed, before, service, artifact } = value;\n  if (typeof path !== \"string\" || typeof existed !== \"boolean\") return null;\n  let key: { service: string; artifact: string } | Record<string, never>;\n  if (service === undefined && artifact === undefined) key = {};\n  else if (typeof service === \"string\" && typeof artifact === \"string\") key = { service, artifact };\n  else return null;\n  if (existed) return isDigest(before) ? { path, existed, before, ...key } : null;\n  return before === null ? { path, existed, before, ...key } : null;\n}\n\n"]}

package/dist/core/staging/txn/forward.js

@@ -0,0 +1,181 @@
+/**
+ * Roll a version-2 or version-3 journal FORWARD: finish the renames a killed
+ * commit did not reach, from the staged temps that are already durable on
+ * disk (and, for a version-3 record, the directory renames after them).
+ *
+ * Forward and not undo, because that is what is actually durable: the
+ * after-bytes were written and (per stageWrites) fully on disk before the
+ * journal existed, while the OVERWRITTEN files' pre-images are durable
+ * nowhere — the rename that replaced them destroyed the only copy. The plan
+ * was validated completely before the first rename, so the post-state is
+ * exactly what a successful run would have produced; unarchive's
+ * finish-never-undo recovery is the precedent.
+ *
+ * The refuse-to-choose doctrine is rollbackStaged's, verbatim: a file whose
+ * bytes are neither the before- nor the after-digest was edited by somebody
+ * since the crash, and completing over it would destroy one of two truths.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { quietRmdir } from "../commit.js";
+import { sha256 } from "../writes.js";
+import { COMMIT_INTENT, InterruptedCommitError, sweepPidTemps } from "../interrupted.js";
+import { clearTxnIntent } from "./journal.js";
+export async function recoverForward(root, intent) {
+    const abs = (rel) => join(root, ...rel.split("/"));
+    // A directory rename is classified by pure existence — a rename moves the
+    // inode, so "which end exists" is exactly as discriminating as a digest is
+    // for a file. Both ends existing (or neither) is a state no step of the
+    // commit produces: somebody made a directory since the crash, and choosing
+    // which tree to keep is the refuse-to-choose case below.
+    const movesDone = [];
+    const movesPending = [];
+    const unknownMoves = [];
+    for (const m of intent.moves) {
+        const fromExists = existsSync(abs(m.from));
+        const toExists = existsSync(abs(m.to));
+        if (toExists && !fromExists)
+            movesDone.push(m);
+        else if (fromExists && !toExists)
+            movesPending.push(m);
+        else
+            unknownMoves.push(`${m.from} -> ${m.to}`);
+    }
+    // Where a recorded file IS now. The journal records a file at the path its
+    // swap wrote — and a `subsystem move` swaps the documents whose links it
+    // rewrites INSIDE a directory it then renames, so once that rename has
+    // landed the file is under the moved directory, not at the recorded path.
+    // Looked for there, it would read as absent: "edited since", a refusal over
+    // a commit that only needed its journal cleared. Classified moves first for
+    // exactly this; a file under a move still pending is where it was recorded.
+    const target = (f) => {
+        const landed = movesDone.find((m) => f.path.startsWith(`${m.from}/`));
+        return landed === undefined ? abs(f.path) : abs(`${landed.to}${f.path.slice(landed.from.length)}`);
+    };
+    const done = [];
+    const pending = [];
+    const unknown = [];
+    for (const f of intent.files) {
+        const file = target(f);
+        const now = existsSync(file) ? sha256(await readFile(file)) : null;
+        if (now === f.after)
+            done.push(f);
+        else if (now === f.before)
+            pending.push(f);
+        else
+            unknown.push(f.path);
+    }
+    if (unknown.length > 0 || unknownMoves.length > 0) {
+        // Two vocabularies on purpose: a FILE in neither recorded state holds
+        // edited bytes, while a DIRECTORY rename in neither state means both ends
+        // exist (or neither does) — nothing was "edited", somebody made or
+        // restored a directory since the crash. One sentence covering both told
+        // the operator to hunt for edited bytes in a directory pair. And the
+        // interrupted work is named by what it WAS (`command` + `target`), not by
+        // `intent.rerun` — that string is the REPAIR spelling (`loam subsystem
+        // sync` repairs all four subsystem verbs), so "a `loam subsystem sync`
+        // was interrupted" named a command nobody ran.
+        const parts = [
+            ...(unknown.length > 0
+                ? [
+                    `${unknown.length} of the file(s) it was writing now hold bytes that are neither what it found ` +
+                        `nor what it wrote — somebody edited them since: ${unknown.join(", ")}`,
+                ]
+                : []),
+            ...(unknownMoves.length > 0
+                ? [
+                    `the directory rename(s) ${unknownMoves.join(", ")} are in neither recorded state — both ends ` +
+                        `exist, or neither does, so loam cannot tell which tree to keep`,
+                ]
+                : []),
+        ];
+        throw new InterruptedCommitError(`a \`${intent.command}\` commit for '${intent.target}' was interrupted mid-commit ` +
+            `(pid ${intent.pid} on ${intent.host}, ${intent.at}) and ${parts.join("; ")}. ` +
+            `loam will not choose between those two truths. ` +
+            `Reconcile them against version control, delete ${COMMIT_INTENT}, then re-run \`${intent.rerun}\`.`);
+    }
+    // Whether forward is still POSSIBLE is decided before a single byte moves:
+    // completing some files and then refusing on a missing temp would leave the
+    // repo in a state neither the old nor the new tree ever had.
+    const missing = pending.filter((f) => f.after !== null && !usableTemp(root, f));
+    if (missing.length > 0) {
+        // A file whose before and after digests are EQUAL — an unchanged file
+        // carried through a commit — reads as "done" in whichever state it is in,
+        // so it is not evidence that any rename landed. Only a file that could
+        // tell the two states apart counts as one — and a landed directory MOVE
+        // always can, so it counts too.
+        const evidence = done.filter((f) => f.before !== f.after);
+        if (evidence.length === 0 && movesDone.length === 0) {
+            // Nothing ever swapped and the temps are gone — this is the tree a
+            // completed ROLLBACK leaves when the crash landed between the rollback
+            // and the journal's removal. The complete pre-state is on disk, which
+            // is one of the two states recovery promises; declaring it beats
+            // refusing over bytes that are already consistent.
+            await finish(root, intent);
+            return { command: intent.command, feature: intent.target, outcome: "consistent", repaired: [] };
+        }
+        throw new InterruptedCommitError(`a \`${intent.command}\` commit for '${intent.target}' was interrupted and ${missing.map((f) => f.path).join(", ")} ` +
+            `${missing.length === 1 ? "is" : "are"} still in the pre-commit state, but the staged bytes that would ` +
+            `finish ${missing.length === 1 ? "it" : "them"} are gone or no longer match the digest recorded before the ` +
+            `crash. Restore the tree from version control, delete ${COMMIT_INTENT}, then re-run \`${intent.rerun}\`.`);
+    }
+    const repaired = [];
+    for (const f of pending) {
+        const file = target(f);
+        if (f.after === null) {
+            await rm(file, { force: true });
+            await quietRmdir(dirname(file));
+        }
+        else {
+            await rename(join(root, ...f.tmp.split("/")), file);
+        }
+        repaired.push(f.path);
+    }
+    // Renames after the file swaps, in recorded order — the order the commit
+    // itself performs them. One that cannot land now (the destination's parent
+    // deleted since the crash, a Windows EPERM on an open handle) is a refusal
+    // naming the pair, not a half-finished loop: nothing before it is undone,
+    // and the journal stays for the next attempt.
+    for (const m of movesPending) {
+        try {
+            await rename(abs(m.from), abs(m.to));
+        }
+        catch (err) {
+            throw new InterruptedCommitError(`a \`${intent.command}\` commit for '${intent.target}' was interrupted and the rename ${m.from} -> ${m.to} ` +
+                `that would finish it cannot be performed now (${err instanceof Error ? err.message : String(err)}). ` +
+                `Complete or undo it by hand against version control, delete ${COMMIT_INTENT}, then re-run \`${intent.rerun}\`.`);
+        }
+        repaired.push(m.to);
+    }
+    await finish(root, intent);
+    return {
+        command: intent.command,
+        feature: intent.target,
+        outcome: repaired.length > 0 ? "repaired" : "completed",
+        repaired,
+    };
+}
+/** Is the recorded temp still there with exactly the bytes the journal promised? */
+function usableTemp(root, f) {
+    if (f.tmp === null)
+        return false;
+    const path = join(root, ...f.tmp.split("/"));
+    try {
+        return sha256(readFileSync(path)) === f.after;
+    }
+    catch {
+        return false;
+    }
+}
+async function finish(root, intent) {
+    const dirs = intent.files.flatMap((f) => {
+        const out = [dirname(join(root, ...f.path.split("/")))];
+        if (f.tmp !== null)
+            out.push(dirname(join(root, ...f.tmp.split("/"))));
+        return out;
+    });
+    await sweepPidTemps(dirs, intent.pid);
+    await clearTxnIntent(root);
+}
+//# sourceMappingURL=forward.js.map

package/dist/core/staging/txn/forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward.js","sourceRoot":"","sources":["../../../../src/core/staging/txn/forward.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Roll a version-2 or version-3 journal FORWARD: finish the renames a killed\n * commit did not reach, from the staged temps that are already durable on\n * disk (and, for a version-3 record, the directory renames after them).\n *\n * Forward and not undo, because that is what is actually durable: the\n * after-bytes were written and (per stageWrites) fully on disk before the\n * journal existed, while the OVERWRITTEN files' pre-images are durable\n * nowhere — the rename that replaced them destroyed the only copy. The plan\n * was validated completely before the first rename, so the post-state is\n * exactly what a successful run would have produced; unarchive's\n * finish-never-undo recovery is the precedent.\n *\n * The refuse-to-choose doctrine is rollbackStaged's, verbatim: a file whose\n * bytes are neither the before- nor the after-digest was edited by somebody\n * since the crash, and completing over it would destroy one of two truths.\n */\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { readFile, rename, rm } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { quietRmdir } from \"../commit.js\";\nimport { sha256 } from \"../writes.js\";\nimport { COMMIT_INTENT, type CommitRecovery, InterruptedCommitError, sweepPidTemps } from \"../interrupted.js\";\nimport { clearTxnIntent, type TxnIntent, type TxnIntentFile, type TxnIntentMove } from \"./journal.js\";\n\nexport async function recoverForward(root: string, intent: TxnIntent): Promise<CommitRecovery> {\n  const abs = (rel: string): string => join(root, ...rel.split(\"/\"));\n  // A directory rename is classified by pure existence — a rename moves the\n  // inode, so \"which end exists\" is exactly as discriminating as a digest is\n  // for a file. Both ends existing (or neither) is a state no step of the\n  // commit produces: somebody made a directory since the crash, and choosing\n  // which tree to keep is the refuse-to-choose case below.\n  const movesDone: TxnIntentMove[] = [];\n  const movesPending: TxnIntentMove[] = [];\n  const unknownMoves: string[] = [];\n  for (const m of intent.moves) {\n    const fromExists = existsSync(abs(m.from));\n    const toExists = existsSync(abs(m.to));\n    if (toExists && !fromExists) movesDone.push(m);\n    else if (fromExists && !toExists) movesPending.push(m);\n    else unknownMoves.push(`${m.from} -> ${m.to}`);\n  }\n  // Where a recorded file IS now. The journal records a file at the path its\n  // swap wrote — and a `subsystem move` swaps the documents whose links it\n  // rewrites INSIDE a directory it then renames, so once that rename has\n  // landed the file is under the moved directory, not at the recorded path.\n  // Looked for there, it would read as absent: \"edited since\", a refusal over\n  // a commit that only needed its journal cleared. Classified moves first for\n  // exactly this; a file under a move still pending is where it was recorded.\n  const target = (f: TxnIntentFile): string => {\n    const landed = movesDone.find((m) => f.path.startsWith(`${m.from}/`));\n    return landed === undefined ? abs(f.path) : abs(`${landed.to}${f.path.slice(landed.from.length)}`);\n  };\n  const done: TxnIntentFile[] = [];\n  const pending: TxnIntentFile[] = [];\n  const unknown: string[] = [];\n  for (const f of intent.files) {\n    const file = target(f);\n    const now = existsSync(file) ? sha256(await readFile(file)) : null;\n    if (now === f.after) done.push(f);\n    else if (now === f.before) pending.push(f);\n    else unknown.push(f.path);\n  }\n  if (unknown.length > 0 || unknownMoves.length > 0) {\n    // Two vocabularies on purpose: a FILE in neither recorded state holds\n    // edited bytes, while a DIRECTORY rename in neither state means both ends\n    // exist (or neither does) — nothing was \"edited\", somebody made or\n    // restored a directory since the crash. One sentence covering both told\n    // the operator to hunt for edited bytes in a directory pair. And the\n    // interrupted work is named by what it WAS (`command` + `target`), not by\n    // `intent.rerun` — that string is the REPAIR spelling (`loam subsystem\n    // sync` repairs all four subsystem verbs), so \"a `loam subsystem sync`\n    // was interrupted\" named a command nobody ran.\n    const parts = [\n      ...(unknown.length > 0\n        ? [\n            `${unknown.length} of the file(s) it was writing now hold bytes that are neither what it found ` +\n              `nor what it wrote — somebody edited them since: ${unknown.join(\", \")}`,\n          ]\n        : []),\n      ...(unknownMoves.length > 0\n        ? [\n            `the directory rename(s) ${unknownMoves.join(\", \")} are in neither recorded state — both ends ` +\n              `exist, or neither does, so loam cannot tell which tree to keep`,\n          ]\n        : []),\n    ];\n    throw new InterruptedCommitError(\n      `a \\`${intent.command}\\` commit for '${intent.target}' was interrupted mid-commit ` +\n        `(pid ${intent.pid} on ${intent.host}, ${intent.at}) and ${parts.join(\"; \")}. ` +\n        `loam will not choose between those two truths. ` +\n        `Reconcile them against version control, delete ${COMMIT_INTENT}, then re-run \\`${intent.rerun}\\`.`,\n    );\n  }\n\n  // Whether forward is still POSSIBLE is decided before a single byte moves:\n  // completing some files and then refusing on a missing temp would leave the\n  // repo in a state neither the old nor the new tree ever had.\n  const missing = pending.filter((f) => f.after !== null && !usableTemp(root, f));\n  if (missing.length > 0) {\n    // A file whose before and after digests are EQUAL — an unchanged file\n    // carried through a commit — reads as \"done\" in whichever state it is in,\n    // so it is not evidence that any rename landed. Only a file that could\n    // tell the two states apart counts as one — and a landed directory MOVE\n    // always can, so it counts too.\n    const evidence = done.filter((f) => f.before !== f.after);\n    if (evidence.length === 0 && movesDone.length === 0) {\n      // Nothing ever swapped and the temps are gone — this is the tree a\n      // completed ROLLBACK leaves when the crash landed between the rollback\n      // and the journal's removal. The complete pre-state is on disk, which\n      // is one of the two states recovery promises; declaring it beats\n      // refusing over bytes that are already consistent.\n      await finish(root, intent);\n      return { command: intent.command, feature: intent.target, outcome: \"consistent\", repaired: [] };\n    }\n    throw new InterruptedCommitError(\n      `a \\`${intent.command}\\` commit for '${intent.target}' was interrupted and ${missing.map((f) => f.path).join(\", \")} ` +\n        `${missing.length === 1 ? \"is\" : \"are\"} still in the pre-commit state, but the staged bytes that would ` +\n        `finish ${missing.length === 1 ? \"it\" : \"them\"} are gone or no longer match the digest recorded before the ` +\n        `crash. Restore the tree from version control, delete ${COMMIT_INTENT}, then re-run \\`${intent.rerun}\\`.`,\n    );\n  }\n\n  const repaired: string[] = [];\n  for (const f of pending) {\n    const file = target(f);\n    if (f.after === null) {\n      await rm(file, { force: true });\n      await quietRmdir(dirname(file));\n    } else {\n      await rename(join(root, ...f.tmp!.split(\"/\")), file);\n    }\n    repaired.push(f.path);\n  }\n  // Renames after the file swaps, in recorded order — the order the commit\n  // itself performs them. One that cannot land now (the destination's parent\n  // deleted since the crash, a Windows EPERM on an open handle) is a refusal\n  // naming the pair, not a half-finished loop: nothing before it is undone,\n  // and the journal stays for the next attempt.\n  for (const m of movesPending) {\n    try {\n      await rename(abs(m.from), abs(m.to));\n    } catch (err) {\n      throw new InterruptedCommitError(\n        `a \\`${intent.command}\\` commit for '${intent.target}' was interrupted and the rename ${m.from} -> ${m.to} ` +\n          `that would finish it cannot be performed now (${err instanceof Error ? err.message : String(err)}). ` +\n          `Complete or undo it by hand against version control, delete ${COMMIT_INTENT}, then re-run \\`${intent.rerun}\\`.`,\n      );\n    }\n    repaired.push(m.to);\n  }\n  await finish(root, intent);\n  return {\n    command: intent.command,\n    feature: intent.target,\n    outcome: repaired.length > 0 ? \"repaired\" : \"completed\",\n    repaired,\n  };\n}\n\n/** Is the recorded temp still there with exactly the bytes the journal promised? */\nfunction usableTemp(root: string, f: TxnIntentFile): boolean {\n  if (f.tmp === null) return false;\n  const path = join(root, ...f.tmp.split(\"/\"));\n  try {\n    return sha256(readFileSync(path)) === f.after;\n  } catch {\n    return false;\n  }\n}\n\nasync function finish(root: string, intent: TxnIntent): Promise<void> {\n  const dirs = intent.files.flatMap((f) => {\n    const out = [dirname(join(root, ...f.path.split(\"/\")))];\n    if (f.tmp !== null) out.push(dirname(join(root, ...f.tmp.split(\"/\"))));\n    return out;\n  });\n  await sweepPidTemps(dirs, intent.pid);\n  await clearTxnIntent(root);\n}\n\n"]}

package/dist/core/staging/txn/journal.js

@@ -0,0 +1,139 @@
+/**
+ * The version-2 `.loam-commit` journal: the record a SMALL journaled
+ * transaction writes before its first rename, for the writers whose commits
+ * have no snapshot and no final directory move — rebase, vouch, new, gherkin.
+ *
+ * Version 1 (archive/unarchive) restores from a snapshot that travels in the
+ * feature directory; none of the smaller writers has one, which is exactly
+ * why the roadmap says extract a smaller transaction rather than reuse — this
+ * journal therefore records, per file, the digest of both states AND the
+ * root-relative staged temp still holding the after-bytes, so recovery can
+ * roll FORWARD from what is already durable instead of pretending pre-images
+ * exist somewhere. `rerun` is the exact `loam …` line doctor prints as the
+ * fix: recovery runs at the start of the next invocation of the same command.
+ *
+ * A txn/ sub-package importing ONLY the staging root, never `recovery/`:
+ * recovery/ already imports the root and will import txn/ for dispatch, so an
+ * edge back from here would be the repo's first package cycle.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join, relative } from "node:path";
+import { isPathInside } from "../../kernel/path-safety.js";
+import { quietRm } from "../commit.js";
+import { COMMIT_INTENT, writeDurable } from "../interrupted.js";
+import { isDigest, sha256 } from "../writes.js";
+const TXN_VERSION = 2;
+/**
+ * The version whose records CARRY DIRECTORY MOVES — `subsystem move`'s
+ * journal, the first consumer whose commit renames directories beside its one
+ * staged file. A version of its own, and version 2 is still what every
+ * move-less writer stamps, deliberately: an old binary must keep recovering
+ * the version-2 records it always could, and it must REFUSE a record with
+ * moves rather than roll the file half forward and leave the renames behind —
+ * an unknown version already reads as "a commit this loam cannot read", which
+ * is `doctor`'s honest blocker, not a silent half-repair.
+ */
+const TXN_MOVES_VERSION = 3;
+/** Root-relative with forward slashes — the journal must survive being read on another machine. */
+function rel(root, abs) {
+    return relative(root, abs).split(/[\\/]/).join("/");
+}
+export async function writeTxnIntent(spec, staged) {
+    const moves = (spec.moves ?? []).map((m) => ({ from: rel(spec.root, m.from), to: rel(spec.root, m.to) }));
+    const intent = {
+        version: moves.length > 0 ? TXN_MOVES_VERSION : TXN_VERSION,
+        command: spec.command,
+        rerun: spec.rerun,
+        target: spec.target,
+        pid: process.pid,
+        host: hostname(),
+        at: new Date().toISOString(),
+        files: staged.map((s) => ({
+            path: rel(spec.root, s.write.path),
+            before: s.before === null ? null : sha256(s.before),
+            after: s.content === null ? null : sha256(s.content),
+            tmp: s.tmp === null ? null : rel(spec.root, s.tmp),
+        })),
+        moves,
+    };
+    await writeDurable(join(spec.root, COMMIT_INTENT), JSON.stringify(intent, null, 2) + "\n");
+}
+export async function clearTxnIntent(root) {
+    await quietRm(join(root, COMMIT_INTENT));
+}
+/**
+ * The journal as written, or null when absent, unreadable, or not version 2 —
+ * the same strict grading version 1 gets: a record that cannot be trusted
+ * whole is not a record, and `doctor` describes the difference.
+ */
+export async function readTxnIntent(root) {
+    const path = join(root, COMMIT_INTENT);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const i = parsed;
+    if (i === null || typeof i !== "object")
+        return null;
+    if (i.version !== TXN_VERSION && i.version !== TXN_MOVES_VERSION)
+        return null;
+    if (typeof i.command !== "string" || typeof i.rerun !== "string" || typeof i.target !== "string")
+        return null;
+    if (typeof i.pid !== "number" || typeof i.host !== "string" || typeof i.at !== "string")
+        return null;
+    if (!Array.isArray(i.files))
+        return null;
+    // A version-2 record predates the field; normalise so recovery reads one
+    // shape. A version-3 record's moves are validated exactly as its files are:
+    // recovery RENAMES what they name, so an entry escaping the root fails the
+    // whole record closed.
+    if (i.moves === undefined)
+        i.moves = [];
+    if (!Array.isArray(i.moves))
+        return null;
+    if (i.version === TXN_VERSION && i.moves.length > 0)
+        return null;
+    for (const m of i.moves) {
+        if (typeof m?.from !== "string" || typeof m?.to !== "string")
+            return null;
+        if (!insideRoot(root, m.from) || !insideRoot(root, m.to))
+            return null;
+    }
+    for (const f of i.files) {
+        if (typeof f?.path !== "string")
+            return null;
+        if (!digestOrNull(f.before) || !digestOrNull(f.after))
+            return null;
+        if (f.tmp !== null && typeof f.tmp !== "string")
+            return null;
+        // A write (after non-null) with no temp recorded could never be rolled
+        // forward; refusing the whole record here keeps that impossibility a
+        // `doctor` sentence instead of a mid-recovery surprise.
+        if (f.after !== null && f.tmp === null)
+            return null;
+        // The journal is untrusted input — a plain file that travels in a git
+        // checkout — and recovery RENAMES OVER and DELETES what these entries
+        // name. An entry escaping the root (`../outside`, an absolute path) would
+        // turn roll-forward into an arbitrary write anywhere on the machine, so
+        // it fails the whole record closed: `doctor` grades it exactly as any
+        // other unreadable journal, a blocker naming the file for a human.
+        if (!insideRoot(root, f.path) || (f.tmp !== null && !insideRoot(root, f.tmp)))
+            return null;
+    }
+    return i;
+}
+function digestOrNull(value) {
+    return value === null || isDigest(value);
+}
+/** Lexical containment of a recorded root-relative path — recovery acts on the join. */
+function insideRoot(root, rel) {
+    return isPathInside(join(root), join(root, ...rel.split("/")));
+}
+//# sourceMappingURL=journal.js.map

package/dist/core/staging/txn/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../../src/core/staging/txn/journal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The version-2 `.loam-commit` journal: the record a SMALL journaled\n * transaction writes before its first rename, for the writers whose commits\n * have no snapshot and no final directory move — rebase, vouch, new, gherkin.\n *\n * Version 1 (archive/unarchive) restores from a snapshot that travels in the\n * feature directory; none of the smaller writers has one, which is exactly\n * why the roadmap says extract a smaller transaction rather than reuse — this\n * journal therefore records, per file, the digest of both states AND the\n * root-relative staged temp still holding the after-bytes, so recovery can\n * roll FORWARD from what is already durable instead of pretending pre-images\n * exist somewhere. `rerun` is the exact `loam …` line doctor prints as the\n * fix: recovery runs at the start of the next invocation of the same command.\n *\n * A txn/ sub-package importing ONLY the staging root, never `recovery/`:\n * recovery/ already imports the root and will import txn/ for dispatch, so an\n * edge back from here would be the repo's first package cycle.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { hostname } from \"node:os\";\nimport { join, relative } from \"node:path\";\nimport { isPathInside } from \"../../kernel/path-safety.js\";\nimport { quietRm } from \"../commit.js\";\nimport { COMMIT_INTENT, writeDurable } from \"../interrupted.js\";\nimport { isDigest, sha256, type StagedWrite } from \"../writes.js\";\n\nconst TXN_VERSION = 2;\n/**\n * The version whose records CARRY DIRECTORY MOVES — `subsystem move`'s\n * journal, the first consumer whose commit renames directories beside its one\n * staged file. A version of its own, and version 2 is still what every\n * move-less writer stamps, deliberately: an old binary must keep recovering\n * the version-2 records it always could, and it must REFUSE a record with\n * moves rather than roll the file half forward and leave the renames behind —\n * an unknown version already reads as \"a commit this loam cannot read\", which\n * is `doctor`'s honest blocker, not a silent half-repair.\n */\nconst TXN_MOVES_VERSION = 3;\n\n/** One directory rename inside a transaction: root-relative, forward slashes. */\nexport interface TxnIntentMove {\n  from: string;\n  to: string;\n}\n\nexport interface TxnIntentFile {\n  /** Root-relative path, forward slashes. */\n  path: string;\n  /** sha256 of the bytes before the swap; null when the swap creates the file. */\n  before: string | null;\n  /** sha256 of the bytes the swap writes; null when the swap deletes the file. */\n  after: string | null;\n  /** Root-relative staged temp holding the after-bytes; null for a deletion. */\n  tmp: string | null;\n}\n\nexport interface TxnIntent {\n  version: number;\n  /** Which command was committing — a sentence a human reads, not a branch. */\n  command: string;\n  /** The exact `loam …` invocation whose next run recovers this journal. */\n  rerun: string;\n  /** What the command was committing for: a feature id, or a service. */\n  target: string;\n  pid: number;\n  host: string;\n  at: string;\n  files: TxnIntentFile[];\n  /**\n   * Directory renames the commit performs AFTER its file swaps, in this\n   * order. `[]` on every version-2 record (the reader normalises absence):\n   * only `subsystem move`/`rename` write any, and their presence is what\n   * bumps the record to version 3.\n   */\n  moves: TxnIntentMove[];\n}\n\n/** What a transaction tells the journal about itself; the caller's one spelling of its identity. */\nexport interface TxnSpec {\n  /** The repo root the journal lives in — the docs repo, or gherkin's owned root. */\n  root: string;\n  command: string;\n  rerun: string;\n  target: string;\n  /** Directory renames to perform after the swaps — ABSOLUTE paths; the journal stores them root-relative. */\n  moves?: { from: string; to: string }[];\n}\n\n/** Root-relative with forward slashes — the journal must survive being read on another machine. */\nfunction rel(root: string, abs: string): string {\n  return relative(root, abs).split(/[\\\\/]/).join(\"/\");\n}\n\nexport async function writeTxnIntent(spec: TxnSpec, staged: StagedWrite[]): Promise<void> {\n  const moves = (spec.moves ?? []).map((m) => ({ from: rel(spec.root, m.from), to: rel(spec.root, m.to) }));\n  const intent: TxnIntent = {\n    version: moves.length > 0 ? TXN_MOVES_VERSION : TXN_VERSION,\n    command: spec.command,\n    rerun: spec.rerun,\n    target: spec.target,\n    pid: process.pid,\n    host: hostname(),\n    at: new Date().toISOString(),\n    files: staged.map((s) => ({\n      path: rel(spec.root, s.write.path),\n      before: s.before === null ? null : sha256(s.before),\n      after: s.content === null ? null : sha256(s.content),\n      tmp: s.tmp === null ? null : rel(spec.root, s.tmp),\n    })),\n    moves,\n  };\n  await writeDurable(join(spec.root, COMMIT_INTENT), JSON.stringify(intent, null, 2) + \"\\n\");\n}\n\nexport async function clearTxnIntent(root: string): Promise<void> {\n  await quietRm(join(root, COMMIT_INTENT));\n}\n\n/**\n * The journal as written, or null when absent, unreadable, or not version 2 —\n * the same strict grading version 1 gets: a record that cannot be trusted\n * whole is not a record, and `doctor` describes the difference.\n */\nexport async function readTxnIntent(root: string): Promise<TxnIntent | null> {\n  const path = join(root, COMMIT_INTENT);\n  if (!existsSync(path)) return null;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(await readFile(path, \"utf8\"));\n  } catch {\n    return null;\n  }\n  const i = parsed as Partial<TxnIntent>;\n  if (i === null || typeof i !== \"object\") return null;\n  if (i.version !== TXN_VERSION && i.version !== TXN_MOVES_VERSION) return null;\n  if (typeof i.command !== \"string\" || typeof i.rerun !== \"string\" || typeof i.target !== \"string\") return null;\n  if (typeof i.pid !== \"number\" || typeof i.host !== \"string\" || typeof i.at !== \"string\") return null;\n  if (!Array.isArray(i.files)) return null;\n  // A version-2 record predates the field; normalise so recovery reads one\n  // shape. A version-3 record's moves are validated exactly as its files are:\n  // recovery RENAMES what they name, so an entry escaping the root fails the\n  // whole record closed.\n  if (i.moves === undefined) i.moves = [];\n  if (!Array.isArray(i.moves)) return null;\n  if (i.version === TXN_VERSION && i.moves.length > 0) return null;\n  for (const m of i.moves) {\n    if (typeof m?.from !== \"string\" || typeof m?.to !== \"string\") return null;\n    if (!insideRoot(root, m.from) || !insideRoot(root, m.to)) return null;\n  }\n  for (const f of i.files) {\n    if (typeof f?.path !== \"string\") return null;\n    if (!digestOrNull(f.before) || !digestOrNull(f.after)) return null;\n    if (f.tmp !== null && typeof f.tmp !== \"string\") return null;\n    // A write (after non-null) with no temp recorded could never be rolled\n    // forward; refusing the whole record here keeps that impossibility a\n    // `doctor` sentence instead of a mid-recovery surprise.\n    if (f.after !== null && f.tmp === null) return null;\n    // The journal is untrusted input — a plain file that travels in a git\n    // checkout — and recovery RENAMES OVER and DELETES what these entries\n    // name. An entry escaping the root (`../outside`, an absolute path) would\n    // turn roll-forward into an arbitrary write anywhere on the machine, so\n    // it fails the whole record closed: `doctor` grades it exactly as any\n    // other unreadable journal, a blocker naming the file for a human.\n    if (!insideRoot(root, f.path) || (f.tmp !== null && !insideRoot(root, f.tmp))) return null;\n  }\n  return i as TxnIntent;\n}\n\nfunction digestOrNull(value: unknown): boolean {\n  return value === null || isDigest(value);\n}\n\n/** Lexical containment of a recorded root-relative path — recovery acts on the join. */\nfunction insideRoot(root: string, rel: string): boolean {\n  return isPathInside(join(root), join(root, ...rel.split(\"/\")));\n}\n"]}