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

package/dist/core/doctor/reports/scan.js

@@ -0,0 +1,242 @@
+/**
+ * The problem reports a repository has collected: how many there are, what
+ * state each one is in, and which ordinal the next one takes.
+ *
+ * A sub-package because `doctor/` is at its five-file limit, and a scan of its
+ * own because this is the one directory loam reads that loam never writes. The
+ * `loam-report` protocol has always asked a repository to accumulate a corpus
+ * under `loam-reports/` and then never looked at it — eleven reports landed in
+ * this repository in two days, three of them already closed, and every bit of
+ * that state lived outside the files, in whoever remembered. The directory is
+ * loam's own convention and its contents are loam's own format, so counting
+ * them is a fact loam can read as cheaply as it reads `agentFiles`. Reading is
+ * the whole of it: nothing here transmits anything, which is the constraint the
+ * protocol is built around.
+ *
+ * Everything below is best-effort on purpose. A report is a hand-written
+ * Markdown file, so an absent directory, an unreadable one, a name written
+ * before the numbering existed and a file with no `Status:` line are all
+ * ordinary states of a healthy repository. None of them is a finding, and
+ * `doctor`'s `healthy` does not move for anything in here — a repo with eleven
+ * open reports is not broken, it is one that has been paying attention.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {} from "../report.js";
+/**
+ * The conventional NAME of the directory the `loam-report` protocol asks a
+ * repository to accumulate, spelled once — the segment `scanReports` joins onto
+ * the resolved root to reach it.
+ *
+ * A name rather than a path, because two readers want different things out of
+ * it and both are right: `ProblemReports.dir` carries the joined ABSOLUTE
+ * location, because the protocol tells an agent to write there and a relative
+ * spelling leaves it guessing which repository "relative" meant (`../report.ts`
+ * records that), while `commands/doctor.ts`'s human row prints this constant, so
+ * a person standing in the repository reads `loam-reports/` — what the protocol,
+ * the reports themselves and every page that mentions them say.
+ */
+export const REPORTS_DIR = "loam-reports";
+/**
+ * The leading ordinal of `012-2026-09-03-slug.md`. Three digits or more, so the
+ * thousandth report widens the field instead of losing its number.
+ */
+const ORDINAL = /^(\d{3,})-/;
+/**
+ * A name written before the numbering existed: `2026-09-03-slug.md`, the shape
+ * eleven reports in this repository already carry.
+ *
+ * Checked FIRST, and this is the whole reason it exists as its own pattern: a
+ * four-digit year satisfies `ORDINAL` perfectly, so a legacy name read as an
+ * ordinal is report number 2026 — and the next report loam hands out is then
+ * 2027, in a directory whose highest real ordinal is 3. A legacy name is still
+ * a report; it just has no number, and contributes none.
+ */
+const LEGACY_DATE_NAME = /^\d{4}-\d{2}-\d{2}-/;
+/** The ordinal a report's file name claims, or null when the name predates numbering. */
+function ordinalOf(file) {
+    if (LEGACY_DATE_NAME.test(file))
+        return null;
+    return ORDINAL.exec(file)?.[1] ?? null;
+}
+/**
+ * The template's `- Status:` line, matched in the header FIELD BLOCK alone (see
+ * `headerFields`). Only the first word is captured: the vocabulary's two
+ * composite values carry prose after it (`fixed in 0.2.0-alpha.5`,
+ * `superseded by 010`) that an author writes for a reader, and parsing further
+ * would make loam an authority on a sentence it does not own.
+ */
+const STATUS_LINE = /^[ \t]*-[ \t]*Status:[ \t]*(\S+)/m;
+/** A fenced block's delimiter line, either spelling. */
+const FENCE = /^[ \t]*(`{3,}|~{3,})/;
+/**
+ * An indented code block's line — the OTHER way markdown quotes code, and the
+ * way `loam instructions loam-report` prints its own template (the four-space
+ * block in ../../agent/support/report.ts). A fence-only reader counted such a
+ * report open off the template's `- Status: open`.
+ */
+const INDENTED = /^(?: {4}|\t)/;
+/** A section heading — the line that ends the header field block. */
+const SECTION = /^##[ \t]/;
+/**
+ * The report's header field block: every line above the first `## ` heading,
+ * with quoted code — fenced or indented — dropped.
+ *
+ * Matched anywhere in the file, `- Status:` convicted the wrong reports twice
+ * over. A report that QUOTES the protocol template — which several do, because
+ * an agent reporting that the protocol is wrong pastes the protocol — carries a
+ * `- Status: open` inside a fence and was counted open however its own header
+ * read; and a report whose body discusses a status line later on was read the
+ * same way. The status a report claims is a header FIELD, written beside
+ * `- Classification:` above the first section, so that is the only place it is
+ * read from. An unterminated fence swallows the rest of the file rather than
+ * flipping back — the safe direction, since the alternative is reading code as
+ * a field.
+ *
+ * Two shapes defeated the first version of that, and both are the same quoting
+ * case: a NESTED fence, where the outer ```` opens and the inner ``` was taken
+ * for its close, leaving the quoted block read as fields; and an INDENTED
+ * block, which the protocol itself uses and whose indented `## Summary` never
+ * ends the header either. So a fence is closed only by a run of the same
+ * character at least as long as the one that opened it, and an indented block
+ * (four spaces after a blank line, through the blank lines inside it) is
+ * dropped whole.
+ */
+function headerFields(text) {
+    const kept = [];
+    let fence = null;
+    let indented = false;
+    let afterBlank = true;
+    for (const line of text.split(/\r?\n/)) {
+        if (fence !== null) {
+            const close = FENCE.exec(line)?.[1];
+            if (close !== undefined && close[0] === fence[0] && close.length >= fence.length)
+                fence = null;
+            continue;
+        }
+        const blank = line.trim() === "";
+        if (indented) {
+            if (blank || INDENTED.test(line))
+                continue;
+            indented = false;
+        }
+        const open = FENCE.exec(line)?.[1];
+        if (open !== undefined) {
+            fence = open;
+            afterBlank = false;
+            continue;
+        }
+        if (afterBlank && INDENTED.test(line)) {
+            indented = true;
+            continue;
+        }
+        if (SECTION.test(line))
+            break;
+        kept.push(line);
+        afterBlank = blank;
+    }
+    return kept.join("\n");
+}
+/** The words a `Status:` line may say that loam can count. */
+const STATED = ["open", "sent", "fixed", "superseded"];
+/**
+ * The ordinal the next report takes: one past the highest present, never one
+ * past the count.
+ *
+ * Those two differ exactly when the directory has a gap or a legacy name in it
+ * — which this directory does, since the numbering arrived after eleven
+ * reports had already been written — and counting instead of maximising is how
+ * a next ordinal starts handing out numbers that are already taken.
+ */
+function nextOrdinal(entries) {
+    let highest = 0;
+    for (const entry of entries) {
+        if (entry.ordinal === null)
+            continue;
+        const value = Number.parseInt(entry.ordinal, 10);
+        if (value > highest)
+            highest = value;
+    }
+    return String(highest + 1).padStart(3, "0");
+}
+/**
+ * What one report's own `Status:` line says, or `unstated`.
+ *
+ * Unreadable reads as unstated rather than throwing: a report saved as UTF-16,
+ * a file the process cannot open, or a directory somebody named `notes.md` are
+ * all things a diagnostic must survive. `doctor` is the command that has to be
+ * able to describe a broken repository without becoming the next thing that
+ * breaks in it.
+ */
+async function statusOf(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        // Unreadable is not a state the file claims — it is a state of the read.
+        return "unstated";
+    }
+    const word = STATUS_LINE.exec(headerFields(text))?.[1]?.toLowerCase();
+    return STATED.find((known) => known === word) ?? "unstated";
+}
+/**
+ * Read `<root>/loam-reports/`, where `root` is the directory holding the
+ * `loam.json` that resolved — the repository the reports were written at the
+ * root of — falling back, when nothing parsed, to the directory of the
+ * `loam.json` loam FOUND (`doctor.ts` says why that and not the cwd), and to the
+ * run directory only when there is no config file anywhere above it.
+ *
+ * Every `*.md` in the directory is an entry, including a hand-written index
+ * page: which files in there are "really" reports is a second naming
+ * convention, and inventing one would make loam disagree with a directory
+ * listing about what the directory holds. An unnumbered entry contributes
+ * nothing to `next`, so an index costs the corpus nothing either.
+ */
+export async function scanReports(root) {
+    const dir = join(root, REPORTS_DIR);
+    let names;
+    try {
+        names = (await readdir(dir)).filter((name) => name.toLowerCase().endsWith(".md"));
+    }
+    catch (error) {
+        // Absent is the state of every repository that has never had to write a
+        // report, and it is the common one — `present: false`, nothing to say. Any
+        // other errno means the directory IS there and this process could not list
+        // it, which is a different sentence: the corpus exists and loam cannot see
+        // into it, so `present` stays true and the counts stay honestly empty.
+        const code = error.code;
+        const present = code !== "ENOENT" && code !== "ENOTDIR";
+        return { dir, present, total: 0, next: "001", entries: [] };
+    }
+    // Sorted here rather than left in readdir order, which is the filesystem's and
+    // differs between one machine and another — and sorted by the ORDINAL the name
+    // claims, numerically, because report order is what a reader scanning the list
+    // expects and byte order stops being it at exactly the point the widening rule
+    // was written for: `1000-…` sorts before `998-…`, so a directory that has
+    // passed its thousandth report reads 1000, 1001, 998, 999 (verification
+    // 2026-09-04, second pass). Unnumbered names — the shape reports carried before
+    // the numbering existed — contribute no ordinal, so they sort last among
+    // themselves by name, where a reader looking for "the next one" is not looking.
+    const rank = (file) => {
+        const ordinal = ordinalOf(file);
+        return ordinal === null ? Number.POSITIVE_INFINITY : Number.parseInt(ordinal, 10);
+    };
+    names.sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));
+    // Read together, like `staleAgentFiles` does: a report corpus is a flat
+    // directory of small hand-written files, so there is nothing here worth a
+    // concurrency cap, and `Promise.all` preserves the order just established.
+    const entries = await Promise.all(names.map(async (file) => ({
+        file,
+        ordinal: ordinalOf(file),
+        status: await statusOf(join(dir, file)),
+    })));
+    return {
+        dir,
+        present: true,
+        total: entries.length,
+        next: nextOrdinal(entries),
+        entries,
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/core/doctor/reports/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../../src/core/doctor/reports/scan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The problem reports a repository has collected: how many there are, what\n * state each one is in, and which ordinal the next one takes.\n *\n * A sub-package because `doctor/` is at its five-file limit, and a scan of its\n * own because this is the one directory loam reads that loam never writes. The\n * `loam-report` protocol has always asked a repository to accumulate a corpus\n * under `loam-reports/` and then never looked at it — eleven reports landed in\n * this repository in two days, three of them already closed, and every bit of\n * that state lived outside the files, in whoever remembered. The directory is\n * loam's own convention and its contents are loam's own format, so counting\n * them is a fact loam can read as cheaply as it reads `agentFiles`. Reading is\n * the whole of it: nothing here transmits anything, which is the constraint the\n * protocol is built around.\n *\n * Everything below is best-effort on purpose. A report is a hand-written\n * Markdown file, so an absent directory, an unreadable one, a name written\n * before the numbering existed and a file with no `Status:` line are all\n * ordinary states of a healthy repository. None of them is a finding, and\n * `doctor`'s `healthy` does not move for anything in here — a repo with eleven\n * open reports is not broken, it is one that has been paying attention.\n */\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport {\n  type ProblemReportEntry,\n  type ProblemReports,\n  type ProblemReportStatus,\n} from \"../report.js\";\n\n/**\n * The conventional NAME of the directory the `loam-report` protocol asks a\n * repository to accumulate, spelled once — the segment `scanReports` joins onto\n * the resolved root to reach it.\n *\n * A name rather than a path, because two readers want different things out of\n * it and both are right: `ProblemReports.dir` carries the joined ABSOLUTE\n * location, because the protocol tells an agent to write there and a relative\n * spelling leaves it guessing which repository \"relative\" meant (`../report.ts`\n * records that), while `commands/doctor.ts`'s human row prints this constant, so\n * a person standing in the repository reads `loam-reports/` — what the protocol,\n * the reports themselves and every page that mentions them say.\n */\nexport const REPORTS_DIR = \"loam-reports\";\n\n/**\n * The leading ordinal of `012-2026-09-03-slug.md`. Three digits or more, so the\n * thousandth report widens the field instead of losing its number.\n */\nconst ORDINAL = /^(\\d{3,})-/;\n\n/**\n * A name written before the numbering existed: `2026-09-03-slug.md`, the shape\n * eleven reports in this repository already carry.\n *\n * Checked FIRST, and this is the whole reason it exists as its own pattern: a\n * four-digit year satisfies `ORDINAL` perfectly, so a legacy name read as an\n * ordinal is report number 2026 — and the next report loam hands out is then\n * 2027, in a directory whose highest real ordinal is 3. A legacy name is still\n * a report; it just has no number, and contributes none.\n */\nconst LEGACY_DATE_NAME = /^\\d{4}-\\d{2}-\\d{2}-/;\n\n/** The ordinal a report's file name claims, or null when the name predates numbering. */\nfunction ordinalOf(file: string): string | null {\n  if (LEGACY_DATE_NAME.test(file)) return null;\n  return ORDINAL.exec(file)?.[1] ?? null;\n}\n\n/**\n * The template's `- Status:` line, matched in the header FIELD BLOCK alone (see\n * `headerFields`). Only the first word is captured: the vocabulary's two\n * composite values carry prose after it (`fixed in 0.2.0-alpha.5`,\n * `superseded by 010`) that an author writes for a reader, and parsing further\n * would make loam an authority on a sentence it does not own.\n */\nconst STATUS_LINE = /^[ \\t]*-[ \\t]*Status:[ \\t]*(\\S+)/m;\n\n/** A fenced block's delimiter line, either spelling. */\nconst FENCE = /^[ \\t]*(`{3,}|~{3,})/;\n\n/**\n * An indented code block's line — the OTHER way markdown quotes code, and the\n * way `loam instructions loam-report` prints its own template (the four-space\n * block in ../../agent/support/report.ts). A fence-only reader counted such a\n * report open off the template's `- Status: open`.\n */\nconst INDENTED = /^(?: {4}|\\t)/;\n\n/** A section heading — the line that ends the header field block. */\nconst SECTION = /^##[ \\t]/;\n\n/**\n * The report's header field block: every line above the first `## ` heading,\n * with quoted code — fenced or indented — dropped.\n *\n * Matched anywhere in the file, `- Status:` convicted the wrong reports twice\n * over. A report that QUOTES the protocol template — which several do, because\n * an agent reporting that the protocol is wrong pastes the protocol — carries a\n * `- Status: open` inside a fence and was counted open however its own header\n * read; and a report whose body discusses a status line later on was read the\n * same way. The status a report claims is a header FIELD, written beside\n * `- Classification:` above the first section, so that is the only place it is\n * read from. An unterminated fence swallows the rest of the file rather than\n * flipping back — the safe direction, since the alternative is reading code as\n * a field.\n *\n * Two shapes defeated the first version of that, and both are the same quoting\n * case: a NESTED fence, where the outer ```` opens and the inner ``` was taken\n * for its close, leaving the quoted block read as fields; and an INDENTED\n * block, which the protocol itself uses and whose indented `## Summary` never\n * ends the header either. So a fence is closed only by a run of the same\n * character at least as long as the one that opened it, and an indented block\n * (four spaces after a blank line, through the blank lines inside it) is\n * dropped whole.\n */\nfunction headerFields(text: string): string {\n  const kept: string[] = [];\n  let fence: string | null = null;\n  let indented = false;\n  let afterBlank = true;\n  for (const line of text.split(/\\r?\\n/)) {\n    if (fence !== null) {\n      const close = FENCE.exec(line)?.[1];\n      if (close !== undefined && close[0] === fence[0] && close.length >= fence.length) fence = null;\n      continue;\n    }\n    const blank = line.trim() === \"\";\n    if (indented) {\n      if (blank || INDENTED.test(line)) continue;\n      indented = false;\n    }\n    const open = FENCE.exec(line)?.[1];\n    if (open !== undefined) {\n      fence = open;\n      afterBlank = false;\n      continue;\n    }\n    if (afterBlank && INDENTED.test(line)) {\n      indented = true;\n      continue;\n    }\n    if (SECTION.test(line)) break;\n    kept.push(line);\n    afterBlank = blank;\n  }\n  return kept.join(\"\\n\");\n}\n\n/** The words a `Status:` line may say that loam can count. */\nconst STATED: readonly ProblemReportStatus[] = [\"open\", \"sent\", \"fixed\", \"superseded\"];\n\n/**\n * The ordinal the next report takes: one past the highest present, never one\n * past the count.\n *\n * Those two differ exactly when the directory has a gap or a legacy name in it\n * — which this directory does, since the numbering arrived after eleven\n * reports had already been written — and counting instead of maximising is how\n * a next ordinal starts handing out numbers that are already taken.\n */\nfunction nextOrdinal(entries: readonly ProblemReportEntry[]): string {\n  let highest = 0;\n  for (const entry of entries) {\n    if (entry.ordinal === null) continue;\n    const value = Number.parseInt(entry.ordinal, 10);\n    if (value > highest) highest = value;\n  }\n  return String(highest + 1).padStart(3, \"0\");\n}\n\n/**\n * What one report's own `Status:` line says, or `unstated`.\n *\n * Unreadable reads as unstated rather than throwing: a report saved as UTF-16,\n * a file the process cannot open, or a directory somebody named `notes.md` are\n * all things a diagnostic must survive. `doctor` is the command that has to be\n * able to describe a broken repository without becoming the next thing that\n * breaks in it.\n */\nasync function statusOf(path: string): Promise<ProblemReportStatus> {\n  let text: string;\n  try {\n    text = await readFile(path, \"utf8\");\n  } catch {\n    // Unreadable is not a state the file claims — it is a state of the read.\n    return \"unstated\";\n  }\n  const word = STATUS_LINE.exec(headerFields(text))?.[1]?.toLowerCase();\n  return STATED.find((known) => known === word) ?? \"unstated\";\n}\n\n/**\n * Read `<root>/loam-reports/`, where `root` is the directory holding the\n * `loam.json` that resolved — the repository the reports were written at the\n * root of — falling back, when nothing parsed, to the directory of the\n * `loam.json` loam FOUND (`doctor.ts` says why that and not the cwd), and to the\n * run directory only when there is no config file anywhere above it.\n *\n * Every `*.md` in the directory is an entry, including a hand-written index\n * page: which files in there are \"really\" reports is a second naming\n * convention, and inventing one would make loam disagree with a directory\n * listing about what the directory holds. An unnumbered entry contributes\n * nothing to `next`, so an index costs the corpus nothing either.\n */\nexport async function scanReports(root: string): Promise<ProblemReports> {\n  const dir = join(root, REPORTS_DIR);\n  let names: string[];\n  try {\n    names = (await readdir(dir)).filter((name) => name.toLowerCase().endsWith(\".md\"));\n  } catch (error) {\n    // Absent is the state of every repository that has never had to write a\n    // report, and it is the common one — `present: false`, nothing to say. Any\n    // other errno means the directory IS there and this process could not list\n    // it, which is a different sentence: the corpus exists and loam cannot see\n    // into it, so `present` stays true and the counts stay honestly empty.\n    const code = (error as NodeJS.ErrnoException).code;\n    const present = code !== \"ENOENT\" && code !== \"ENOTDIR\";\n    return { dir, present, total: 0, next: \"001\", entries: [] };\n  }\n\n  // Sorted here rather than left in readdir order, which is the filesystem's and\n  // differs between one machine and another — and sorted by the ORDINAL the name\n  // claims, numerically, because report order is what a reader scanning the list\n  // expects and byte order stops being it at exactly the point the widening rule\n  // was written for: `1000-…` sorts before `998-…`, so a directory that has\n  // passed its thousandth report reads 1000, 1001, 998, 999 (verification\n  // 2026-09-04, second pass). Unnumbered names — the shape reports carried before\n  // the numbering existed — contribute no ordinal, so they sort last among\n  // themselves by name, where a reader looking for \"the next one\" is not looking.\n  const rank = (file: string): number => {\n    const ordinal = ordinalOf(file);\n    return ordinal === null ? Number.POSITIVE_INFINITY : Number.parseInt(ordinal, 10);\n  };\n  names.sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : a > b ? 1 : 0));\n  // Read together, like `staleAgentFiles` does: a report corpus is a flat\n  // directory of small hand-written files, so there is nothing here worth a\n  // concurrency cap, and `Promise.all` preserves the order just established.\n  const entries = await Promise.all(names.map(async (file): Promise<ProblemReportEntry> => ({\n    file,\n    ordinal: ordinalOf(file),\n    status: await statusOf(join(dir, file)),\n  })));\n\n  return {\n    dir,\n    present: true,\n    total: entries.length,\n    next: nextOrdinal(entries),\n    entries,\n  };\n}\n"]}

package/dist/core/doctor/residue.js

@@ -0,0 +1,110 @@
+/**
+ * What an unfinished write means for the health of the repo.
+ *
+ * `core/staging/recovery/residue.ts` reports what is on disk; this decides how
+ * bad it is. A held lock and an interrupted commit are blockers because the docs
+ * are, or may be, half-merged: a SIGKILL between two of archive's renames once
+ * left `doctor: healthy: true` over a merged spec.md and an unmerged landscape,
+ * and the next `loam archive` reported loam's own half-merge as the author's
+ * bug. Temp files are the exception — a `.loam-*.tmp` was never linked into
+ * place, so nothing reads it. Litter, not damage.
+ */
+import { join } from "node:path";
+import {} from "../staging/recovery/residue.js";
+import {} from "./report.js";
+export function gradeWritePathResidue(docsDir, residue, findings) {
+    if (residue.lock !== null) {
+        const lockFile = join(docsDir, residue.lock.path);
+        // Three grades of one file. Held by a live process is a fact about right
+        // now — wait and re-run. Held by a dead process is damage: nothing will
+        // ever release it. And a lock that cannot NAME a holder — empty bytes from
+        // a crash between create and flush, or JSON nothing understands — is the
+        // same damage wearing a live lock's face: `breakStaleLock` rightly refuses
+        // to guess about it, so "wait" is advice that can never work, while every
+        // writer (archive, unarchive, rebase, verify --record) refuses `docs-busy`
+        // forever.
+        const unbreakable = residue.lock.stale || residue.lock.unreadable;
+        findings.push({
+            severity: unbreakable ? "blocker" : "warning",
+            code: "doctor.docs-locked",
+            message: residue.lock.unreadable
+                ? `${residue.lock.path} exists but cannot be read as a lock record — no process can be identified as its holder, so nothing is ever going to release it, and every writing command refuses with \`docs-busy\` while it is there.`
+                : residue.lock.stale
+                    ? `${residue.lock.path} is held by ${residue.lock.holder}, a process that no longer exists on this host — every command that writes through this root will refuse with \`docs-busy\` until it is gone.`
+                    : `${residue.lock.path} is held by ${residue.lock.holder}; another loam command is writing through this root.`,
+            fix: unbreakable
+                ? `Delete ${lockFile} — ${residue.lock.unreadable ? "it names no holder, so nothing is going to release it" : "its holder is dead, so nothing is going to release it"}. Check \`loam doctor\` again afterwards for an interrupted commit.`
+                : "Wait for it to finish and re-run; nothing is read or written while it is held.",
+        });
+    }
+    if (residue.intentUnreadable) {
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-unreadable",
+            message: `${docsDir} holds a .loam-commit that cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable.`,
+            fix: "Hand this to a human: compare this root's files against version control before running any loam command that writes here. Every journaled writer refuses with `commit-interrupted` while it is there.",
+        });
+    }
+    else if (residue.intent !== null && "rerun" in residue.intent) {
+        // Version 2 — the smaller journaled transaction (rebase, vouch, new,
+        // gherkin, and any writer after them). Its stored `rerun` IS the repair:
+        // that command recovers first, rolling the staged bytes forward. The
+        // string is journal data, so agent-commands-runnable cannot parse it here;
+        // test/staging-txn.test.ts parses every writer's rerun template against
+        // the real program instead.
+        const i = residue.intent;
+        // Both halves of the journal are named, because a version-3 record can be
+        // rename-only (`subsystem move` where the views bytes did not change): a
+        // blocker that said "0 file(s) may be half-written" and named nothing sent
+        // the operator hunting for files while the pending damage was directories.
+        const halves = [
+            ...(i.files.length > 0 ? [`${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(", ")}`] : []),
+            ...(i.moves.length > 0
+                ? [`${i.moves.length} directory move(s) pending: ${i.moves.map((m) => `${m.from} -> ${m.to}`).join(", ")}`]
+                : []),
+        ];
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-interrupted",
+            message: `A \`${i.rerun}\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `
+                + (halves.length > 0 ? halves.join("; ") : "its journal records no pending file or directory"),
+            fix: `Re-run \`${i.rerun}\` — it recovers first, rolling the staged bytes forward, and refuses with \`commit-interrupted\` rather than guessing if a file has been edited since.`,
+        });
+    }
+    else if (residue.intent !== null) {
+        const i = residue.intent;
+        // The command is spelled out per branch rather than interpolated into one
+        // sentence: `loam ${i.command} ${i.feature}` reads fine to a person and is
+        // opaque to test/agent-commands-runnable.test.ts, which parses the commands
+        // loam prints against the real program. Same discipline as spelling `code:`
+        // literally — be visible to your own guard.
+        const repair = i.command === "archive"
+            ? `\`loam archive ${i.feature}\` — it recovers first, under the lock, putting the half-written files back from the snapshot`
+            : `\`loam unarchive ${i.feature}\` — it recovers first, under the lock, finishing the restore (an interrupted restore is FINISHED, never undone: the merged text it was replacing is written down nowhere)`;
+        findings.push({
+            severity: "blocker",
+            code: "doctor.commit-interrupted",
+            message: `A ${i.command === "archive" ? `\`loam archive ${i.feature}\`` : `\`loam unarchive ${i.feature}\``} `
+                + `was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `
+                + `${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(", ")}`,
+            fix: `Re-run ${repair}, and refuses with \`commit-interrupted\` rather than guessing if a file has been edited since.`,
+        });
+    }
+    // A version-2 journal's recorded temps are NOT litter: they are the only
+    // durable copy of the after-bytes its roll-forward recovery renames in.
+    // Advising their deletion beside a blocker that says "re-run to recover"
+    // converted a one-command repair into a manual VCS restore.
+    const journalTemps = new Set(residue.intent !== null && "rerun" in residue.intent
+        ? residue.intent.files.flatMap((f) => (f.tmp === null ? [] : [f.tmp]))
+        : []);
+    const litter = residue.temps.filter((t) => !journalTemps.has(t));
+    if (litter.length > 0) {
+        findings.push({
+            severity: "warning",
+            code: "doctor.staging-temps",
+            message: `${litter.length} orphaned staging file(s) under ${docsDir}: ${litter.join(", ")} — a killed writer's scratch, never linked into place.`,
+            fix: "The next journaled writer through this root removes its own; delete any that remain. Nothing reads them, so they cost disk and nothing else.",
+        });
+    }
+}
+//# sourceMappingURL=residue.js.map

package/dist/core/doctor/residue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residue.js","sourceRoot":"","sources":["../../../src/core/doctor/residue.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an unfinished write means for the health of the repo.\n *\n * `core/staging/recovery/residue.ts` reports what is on disk; this decides how\n * bad it is. A held lock and an interrupted commit are blockers because the docs\n * are, or may be, half-merged: a SIGKILL between two of archive's renames once\n * left `doctor: healthy: true` over a merged spec.md and an unmerged landscape,\n * and the next `loam archive` reported loam's own half-merge as the author's\n * bug. Temp files are the exception — a `.loam-*.tmp` was never linked into\n * place, so nothing reads it. Litter, not damage.\n */\nimport { join } from \"node:path\";\nimport { type WritePathResidue } from \"../staging/recovery/residue.js\";\nimport { type DoctorFinding } from \"./report.js\";\n\nexport function gradeWritePathResidue(\n  docsDir: string,\n  residue: WritePathResidue,\n  findings: DoctorFinding[],\n): void {\n  if (residue.lock !== null) {\n    const lockFile = join(docsDir, residue.lock.path);\n    // Three grades of one file. Held by a live process is a fact about right\n    // now — wait and re-run. Held by a dead process is damage: nothing will\n    // ever release it. And a lock that cannot NAME a holder — empty bytes from\n    // a crash between create and flush, or JSON nothing understands — is the\n    // same damage wearing a live lock's face: `breakStaleLock` rightly refuses\n    // to guess about it, so \"wait\" is advice that can never work, while every\n    // writer (archive, unarchive, rebase, verify --record) refuses `docs-busy`\n    // forever.\n    const unbreakable = residue.lock.stale || residue.lock.unreadable;\n    findings.push({\n      severity: unbreakable ? \"blocker\" : \"warning\",\n      code: \"doctor.docs-locked\",\n      message: residue.lock.unreadable\n        ? `${residue.lock.path} exists but cannot be read as a lock record — no process can be identified as its holder, so nothing is ever going to release it, and every writing command refuses with \\`docs-busy\\` while it is there.`\n        : residue.lock.stale\n          ? `${residue.lock.path} is held by ${residue.lock.holder}, a process that no longer exists on this host — every command that writes through this root will refuse with \\`docs-busy\\` until it is gone.`\n          : `${residue.lock.path} is held by ${residue.lock.holder}; another loam command is writing through this root.`,\n      fix: unbreakable\n        ? `Delete ${lockFile} — ${residue.lock.unreadable ? \"it names no holder, so nothing is going to release it\" : \"its holder is dead, so nothing is going to release it\"}. Check \\`loam doctor\\` again afterwards for an interrupted commit.`\n        : \"Wait for it to finish and re-run; nothing is read or written while it is held.\",\n    });\n  }\n\n  if (residue.intentUnreadable) {\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-unreadable\",\n      message: `${docsDir} holds a .loam-commit that cannot be read — a commit was interrupted and the one record of which files it had already written is unreadable.`,\n      fix: \"Hand this to a human: compare this root's files against version control before running any loam command that writes here. Every journaled writer refuses with `commit-interrupted` while it is there.\",\n    });\n  } else if (residue.intent !== null && \"rerun\" in residue.intent) {\n    // Version 2 — the smaller journaled transaction (rebase, vouch, new,\n    // gherkin, and any writer after them). Its stored `rerun` IS the repair:\n    // that command recovers first, rolling the staged bytes forward. The\n    // string is journal data, so agent-commands-runnable cannot parse it here;\n    // test/staging-txn.test.ts parses every writer's rerun template against\n    // the real program instead.\n    const i = residue.intent;\n    // Both halves of the journal are named, because a version-3 record can be\n    // rename-only (`subsystem move` where the views bytes did not change): a\n    // blocker that said \"0 file(s) may be half-written\" and named nothing sent\n    // the operator hunting for files while the pending damage was directories.\n    const halves = [\n      ...(i.files.length > 0 ? [`${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(\", \")}`] : []),\n      ...(i.moves.length > 0\n        ? [`${i.moves.length} directory move(s) pending: ${i.moves.map((m) => `${m.from} -> ${m.to}`).join(\", \")}`]\n        : []),\n    ];\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-interrupted\",\n      message:\n        `A \\`${i.rerun}\\` was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `\n        + (halves.length > 0 ? halves.join(\"; \") : \"its journal records no pending file or directory\"),\n      fix: `Re-run \\`${i.rerun}\\` — it recovers first, rolling the staged bytes forward, and refuses with \\`commit-interrupted\\` rather than guessing if a file has been edited since.`,\n    });\n  } else if (residue.intent !== null) {\n    const i = residue.intent;\n    // The command is spelled out per branch rather than interpolated into one\n    // sentence: `loam ${i.command} ${i.feature}` reads fine to a person and is\n    // opaque to test/agent-commands-runnable.test.ts, which parses the commands\n    // loam prints against the real program. Same discipline as spelling `code:`\n    // literally — be visible to your own guard.\n    const repair = i.command === \"archive\"\n      ? `\\`loam archive ${i.feature}\\` — it recovers first, under the lock, putting the half-written files back from the snapshot`\n      : `\\`loam unarchive ${i.feature}\\` — it recovers first, under the lock, finishing the restore (an interrupted restore is FINISHED, never undone: the merged text it was replacing is written down nowhere)`;\n    findings.push({\n      severity: \"blocker\",\n      code: \"doctor.commit-interrupted\",\n      message:\n        `A ${i.command === \"archive\" ? `\\`loam archive ${i.feature}\\`` : `\\`loam unarchive ${i.feature}\\``} `\n        + `was killed mid-commit (${i.host}, pid ${i.pid}, ${i.at}) — `\n        + `${i.files.length} file(s) may be half-written: ${i.files.map((f) => f.path).join(\", \")}`,\n      fix: `Re-run ${repair}, and refuses with \\`commit-interrupted\\` rather than guessing if a file has been edited since.`,\n    });\n  }\n\n  // A version-2 journal's recorded temps are NOT litter: they are the only\n  // durable copy of the after-bytes its roll-forward recovery renames in.\n  // Advising their deletion beside a blocker that says \"re-run to recover\"\n  // converted a one-command repair into a manual VCS restore.\n  const journalTemps = new Set(\n    residue.intent !== null && \"rerun\" in residue.intent\n      ? residue.intent.files.flatMap((f) => (f.tmp === null ? [] : [f.tmp]))\n      : [],\n  );\n  const litter = residue.temps.filter((t) => !journalTemps.has(t));\n  if (litter.length > 0) {\n    findings.push({\n      severity: \"warning\",\n      code: \"doctor.staging-temps\",\n      message: `${litter.length} orphaned staging file(s) under ${docsDir}: ${litter.join(\", \")} — a killed writer's scratch, never linked into place.`,\n      fix: \"The next journaled writer through this root removes its own; delete any that remain. Nothing reads them, so they cost disk and nothing else.\",\n    });\n  }\n}\n"]}

package/dist/core/document/apply.js

@@ -0,0 +1,224 @@
+/**
+ * A feature's ADDED/MODIFIED/REMOVED requirements folded onto a living set.
+ *
+ * The one thing `loam archive` does to a spec, and a module of its own because
+ * it is where a requirement stops being a delta: `asLiving` drops the
+ * `Based-On:` pin, which is a claim about which living version this was written
+ * against — meaningless once it IS the living version, and poison for the next
+ * feature's baseline, which would otherwise hash the previous feature's pin.
+ *
+ * It is also where the merge says what it TAKES AWAY (`replacementsOf`,
+ * `droppedParts`), because only the algebra knows which living requirement a
+ * delta requirement selects: a MODIFIED carries its full new text and replaces
+ * the living requirement whole, so every scenario and every join line it does
+ * not restate is gone after the archive — and a second reading of "which one
+ * does this select" anywhere else would be a second answer free to disagree.
+ */
+import { requirementIdProblems, splitRealizesPin, withoutBaseline } from "./spec.js";
+/**
+ * A delta requirement as it lands in the living document, with the bookkeeping
+ * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about
+ * which living version this was written against — meaningless once it IS the
+ * living version, and poison for the next feature's baseline, which would then
+ * hash the previous feature's pin) and the line it was parsed from.
+ */
+function asLiving(d) {
+    const { line: _dropped, ...rest } = withoutBaseline(d);
+    return { ...rest, kind: "BASE" };
+}
+/**
+ * Apply a feature's ADDED/MODIFIED/REMOVED requirements onto a living requirement set.
+ *
+ * A living requirement the delta does not touch comes back as the SAME object
+ * it went in as (a living spec's requirements are already BASE), and that
+ * identity is load-bearing: archive keys each requirement's raw bytes on it, so
+ * an untouched requirement is written back exactly as its author wrote it and
+ * only the ones this function replaced or added are serialized.
+ */
+export function applyRequirementDelta(living, delta) {
+    return foldDelta(living, delta).merged;
+}
+/**
+ * Every living requirement the delta replaces or removes, in delta order — the
+ * walk `applyRequirementDelta` takes, so the two cannot disagree about which
+ * requirement a MODIFIED selected. Throws exactly when the merge would.
+ */
+export function replacementsOf(living, delta) {
+    return foldDelta(living, delta).replaced;
+}
+function foldDelta(living, delta) {
+    const malformed = [...requirementIdProblems(living), ...requirementIdProblems(delta)];
+    if (malformed.length > 0) {
+        throw new Error("cannot merge requirements with invalid, repeated, or duplicate Requirement-ID declarations");
+    }
+    let result = living.map((r) => (r.kind === "BASE" ? r : { ...r, kind: "BASE" }));
+    const replaced = [];
+    // What each requirement the fold has PRODUCED stands for: the replacement
+    // record it belongs to, or null for one this delta added. A delta may select
+    // one requirement twice (nothing refuses a repeated heading in a delta), and
+    // without this the second step reported the first step's text as "living" —
+    // a drop the merge never makes. With it every record stays pre-merge to
+    // post-merge, so what `droppedParts` reads is the net change.
+    const born = new Map();
+    const record = (kind, previous, merged) => {
+        const earlier = born.get(previous);
+        if (earlier === undefined) {
+            const entry = { kind, living: previous, merged };
+            replaced.push(entry);
+            if (merged !== null)
+                born.set(merged, entry);
+        }
+        else if (earlier === null) {
+            // Added by this delta, so nothing living is replaced by rewriting it.
+            if (merged !== null)
+                born.set(merged, null);
+        }
+        else {
+            earlier.merged = merged;
+            if (merged === null)
+                earlier.kind = "REMOVED";
+            else
+                born.set(merged, earlier);
+        }
+    };
+    const add = (merged) => {
+        born.set(merged, null);
+        result.push(merged);
+    };
+    for (const d of delta) {
+        // BASE is not a delta kind — a requirement outside an ADDED/MODIFIED/REMOVED
+        // section (e.g. quoted under ## Notes) is documentation, not a change.
+        if (d.kind === "BASE")
+            continue;
+        const kind = d.kind;
+        if (d.id !== undefined) {
+            const idMatches = result
+                .map((r, i) => (r.id === d.id ? i : -1))
+                .filter((i) => i >= 0);
+            const nameMatches = result
+                .map((r, i) => (r.name === d.name ? i : -1))
+                .filter((i) => i >= 0);
+            const otherNameMatches = nameMatches.filter((i) => !idMatches.includes(i));
+            if (idMatches.length > 1 || otherNameMatches.length > 0) {
+                throw new Error(`ambiguous requirement identity for '${d.name}' (${d.id}): Requirement-ID and heading select different living requirements`);
+            }
+            if (d.kind === "REMOVED") {
+                const selected = new Set(idMatches);
+                for (const i of idMatches)
+                    record(kind, result[i], null);
+                result = result.filter((_, i) => !selected.has(i));
+            }
+            else {
+                const merged = asLiving(d);
+                const at = idMatches[0];
+                if (at === undefined)
+                    add(merged);
+                else {
+                    record(kind, result[at], merged);
+                    result[at] = merged;
+                }
+            }
+        }
+        else if (d.kind === "REMOVED") {
+            for (const r of result)
+                if (r.name === d.name)
+                    record(kind, r, null);
+            result = result.filter((r) => r.name !== d.name);
+        }
+        else {
+            const i = result.findIndex((r) => r.name === d.name);
+            // A legacy delta may still modify an ID-bearing living requirement by
+            // its exact heading. Keep the identity while the repository migrates.
+            const inheritedId = i >= 0 ? result[i].id : undefined;
+            const merged = {
+                ...asLiving(d),
+                ...(inheritedId === undefined ? {} : { id: inheritedId }),
+            };
+            if (i < 0)
+                add(merged);
+            else {
+                record(kind, result[i], merged);
+                result[i] = merged;
+            }
+        }
+    }
+    return { merged: result, replaced };
+}
+/**
+ * The join lines a requirement carries, keyed by `Requirement` field and
+ * spelled as the body line writes them — every list the parser reads out of a
+ * requirement's text, in one order, so the archive plan, `loam delta` and their
+ * `--json` rows name a dropped entry the same way.
+ */
+export const DIRECTIVE_LINES = {
+    operations: "Operations",
+    covers: "Covers",
+    requires: "Requires",
+    capabilities: "Capability",
+    realizes: "Realizes",
+    publishes: "Publishes",
+    consumes: "Consumes",
+};
+/**
+ * What a replacement drops: the living scenarios its new text does not carry,
+ * by name, and each join-line entry it does not restate, verbatim.
+ *
+ * VERBATIM AND BY NAME, and that is a reading, not a judgement — with one
+ * exception for bookkeeping: a `Realizes:` entry is compared, and reported, by
+ * the target it names, its `@<digest>` pin set aside. A scenario
+ * renamed is reported dropped, and a `Covers:` entry respelled from an element
+ * id to the service name is reported dropped too, though either may mean the
+ * same thing — this lists what the living text says that the merged text does
+ * not, and the author decides. What it must never be again is the old answer,
+ * which was nothing: a MODIFIED that restated one of two scenarios merged, and
+ * the second vanished under the archive's exit 0.
+ */
+export function droppedParts(replacement) {
+    const { living, merged } = replacement;
+    const keptScenarios = new Set((merged?.scenarios ?? []).map((s) => s.name));
+    const directives = {};
+    for (const key of Object.keys(DIRECTIVE_LINES)) {
+        // A `Realizes:` entry is compared by the target it names: the `@<digest>`
+        // pin `loam rebase --living` writes is bookkeeping, and a replacement that
+        // restates the target unpinned has kept the join, not dropped it.
+        const spell = key === "realizes" ? (entry) => splitRealizesPin(entry).target : (entry) => entry;
+        const kept = new Set((merged?.[key] ?? []).map(spell));
+        const gone = [...new Set(living[key].map(spell))].filter((entry) => !kept.has(entry));
+        if (gone.length > 0)
+            directives[key] = gone;
+    }
+    return { scenarios: living.scenarios.map((s) => s.name).filter((name) => !keptScenarios.has(name)), directives };
+}
+/** Does this replacement take anything away at all? */
+export function dropsAnything(parts) {
+    return parts.scenarios.length > 0 || Object.keys(parts.directives).length > 0;
+}
+/**
+ * Every replacement that takes something away: a removal always (the
+ * requirement itself is what goes), a MODIFIED or a landing ADDED whenever its
+ * new text restates less than the living one held.
+ */
+export function droppedBy(living, delta) {
+    return replacementsOf(living, delta).flatMap((replacement) => {
+        const parts = droppedParts(replacement);
+        if (replacement.kind !== "REMOVED" && !dropsAnything(parts))
+            return [];
+        const { name, id } = replacement.living;
+        return [{ kind: replacement.kind, requirement: name, ...(id === undefined ? {} : { id }), ...parts }];
+    });
+}
+/** One dropped row in words — the line the archive plan and `loam delta` both print. */
+export function droppedSentence(row) {
+    const who = row.id === undefined ? `'${row.requirement}'` : `${row.id} '${row.requirement}'`;
+    const lost = [
+        ...(row.scenarios.length === 0 ? [] : [`scenario ${row.scenarios.map((s) => `'${s}'`).join(", ")}`]),
+        ...Object.keys(DIRECTIVE_LINES).flatMap((key) => {
+            const gone = row.directives[key];
+            return gone === undefined ? [] : [`${DIRECTIVE_LINES[key]}: ${gone.join(", ")}`];
+        }),
+    ];
+    if (row.kind === "REMOVED")
+        return lost.length === 0 ? `${who} is removed` : `${who} is removed, and with it ${lost.join("; ")}`;
+    return `${who} is replaced whole, and its new text does not carry ${lost.join("; ")}`;
+}
+//# sourceMappingURL=apply.js.map