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

package/dist/core/scaffold/landscape.js

@@ -0,0 +1,131 @@
+/**
+ * The bytes a brand-new docs repo's fleet map starts with, and the one
+ * question anybody asks of them afterwards: has a human touched this yet?
+ *
+ * Split out of `../docs.ts` when the README joined the scaffold and the file
+ * reached its line limit, and the seam was already there: `docs.ts` says what
+ * a docs repo is MADE OF — which directories, which files, in what order —
+ * while this package holds the CONTENT of the authored templates it lays down.
+ * The two change for different reasons: a new artifact edits the first, better
+ * advice to a new fleet edits the second.
+ */
+/**
+ * The fleet map, empty but valid.
+ *
+ * Nobody writes this file automatically — `adopt` deliberately does not touch
+ * it, because who calls whom is a human judgement and a generated landscape
+ * would be a guess presented as the map. But "nobody writes it" used to mean
+ * "it is simply absent", and an absent landscape is the one artifact whose
+ * absence silences the fleet-wide checks entirely: every cross-service breach
+ * `validate` exists to find is invisible on a repo with no landscape.
+ *
+ * So the scaffold lays down the empty map instead: the four element kinds a
+ * fleet actually uses are declared, the model is empty, and the comments say
+ * what to add and why. The first `loam adopt` then has somewhere to be drawn.
+ *
+ * A `views` block IS scaffolded — reversing the decision this comment used to
+ * record, which was: no views, because computing one is superlinear in edge
+ * count and a scaffolded `include *` handed every repo a fleet-sized bill for
+ * the first tool that renders. That cost was real and still is; what changed
+ * is the shape of the block. A fleet map stops being readable at the third
+ * service unless platform infrastructure is split out, and the split's
+ * `exclude element.tag = #platform` is exactly the
+ * pruning that keeps the fleet view's render affordable — the scaffold now
+ * pays the old objection instead of ignoring it. loam itself still reads
+ * elements and relationships and never a view. The platform view's predicate
+ * is scaffolded because it is the line users mistype: the obvious spelling
+ * draws boxes with no edges.
+ * The `views` block below has a deliberate second copy: `core/c4/seed/template.ts` emits the
+ * same two views into a seeded landscape (two strikes; extract on a third), and test/seed.test.ts
+ * compares the two blocks byte for byte — comments included — so whichever copy drifts fails.
+ */
+export const LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call
+// between two of them is an edge. This file is written by hand — loam never
+// guesses it, because "who calls whom" is the one fact no generator can read
+// off a repository.
+//
+// After \`loam adopt --service <id>\`, add the service here:
+//
+//   paymentService = softwareSystem 'payment-service' {
+//     description 'Owns payment authorization/capture'
+//     metadata { service 'payment-service' }   // binds the box to services/<id>/
+//   }
+//
+// and give each call the operationId it uses, so requirements, C4 and OpenAPI
+// can be cross-checked:
+//
+//   checkoutWeb -> paymentService 'Authorizes' {
+//     metadata { op 'authorizePayment' }
+//   }
+//
+// The \`views\` block at the bottom is for LikeC4's own tooling — loam reads
+// the model and never a view. Render with \`npx likec4 start\` from the docs
+// repo root, which likec4.config.json scopes to this directory. (A service
+// model or a feature delta renders from its OWN directory, e.g.
+// \`npx likec4 start services/<id>\`: each declares its own \`specification\`
+// block, so the renderer can only be given one of them at a time.) Keep views
+// scoped, because computing one is superlinear in the number of edges — the
+// \`fleet\` view below stays affordable precisely because it excludes the
+// platform hubs.
+//
+// One shape is worth getting right before the fleet is drawn: a shared broker.
+// Kafka as a single element becomes the node every service points at, and any
+// view over it is a star nobody can read. Model the TOPIC instead — a \`topic\`
+// nested inside the broker's element, edges pointing at \`kafka.<topic>\` — which
+// splits one hub of degree sixty into a dozen small ones and is the truer model
+// besides. Tag the KIND, not just the broker: LikeC4 does not inherit tags, so a
+// topic under an \`#external\` broker is not external itself and \`validate\` asks
+// for a services/ directory nobody owes.
+//
+//   specification {
+//     element topic {
+//       #external
+//       style { shape queue }
+//     }
+//   }
+
+specification {
+  element person
+  element softwareSystem
+  element container
+  element database
+
+  // Ubiquitous infrastructure — logging Kafka, auth, service discovery — takes
+  // one inbound edge per service, and by the third service the fleet view is a
+  // hairball. Tag those elements #platform: the fleet view excludes them
+  // without losing "who depends on the Identity Provider", which the platform
+  // view answers.
+  tag platform
+}
+
+model {
+}
+
+views {
+  view fleet {
+    include *
+    exclude element.tag = #platform
+  }
+  // The obvious spelling — \`include element.tag = #platform\` — draws the
+  // platform boxes with NO edges and no consumers. The predicate that works is
+  // the relationship form below.
+  view platform {
+    include * -> element.tag = #platform
+  }
+}
+`;
+/**
+ * Whether the fleet map is still the scaffold's own bytes — the sentinel
+ * doctrine of core/coherence/authoring/sentinels.ts: the writer above and this
+ * checker read ONE string, so they cannot drift apart. `endsWith`, not
+ * equality, because `migrate-openspec` prepends a `landscapePreamble` to the
+ * identical stub; CRLF-normalised because a checkout under core.autocrlf is
+ * still untouched. A hand-edit inside the stub body breaks the suffix match —
+ * the safe failure mode is a false "authored", which merely drops one teaching
+ * step from `loam status`'s empty-fleet ladder (core/status/fleet/next.ts).
+ */
+export function isLandscapeStub(content) {
+    const normal = (s) => s.replace(/\r\n/g, "\n").trimEnd();
+    return normal(content).endsWith(normal(LANDSCAPE_STUB));
+}
+//# sourceMappingURL=landscape.js.map

package/dist/core/scaffold/landscape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../src/core/scaffold/landscape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0E7B,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;IACzE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * The bytes a brand-new docs repo's fleet map starts with, and the one\n * question anybody asks of them afterwards: has a human touched this yet?\n *\n * Split out of `../docs.ts` when the README joined the scaffold and the file\n * reached its line limit, and the seam was already there: `docs.ts` says what\n * a docs repo is MADE OF — which directories, which files, in what order —\n * while this package holds the CONTENT of the authored templates it lays down.\n * The two change for different reasons: a new artifact edits the first, better\n * advice to a new fleet edits the second.\n */\n\n/**\n * The fleet map, empty but valid.\n *\n * Nobody writes this file automatically — `adopt` deliberately does not touch\n * it, because who calls whom is a human judgement and a generated landscape\n * would be a guess presented as the map. But \"nobody writes it\" used to mean\n * \"it is simply absent\", and an absent landscape is the one artifact whose\n * absence silences the fleet-wide checks entirely: every cross-service breach\n * `validate` exists to find is invisible on a repo with no landscape.\n *\n * So the scaffold lays down the empty map instead: the four element kinds a\n * fleet actually uses are declared, the model is empty, and the comments say\n * what to add and why. The first `loam adopt` then has somewhere to be drawn.\n *\n * A `views` block IS scaffolded — reversing the decision this comment used to\n * record, which was: no views, because computing one is superlinear in edge\n * count and a scaffolded `include *` handed every repo a fleet-sized bill for\n * the first tool that renders. That cost was real and still is; what changed\n * is the shape of the block. A fleet map stops being readable at the third\n * service unless platform infrastructure is split out, and the split's\n * `exclude element.tag = #platform` is exactly the\n * pruning that keeps the fleet view's render affordable — the scaffold now\n * pays the old objection instead of ignoring it. loam itself still reads\n * elements and relationships and never a view. The platform view's predicate\n * is scaffolded because it is the line users mistype: the obvious spelling\n * draws boxes with no edges.\n * The `views` block below has a deliberate second copy: `core/c4/seed/template.ts` emits the\n * same two views into a seeded landscape (two strikes; extract on a third), and test/seed.test.ts\n * compares the two blocks byte for byte — comments included — so whichever copy drifts fails.\n */\nexport const LANDSCAPE_STUB = `// The fleet map: every service in services/ appears here, and every call\n// between two of them is an edge. This file is written by hand — loam never\n// guesses it, because \"who calls whom\" is the one fact no generator can read\n// off a repository.\n//\n// After \\`loam adopt --service <id>\\`, add the service here:\n//\n//   paymentService = softwareSystem 'payment-service' {\n//     description 'Owns payment authorization/capture'\n//     metadata { service 'payment-service' }   // binds the box to services/<id>/\n//   }\n//\n// and give each call the operationId it uses, so requirements, C4 and OpenAPI\n// can be cross-checked:\n//\n//   checkoutWeb -> paymentService 'Authorizes' {\n//     metadata { op 'authorizePayment' }\n//   }\n//\n// The \\`views\\` block at the bottom is for LikeC4's own tooling — loam reads\n// the model and never a view. Render with \\`npx likec4 start\\` from the docs\n// repo root, which likec4.config.json scopes to this directory. (A service\n// model or a feature delta renders from its OWN directory, e.g.\n// \\`npx likec4 start services/<id>\\`: each declares its own \\`specification\\`\n// block, so the renderer can only be given one of them at a time.) Keep views\n// scoped, because computing one is superlinear in the number of edges — the\n// \\`fleet\\` view below stays affordable precisely because it excludes the\n// platform hubs.\n//\n// One shape is worth getting right before the fleet is drawn: a shared broker.\n// Kafka as a single element becomes the node every service points at, and any\n// view over it is a star nobody can read. Model the TOPIC instead — a \\`topic\\`\n// nested inside the broker's element, edges pointing at \\`kafka.<topic>\\` — which\n// splits one hub of degree sixty into a dozen small ones and is the truer model\n// besides. Tag the KIND, not just the broker: LikeC4 does not inherit tags, so a\n// topic under an \\`#external\\` broker is not external itself and \\`validate\\` asks\n// for a services/ directory nobody owes.\n//\n//   specification {\n//     element topic {\n//       #external\n//       style { shape queue }\n//     }\n//   }\n\nspecification {\n  element person\n  element softwareSystem\n  element container\n  element database\n\n  // Ubiquitous infrastructure — logging Kafka, auth, service discovery — takes\n  // one inbound edge per service, and by the third service the fleet view is a\n  // hairball. Tag those elements #platform: the fleet view excludes them\n  // without losing \"who depends on the Identity Provider\", which the platform\n  // view answers.\n  tag platform\n}\n\nmodel {\n}\n\nviews {\n  view fleet {\n    include *\n    exclude element.tag = #platform\n  }\n  // The obvious spelling — \\`include element.tag = #platform\\` — draws the\n  // platform boxes with NO edges and no consumers. The predicate that works is\n  // the relationship form below.\n  view platform {\n    include * -> element.tag = #platform\n  }\n}\n`;\n\n/**\n * Whether the fleet map is still the scaffold's own bytes — the sentinel\n * doctrine of core/coherence/authoring/sentinels.ts: the writer above and this\n * checker read ONE string, so they cannot drift apart. `endsWith`, not\n * equality, because `migrate-openspec` prepends a `landscapePreamble` to the\n * identical stub; CRLF-normalised because a checkout under core.autocrlf is\n * still untouched. A hand-edit inside the stub body breaks the suffix match —\n * the safe failure mode is a false \"authored\", which merely drops one teaching\n * step from `loam status`'s empty-fleet ladder (core/status/fleet/next.ts).\n */\nexport function isLandscapeStub(content: string): boolean {\n  const normal = (s: string): string => s.replace(/\\r\\n/g, \"\\n\").trimEnd();\n  return normal(content).endsWith(normal(LANDSCAPE_STUB));\n}\n"]}

package/dist/core/scaffold/readme.js

@@ -0,0 +1,84 @@
+/**
+ * The README a new docs repo starts with — the one file in it addressed to a
+ * person.
+ *
+ * Everything else the scaffold lays down is either a document about the
+ * governed system or `AGENTS.md`, which is 1500 lines written for a coding
+ * agent and named so that a human does not open it. A forge renders `README.md`
+ * as the repository's landing page and nothing else, so without this file a
+ * docs repo opens as a bare directory listing: four folders and two config
+ * files, and no sentence anywhere saying what any of it is.
+ *
+ * Deliberately SHORT, and deliberately not a second copy of anything. The
+ * layout table and the cycle are AGENTS.md's, in full; this page says what the
+ * repo is, points at the three commands a person actually types, and hands off.
+ * A README that restated the contract would be a second thing to keep true, and
+ * the first one to go stale.
+ */
+export const README_FILENAME = "README.md";
+export const README_MD = `# Architecture & specs
+
+This repository is a governed system's **source of truth**: its architecture,
+requirements, contracts, domain vocabulary and verification evidence, kept in
+explicit agreement. It is plain files — Markdown, YAML and LikeC4 — reviewed like
+code, in pull requests.
+
+In paths and commands, loam calls one governed implementation boundary a
+**service**. That boundary may be a modular monolith, a network service, a CLI or
+a worker. Nested C4 elements remain modules or components unless they need their
+own repository binding, contracts, evidence and deployment boundary.
+
+It is read and written with [**loam**](https://github.com/ybotok/loam). Delete
+loam and these documents still make sense; that is the point of keeping them this
+way.
+
+## What is where
+
+| | |
+|---|---|
+| \`architecture/landscape.likec4\` | the system map — governed boundaries, nested structure and their relationships |
+| \`services/<id>/\` | one directory per governed boundary: what it promises, exposes and verifies |
+| \`features/<FEAT>/\` | a change in flight — why it exists, and the delta it makes to the documents above |
+| \`features/archive/\` | changes that shipped; their deltas are already merged into the living documents |
+
+A directory under \`services/\` that holds a \`subsystem.yaml\` is a **group**, not
+a service — services can be filed inside one at any depth.
+
+## If you are new here
+
+\`\`\`bash
+loam status
+\`\`\`
+
+It reads the files and tells you where things stand and what to do next, ordered
+most-unblocking first, with the exact command for each step. Nothing in this
+repository is generated from a database or a server — if \`loam status\` says
+something, a file said it first.
+
+To check the whole repository the way CI does:
+
+\`\`\`bash
+loam validate --all
+\`\`\`
+
+And when a finding's code means nothing to you:
+
+\`\`\`bash
+loam explain <code>
+\`\`\`
+
+## Changing something
+
+Documents here are edited through a **feature**: \`loam new <FEAT>\` scaffolds one,
+you write the intent and the deltas, \`loam validate --feature <FEAT>\` grades it,
+and \`loam archive <FEAT>\` merges it into the living documents. Living documents
+are not edited directly once a boundary is adopted — the feature is the
+reviewable unit, and the archive is what makes the change traceable afterwards.
+
+## For coding agents
+
+\`AGENTS.md\` in this directory is the full contract: the layout in detail, the
+authoring rules \`loam validate\` enforces, the ID spine, the cycle, and what every
+finding code means. It is generated by loam and kept in step with the binary.
+`;
+//# sourceMappingURL=readme.js.map

package/dist/core/scaffold/readme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.js","sourceRoot":"","sources":["../../../src/core/scaffold/readme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgExB,CAAC","sourcesContent":["/**\n * The README a new docs repo starts with — the one file in it addressed to a\n * person.\n *\n * Everything else the scaffold lays down is either a document about the\n * governed system or `AGENTS.md`, which is 1500 lines written for a coding\n * agent and named so that a human does not open it. A forge renders `README.md`\n * as the repository's landing page and nothing else, so without this file a\n * docs repo opens as a bare directory listing: four folders and two config\n * files, and no sentence anywhere saying what any of it is.\n *\n * Deliberately SHORT, and deliberately not a second copy of anything. The\n * layout table and the cycle are AGENTS.md's, in full; this page says what the\n * repo is, points at the three commands a person actually types, and hands off.\n * A README that restated the contract would be a second thing to keep true, and\n * the first one to go stale.\n */\nexport const README_FILENAME = \"README.md\";\n\nexport const README_MD = `# Architecture & specs\n\nThis repository is a governed system's **source of truth**: its architecture,\nrequirements, contracts, domain vocabulary and verification evidence, kept in\nexplicit agreement. It is plain files — Markdown, YAML and LikeC4 — reviewed like\ncode, in pull requests.\n\nIn paths and commands, loam calls one governed implementation boundary a\n**service**. That boundary may be a modular monolith, a network service, a CLI or\na worker. Nested C4 elements remain modules or components unless they need their\nown repository binding, contracts, evidence and deployment boundary.\n\nIt is read and written with [**loam**](https://github.com/ybotok/loam). Delete\nloam and these documents still make sense; that is the point of keeping them this\nway.\n\n## What is where\n\n| | |\n|---|---|\n| \\`architecture/landscape.likec4\\` | the system map — governed boundaries, nested structure and their relationships |\n| \\`services/<id>/\\` | one directory per governed boundary: what it promises, exposes and verifies |\n| \\`features/<FEAT>/\\` | a change in flight — why it exists, and the delta it makes to the documents above |\n| \\`features/archive/\\` | changes that shipped; their deltas are already merged into the living documents |\n\nA directory under \\`services/\\` that holds a \\`subsystem.yaml\\` is a **group**, not\na service — services can be filed inside one at any depth.\n\n## If you are new here\n\n\\`\\`\\`bash\nloam status\n\\`\\`\\`\n\nIt reads the files and tells you where things stand and what to do next, ordered\nmost-unblocking first, with the exact command for each step. Nothing in this\nrepository is generated from a database or a server — if \\`loam status\\` says\nsomething, a file said it first.\n\nTo check the whole repository the way CI does:\n\n\\`\\`\\`bash\nloam validate --all\n\\`\\`\\`\n\nAnd when a finding's code means nothing to you:\n\n\\`\\`\\`bash\nloam explain <code>\n\\`\\`\\`\n\n## Changing something\n\nDocuments here are edited through a **feature**: \\`loam new <FEAT>\\` scaffolds one,\nyou write the intent and the deltas, \\`loam validate --feature <FEAT>\\` grades it,\nand \\`loam archive <FEAT>\\` merges it into the living documents. Living documents\nare not edited directly once a boundary is adopted — the feature is the\nreviewable unit, and the archive is what makes the change traceable afterwards.\n\n## For coding agents\n\n\\`AGENTS.md\\` in this directory is the full contract: the layout in detail, the\nauthoring rules \\`loam validate\\` enforces, the ID spine, the cycle, and what every\nfinding code means. It is generated by loam and kept in step with the binary.\n`;\n"]}

package/dist/core/staging/commit.js

@@ -0,0 +1,241 @@
+/**
+ * The commit itself, in three steps: stage every new version beside its
+ * target, swap them in, roll back what already went in when a later step fails.
+ *
+ * This is what `archive` and `unarchive` share, and it moved out of archive.ts
+ * verbatim once unarchive became its second consumer. The MERGE computations
+ * stayed with archive, which is still their only caller — the split was about a
+ * second CONSUMER, never about archive being long.
+ *
+ * `StagingRaceError` belongs here rather than with the lock, though both are
+ * about a second writer: the lock is taken before a plan is computed, while
+ * this is the compare-and-set immediately before each rename — the second line
+ * of defence for exactly the window two racers who both broke the same stale
+ * lock would land in.
+ */
+import { existsSync } from "node:fs";
+import { link, mkdir, readFile, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { sameBytes, toBytes } from "./writes.js";
+/**
+ * The target changed between the pre-image staging read and the swap.
+ *
+ * The pre-image is what a rollback restores and what `unarchive` is handed, so
+ * swapping over somebody else's newer bytes would both lose their work and
+ * arm a rollback that writes a third version nobody wrote. Commands map this to
+ * `merge-failed`: nothing of theirs went in, the docs are as the other writer
+ * left them, and re-running can work.
+ */
+export class StagingRaceError extends Error {
+    path;
+    name = "StagingRaceError";
+    constructor(path) {
+        super(`${path} changed while this command was planning its merge — nothing was written; re-run`);
+        this.path = path;
+    }
+}
+/**
+ * Write every new version to a temp file beside its target, remembering what the
+ * target said first. Nothing observable changes here: on failure the temp files
+ * are removed and the docs are exactly as they were.
+ *
+ * The pre-image is read eagerly and deliberately: it is what a rollback restores
+ * and what `unarchive` is given, so a file we cannot read is a file we cannot
+ * safely rewrite, and the merge must stop before it starts.
+ */
+export async function stageWrites(writes) {
+    const staged = [];
+    try {
+        for (const [i, write] of writes.entries()) {
+            // mkdir(recursive) reports the topmost directory it had to create — the
+            // handle a rollback needs to put the tree back the way it found it.
+            const createdDir = (await mkdir(dirname(write.path), { recursive: true })) ?? null;
+            const before = existsSync(write.path) ? await readFile(write.path) : null;
+            const content = toBytes(write.content);
+            let tmp = null;
+            if (content !== null) {
+                tmp = tempPath(write.path, i);
+                await writeFile(tmp, content);
+            }
+            staged.push({ write, content, tmp, before, createdDir, swapped: false });
+        }
+    }
+    catch (err) {
+        await discardStaged(staged);
+        throw err;
+    }
+    return staged;
+}
+/**
+ * Swap the staged versions in, one file at a time. Each swap is a rename(2)
+ * within a single directory, so a concurrent reader sees either the old bytes or
+ * the new ones — never a half-written file. Across files it is not atomic: the
+ * caller rolls back what has already gone in.
+ *
+ * Every swap re-reads its target first and compares it with the pre-image the
+ * plan was computed from — a compare-and-set on the file's whole content. It is
+ * half a CAS on purpose: read and rename cannot be one syscall, so a writer
+ * landing inside that window still wins. What it does buy is the window that
+ * actually matters — the seconds a plan spends parsing LikeC4 and merging YAML
+ * between the pre-image read and this swap — and it costs one read per file.
+ */
+export async function swapStaged(staged) {
+    for (const s of staged) {
+        const now = existsSync(s.write.path) ? await readFile(s.write.path) : null;
+        if (!sameBytes(now, s.before))
+            throw new StagingRaceError(s.write.path);
+        if (s.tmp === null) {
+            if (s.before !== null)
+                await unlink(s.write.path);
+        }
+        else if (s.write.exclusive === true) {
+            // link(2) is the same-filesystem, atomic no-clobber counterpart to rename:
+            // it fails with EEXIST instead of replacing a file created after planning.
+            await link(s.tmp, s.write.path);
+            s.swapped = true;
+            await unlink(s.tmp);
+            s.tmp = null;
+            continue;
+        }
+        else {
+            await rename(s.tmp, s.write.path);
+        }
+        s.swapped = true;
+    }
+}
+/**
+ * Put back every file that was already swapped, newest first, from the bytes read
+ * before the swap. Returns the paths it could NOT restore — the caller must say so
+ * out loud rather than report a clean failure over a half-merged repo.
+ *
+ * A rollback only ever un-does ITS OWN write: if the file no longer holds the
+ * bytes this run put there, somebody else has written it since, and restoring
+ * the pre-image would destroy their work while reporting a clean failure. That
+ * file is left exactly as found and named in the failures, which is what turns
+ * the caller's answer from `merge-failed` ("trust the repo") into
+ * `rollback-incomplete` ("look at it by hand") — the honest answer, because the
+ * repo now holds one run's writes half-reverted next to another's.
+ */
+export async function rollbackStaged(staged) {
+    const failures = [];
+    for (const s of [...staged].reverse()) {
+        if (!s.swapped)
+            continue;
+        try {
+            const now = existsSync(s.write.path) ? await readFile(s.write.path) : null;
+            if (!sameBytes(now, s.content)) {
+                failures.push(`${s.write.path} (changed by another writer after this run wrote it — left as found)`);
+                continue;
+            }
+            if (s.before === null)
+                await rm(s.write.path, { force: true });
+            else
+                await atomicWrite(s.write.path, s.before);
+            s.swapped = false;
+        }
+        catch (err) {
+            failures.push(`${s.write.path} (${message(err)})`);
+        }
+    }
+    await discardStaged(staged);
+    return failures;
+}
+/** Write `content` to `path` through a temp file in the same directory. */
+export async function atomicWrite(path, content) {
+    const tmp = tempPath(path, 0);
+    await writeFile(tmp, content);
+    await rename(tmp, path);
+}
+/** A hidden sibling of `path`: same directory, so the rename never crosses a filesystem. */
+export function tempPath(path, n) {
+    return join(dirname(path), `.${basename(path)}.loam-${process.pid}-${n}-${Date.now()}.tmp`);
+}
+/** The shape `tempPath` writes — what a scan for leftovers of a killed run matches on. */
+export const TEMP_FILE_RE = /^\..*\.loam-\d+-\d+-\d+\.tmp$/;
+/**
+ * Everything staging left on disk: the temp files, and the directories it made
+ * for them.
+ *
+ * Directories go by rmdir, never by recursive remove, and the walk stops the
+ * moment one is not empty. The recursive form used to be reached for because
+ * "we created this directory, so it is ours" — but a directory created at plan
+ * time is shared by the time the rollback runs: a second archive can have put a
+ * whole feature inside `features/archive/` in between, and `rm -r` on our own
+ * created root took their work with it, silently, on OUR failure path.
+ */
+async function discardStaged(staged) {
+    for (const s of staged)
+        if (s.tmp !== null)
+            await quietRm(s.tmp);
+    const roots = staged.filter((s) => s.createdDir !== null).map((s) => resolve(s.createdDir));
+    for (const s of [...staged].reverse()) {
+        const root = roots.find((candidate) => contains(candidate, s.write.path));
+        if (root !== undefined)
+            await quietPruneEmptyParents(dirname(s.write.path), root);
+    }
+}
+function contains(parent, candidate) {
+    const rel = relative(parent, resolve(candidate));
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+/**
+ * Undo the directories a write had to create, from `start` up to and including
+ * `boundary`. Remove only directories that are still EMPTY: anything else in
+ * there arrived after we made it, and belongs to whoever put it there.
+ */
+/** Remove `dir` if it is empty. Best effort — a directory left standing is noise, not corruption. */
+export async function quietRmdir(dir) {
+    try {
+        await rmdir(dir);
+    }
+    catch {
+        // Not empty, or not ours.
+    }
+}
+export async function quietPruneEmptyParents(start, boundary) {
+    let cursor = resolve(start);
+    const root = resolve(boundary);
+    while (contains(root, cursor)) {
+        try {
+            await rmdir(cursor);
+        }
+        catch {
+            return;
+        }
+        if (cursor === root)
+            return;
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            return;
+        cursor = parent;
+    }
+}
+export async function quietRm(path) {
+    try {
+        await rm(path, { recursive: true, force: true });
+    }
+    catch {
+        // Best effort — a leftover temp file is noise, not corruption.
+    }
+}
+/**
+ * The one spelling of the sentence a rollback failure prints, parameterised
+ * only by the verb for what the files were mid-way through becoming. It
+ * existed in three near-copies (archive's "half-merged", vouch's
+ * "half-stamped", verify's "half-written") — the exact shape whose fix lands
+ * in one copy while an operator greps their logs for another.
+ */
+export function rollbackMessage(err, failures, what) {
+    return `${message(err)} — ROLLBACK INCOMPLETE, these files may be half-${what} and need checking by hand: ${failures.join(", ")}`;
+}
+/** Say what the failure cost: nothing, or a repo that needs looking at by hand. */
+export function rollbackError(err, failures) {
+    if (failures.length === 0) {
+        return new Error(`${message(err)} — the living docs were rolled back, nothing was merged`);
+    }
+    return new Error(rollbackMessage(err, failures, "merged"));
+}
+export function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=commit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/core/staging/commit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAuC,MAAM,aAAa,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGpB,IAAI;IAFP,IAAI,GAAG,kBAAkB,CAAC;IAE5C,YAAqB,IAAY;QAC/B,KAAK,CAAC,GAAG,IAAI,kFAAkF,CAAC,CAAC;oBAD9E,IAAI;IAEzB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAsB;IACtD,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1C,wEAAwE;YACxE,oEAAoE;YACpE,MAAM,UAAU,GAAG,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC;YACnF,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC1E,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACvC,IAAI,GAAG,GAAkB,IAAI,CAAC;YAC9B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC9B,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAqB;IACpD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3E,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxE,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;gBAAE,MAAM,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,CAAC;aAAM,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YACtC,2EAA2E;YAC3E,2EAA2E;YAC3E,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;YACjB,MAAM,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;YACb,SAAS;QACX,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;QACD,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAqB;IACxD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,OAAO;YAAE,SAAS;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3E,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,sEAAsE,CAAC,CAAC;gBACrG,SAAS;YACX,CAAC;YACD,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;gBAAE,MAAM,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;;gBAC1D,MAAM,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;YAC/C,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IACD,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,OAAe;IAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9B,MAAM,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,CAAS;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC9F,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,MAAM,YAAY,GAAG,+BAA+B,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,KAAK,UAAU,aAAa,CAAC,MAAqB;IAChD,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI;YAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,UAAW,CAAC,CAAC,CAAC;IAC7F,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc,EAAE,SAAiB;IACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACjD,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,qGAAqG;AACrG,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAa,EAAE,QAAgB;IAC1E,IAAI,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO;QAC9B,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,QAAkB,EAAE,IAAY;IAC5E,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mDAAmD,IAAI,+BAA+B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACpI,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,QAAkB;IAC5D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,IAAI,KAAK,CACd,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CACzC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAY;IAClC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * The commit itself, in three steps: stage every new version beside its\n * target, swap them in, roll back what already went in when a later step fails.\n *\n * This is what `archive` and `unarchive` share, and it moved out of archive.ts\n * verbatim once unarchive became its second consumer. The MERGE computations\n * stayed with archive, which is still their only caller — the split was about a\n * second CONSUMER, never about archive being long.\n *\n * `StagingRaceError` belongs here rather than with the lock, though both are\n * about a second writer: the lock is taken before a plan is computed, while\n * this is the compare-and-set immediately before each rename — the second line\n * of defence for exactly the window two racers who both broke the same stale\n * lock would land in.\n */\nimport { existsSync } from \"node:fs\";\nimport { link, mkdir, readFile, rename, rm, rmdir, unlink, writeFile } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, relative, resolve, sep } from \"node:path\";\nimport { sameBytes, toBytes, type PlannedWrite, type StagedWrite } from \"./writes.js\";\n\n/**\n * The target changed between the pre-image staging read and the swap.\n *\n * The pre-image is what a rollback restores and what `unarchive` is handed, so\n * swapping over somebody else's newer bytes would both lose their work and\n * arm a rollback that writes a third version nobody wrote. Commands map this to\n * `merge-failed`: nothing of theirs went in, the docs are as the other writer\n * left them, and re-running can work.\n */\nexport class StagingRaceError extends Error {\n  override readonly name = \"StagingRaceError\";\n\n  constructor(readonly path: string) {\n    super(`${path} changed while this command was planning its merge — nothing was written; re-run`);\n  }\n}\n\n/**\n * Write every new version to a temp file beside its target, remembering what the\n * target said first. Nothing observable changes here: on failure the temp files\n * are removed and the docs are exactly as they were.\n *\n * The pre-image is read eagerly and deliberately: it is what a rollback restores\n * and what `unarchive` is given, so a file we cannot read is a file we cannot\n * safely rewrite, and the merge must stop before it starts.\n */\nexport async function stageWrites(writes: PlannedWrite[]): Promise<StagedWrite[]> {\n  const staged: StagedWrite[] = [];\n  try {\n    for (const [i, write] of writes.entries()) {\n      // mkdir(recursive) reports the topmost directory it had to create — the\n      // handle a rollback needs to put the tree back the way it found it.\n      const createdDir = (await mkdir(dirname(write.path), { recursive: true })) ?? null;\n      const before = existsSync(write.path) ? await readFile(write.path) : null;\n      const content = toBytes(write.content);\n      let tmp: string | null = null;\n      if (content !== null) {\n        tmp = tempPath(write.path, i);\n        await writeFile(tmp, content);\n      }\n      staged.push({ write, content, tmp, before, createdDir, swapped: false });\n    }\n  } catch (err) {\n    await discardStaged(staged);\n    throw err;\n  }\n  return staged;\n}\n\n/**\n * Swap the staged versions in, one file at a time. Each swap is a rename(2)\n * within a single directory, so a concurrent reader sees either the old bytes or\n * the new ones — never a half-written file. Across files it is not atomic: the\n * caller rolls back what has already gone in.\n *\n * Every swap re-reads its target first and compares it with the pre-image the\n * plan was computed from — a compare-and-set on the file's whole content. It is\n * half a CAS on purpose: read and rename cannot be one syscall, so a writer\n * landing inside that window still wins. What it does buy is the window that\n * actually matters — the seconds a plan spends parsing LikeC4 and merging YAML\n * between the pre-image read and this swap — and it costs one read per file.\n */\nexport async function swapStaged(staged: StagedWrite[]): Promise<void> {\n  for (const s of staged) {\n    const now = existsSync(s.write.path) ? await readFile(s.write.path) : null;\n    if (!sameBytes(now, s.before)) throw new StagingRaceError(s.write.path);\n    if (s.tmp === null) {\n      if (s.before !== null) await unlink(s.write.path);\n    } else if (s.write.exclusive === true) {\n      // link(2) is the same-filesystem, atomic no-clobber counterpart to rename:\n      // it fails with EEXIST instead of replacing a file created after planning.\n      await link(s.tmp, s.write.path);\n      s.swapped = true;\n      await unlink(s.tmp);\n      s.tmp = null;\n      continue;\n    } else {\n      await rename(s.tmp, s.write.path);\n    }\n    s.swapped = true;\n  }\n}\n\n/**\n * Put back every file that was already swapped, newest first, from the bytes read\n * before the swap. Returns the paths it could NOT restore — the caller must say so\n * out loud rather than report a clean failure over a half-merged repo.\n *\n * A rollback only ever un-does ITS OWN write: if the file no longer holds the\n * bytes this run put there, somebody else has written it since, and restoring\n * the pre-image would destroy their work while reporting a clean failure. That\n * file is left exactly as found and named in the failures, which is what turns\n * the caller's answer from `merge-failed` (\"trust the repo\") into\n * `rollback-incomplete` (\"look at it by hand\") — the honest answer, because the\n * repo now holds one run's writes half-reverted next to another's.\n */\nexport async function rollbackStaged(staged: StagedWrite[]): Promise<string[]> {\n  const failures: string[] = [];\n  for (const s of [...staged].reverse()) {\n    if (!s.swapped) continue;\n    try {\n      const now = existsSync(s.write.path) ? await readFile(s.write.path) : null;\n      if (!sameBytes(now, s.content)) {\n        failures.push(`${s.write.path} (changed by another writer after this run wrote it — left as found)`);\n        continue;\n      }\n      if (s.before === null) await rm(s.write.path, { force: true });\n      else await atomicWrite(s.write.path, s.before);\n      s.swapped = false;\n    } catch (err) {\n      failures.push(`${s.write.path} (${message(err)})`);\n    }\n  }\n  await discardStaged(staged);\n  return failures;\n}\n\n/** Write `content` to `path` through a temp file in the same directory. */\nexport async function atomicWrite(path: string, content: Buffer): Promise<void> {\n  const tmp = tempPath(path, 0);\n  await writeFile(tmp, content);\n  await rename(tmp, path);\n}\n\n/** A hidden sibling of `path`: same directory, so the rename never crosses a filesystem. */\nexport function tempPath(path: string, n: number): string {\n  return join(dirname(path), `.${basename(path)}.loam-${process.pid}-${n}-${Date.now()}.tmp`);\n}\n\n/** The shape `tempPath` writes — what a scan for leftovers of a killed run matches on. */\nexport const TEMP_FILE_RE = /^\\..*\\.loam-\\d+-\\d+-\\d+\\.tmp$/;\n\n/**\n * Everything staging left on disk: the temp files, and the directories it made\n * for them.\n *\n * Directories go by rmdir, never by recursive remove, and the walk stops the\n * moment one is not empty. The recursive form used to be reached for because\n * \"we created this directory, so it is ours\" — but a directory created at plan\n * time is shared by the time the rollback runs: a second archive can have put a\n * whole feature inside `features/archive/` in between, and `rm -r` on our own\n * created root took their work with it, silently, on OUR failure path.\n */\nasync function discardStaged(staged: StagedWrite[]): Promise<void> {\n  for (const s of staged) if (s.tmp !== null) await quietRm(s.tmp);\n  const roots = staged.filter((s) => s.createdDir !== null).map((s) => resolve(s.createdDir!));\n  for (const s of [...staged].reverse()) {\n    const root = roots.find((candidate) => contains(candidate, s.write.path));\n    if (root !== undefined) await quietPruneEmptyParents(dirname(s.write.path), root);\n  }\n}\n\nfunction contains(parent: string, candidate: string): boolean {\n  const rel = relative(parent, resolve(candidate));\n  return rel === \"\" || (!rel.startsWith(`..${sep}`) && rel !== \"..\" && !isAbsolute(rel));\n}\n\n/**\n * Undo the directories a write had to create, from `start` up to and including\n * `boundary`. Remove only directories that are still EMPTY: anything else in\n * there arrived after we made it, and belongs to whoever put it there.\n */\n/** Remove `dir` if it is empty. Best effort — a directory left standing is noise, not corruption. */\nexport async function quietRmdir(dir: string): Promise<void> {\n  try {\n    await rmdir(dir);\n  } catch {\n    // Not empty, or not ours.\n  }\n}\n\nexport async function quietPruneEmptyParents(start: string, boundary: string): Promise<void> {\n  let cursor = resolve(start);\n  const root = resolve(boundary);\n  while (contains(root, cursor)) {\n    try {\n      await rmdir(cursor);\n    } catch {\n      return;\n    }\n    if (cursor === root) return;\n    const parent = dirname(cursor);\n    if (parent === cursor) return;\n    cursor = parent;\n  }\n}\n\nexport async function quietRm(path: string): Promise<void> {\n  try {\n    await rm(path, { recursive: true, force: true });\n  } catch {\n    // Best effort — a leftover temp file is noise, not corruption.\n  }\n}\n\n/**\n * The one spelling of the sentence a rollback failure prints, parameterised\n * only by the verb for what the files were mid-way through becoming. It\n * existed in three near-copies (archive's \"half-merged\", vouch's\n * \"half-stamped\", verify's \"half-written\") — the exact shape whose fix lands\n * in one copy while an operator greps their logs for another.\n */\nexport function rollbackMessage(err: unknown, failures: string[], what: string): string {\n  return `${message(err)} — ROLLBACK INCOMPLETE, these files may be half-${what} and need checking by hand: ${failures.join(\", \")}`;\n}\n\n/** Say what the failure cost: nothing, or a repo that needs looking at by hand. */\nexport function rollbackError(err: unknown, failures: string[]): Error {\n  if (failures.length === 0) {\n    return new Error(`${message(err)} — the living docs were rolled back, nothing was merged`);\n  }\n  return new Error(\n    rollbackMessage(err, failures, \"merged\"),\n  );\n}\n\nexport function message(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n\n"]}

package/dist/core/staging/interrupted.js

@@ -0,0 +1,96 @@
+/**
+ * The vocabulary every journaled commit shares, whichever journal version
+ * wrote it: the record's filename, the refusal an interrupted commit raises,
+ * the recovery report a caller prints, and the two disk disciplines (durable
+ * write, pid-scoped temp sweep) that recovery rests on.
+ *
+ * A staging-ROOT module, deliberately: `recovery/` (the version-1 undo path)
+ * and `txn/` (the version-2 roll-forward path) both need these VALUES, and a
+ * value import between those two packages in either direction would be the
+ * repo's first package cycle — `recovery/` already imports the staging root,
+ * and `txn/` must too. Shared values live where both edges already point.
+ */
+import { readdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { quietRm, TEMP_FILE_RE } from "./commit.js";
+/**
+ * The journal that makes an interrupted commit detectable.
+ *
+ * `swapStaged` is N renames, and only each ONE of them is atomic. A kill
+ * between two of them leaves the tree half-merged — and nothing could see it:
+ * `doctor` and `status` called the repo healthy, `validate --all` blamed the
+ * delta, and the next archive cleared the one snapshot that could have
+ * repaired it. So every commit's swap loop runs inside a record written and
+ * fsynced BEFORE the first rename and removed after the last step: its mere
+ * presence says a commit was in flight, and its per-path digests say, file by
+ * file, whether that file's rename landed.
+ *
+ * It is deliberately NOT a source of truth and never disagrees with the
+ * files: every judgement it supports is made by re-reading the bytes and
+ * comparing digests, and every byte a repair writes is verified against the
+ * digest recorded before the crash. Outside the commit window it does not
+ * exist — except after a rollback that could not finish, where it is kept on
+ * purpose as the one durable record of which files need a human. Version 1
+ * (archive/unarchive) restores from a snapshot; version 2 (the smaller
+ * transaction) rolls forward from the staged temps. Both wear this name so
+ * one `doctor` scan finds either.
+ */
+export const COMMIT_INTENT = ".loam-commit";
+/** An interrupted commit this loam must not silently write over. */
+export class InterruptedCommitError extends Error {
+    name = "InterruptedCommitError";
+}
+/**
+ * Write `text` to `path` and get it onto the DISK, not just into the page
+ * cache: a journal that dies with the machine describes nothing. The
+ * directory entry is fsynced too where the platform allows opening a
+ * directory — without that the file's bytes can be durable while its name is
+ * not.
+ */
+export async function writeDurable(path, text) {
+    const handle = await open(path, "w");
+    try {
+        await handle.writeFile(text, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        const dir = await open(join(path, ".."), "r");
+        try {
+            await dir.sync();
+        }
+        finally {
+            await dir.close();
+        }
+    }
+    catch {
+        // Not every platform lets a directory be opened; the file's own bytes are
+        // flushed either way, which is the part that carries the digests.
+    }
+}
+/**
+ * Drop the staged temp files a killed run could not remove — scoped to that
+ * run's own pid and its own target directories, both carried in the temp
+ * name, so a leftover belonging to anything else is left for `doctor` to
+ * name. Without this a repair that put every byte back still left the repo
+ * dirty, which is the one thing a caller checks to decide whether it worked.
+ */
+export async function sweepPidTemps(dirs, pid) {
+    for (const dir of new Set(dirs)) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!TEMP_FILE_RE.test(name) || !name.includes(`.loam-${pid}-`))
+                continue;
+            await quietRm(join(dir, name));
+        }
+    }
+}
+//# sourceMappingURL=interrupted.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interrupted.js","sourceRoot":"","sources":["../../../src/core/staging/interrupted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,CAAC;AAE5C,oEAAoE;AACpE,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC7B,IAAI,GAAG,wBAAwB,CAAC;CACnD;AAsBD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY;IAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACrC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,kEAAkE;IACpE,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAsB,EAAE,GAAW;IACrE,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,GAAG,CAAC;gBAAE,SAAS;YAC1E,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["/**\n * The vocabulary every journaled commit shares, whichever journal version\n * wrote it: the record's filename, the refusal an interrupted commit raises,\n * the recovery report a caller prints, and the two disk disciplines (durable\n * write, pid-scoped temp sweep) that recovery rests on.\n *\n * A staging-ROOT module, deliberately: `recovery/` (the version-1 undo path)\n * and `txn/` (the version-2 roll-forward path) both need these VALUES, and a\n * value import between those two packages in either direction would be the\n * repo's first package cycle — `recovery/` already imports the staging root,\n * and `txn/` must too. Shared values live where both edges already point.\n */\nimport { readdir, open } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { quietRm, TEMP_FILE_RE } from \"./commit.js\";\n\n/**\n * The journal that makes an interrupted commit detectable.\n *\n * `swapStaged` is N renames, and only each ONE of them is atomic. A kill\n * between two of them leaves the tree half-merged — and nothing could see it:\n * `doctor` and `status` called the repo healthy, `validate --all` blamed the\n * delta, and the next archive cleared the one snapshot that could have\n * repaired it. So every commit's swap loop runs inside a record written and\n * fsynced BEFORE the first rename and removed after the last step: its mere\n * presence says a commit was in flight, and its per-path digests say, file by\n * file, whether that file's rename landed.\n *\n * It is deliberately NOT a source of truth and never disagrees with the\n * files: every judgement it supports is made by re-reading the bytes and\n * comparing digests, and every byte a repair writes is verified against the\n * digest recorded before the crash. Outside the commit window it does not\n * exist — except after a rollback that could not finish, where it is kept on\n * purpose as the one durable record of which files need a human. Version 1\n * (archive/unarchive) restores from a snapshot; version 2 (the smaller\n * transaction) rolls forward from the staged temps. Both wear this name so\n * one `doctor` scan finds either.\n */\nexport const COMMIT_INTENT = \".loam-commit\";\n\n/** An interrupted commit this loam must not silently write over. */\nexport class InterruptedCommitError extends Error {\n  override readonly name = \"InterruptedCommitError\";\n}\n\n/** What recovery did, for the caller to print and put in `--json`. */\nexport interface CommitRecovery {\n  /** Which command's commit was recovered — a sentence a human reads, not a branch. */\n  command: string;\n  /**\n   * What that command was committing FOR: a feature id for archive, unarchive\n   * and rebase; a service for vouch and gherkin. The field keeps archive's\n   * original name because its `--json` shape shipped first.\n   */\n  feature: string;\n  /**\n   * `completed` — every step but the record's own removal landed;\n   * `consistent` — no file was left in the other state;\n   * `repaired` — files were put back (v1) or carried forward (v2), byte for byte.\n   */\n  outcome: \"completed\" | \"consistent\" | \"repaired\";\n  /** Repo-relative paths this recovery rewrote or removed. */\n  repaired: string[];\n}\n\n/**\n * Write `text` to `path` and get it onto the DISK, not just into the page\n * cache: a journal that dies with the machine describes nothing. The\n * directory entry is fsynced too where the platform allows opening a\n * directory — without that the file's bytes can be durable while its name is\n * not.\n */\nexport async function writeDurable(path: string, text: string): Promise<void> {\n  const handle = await open(path, \"w\");\n  try {\n    await handle.writeFile(text, \"utf8\");\n    await handle.sync();\n  } finally {\n    await handle.close();\n  }\n  try {\n    const dir = await open(join(path, \"..\"), \"r\");\n    try {\n      await dir.sync();\n    } finally {\n      await dir.close();\n    }\n  } catch {\n    // Not every platform lets a directory be opened; the file's own bytes are\n    // flushed either way, which is the part that carries the digests.\n  }\n}\n\n/**\n * Drop the staged temp files a killed run could not remove — scoped to that\n * run's own pid and its own target directories, both carried in the temp\n * name, so a leftover belonging to anything else is left for `doctor` to\n * name. Without this a repair that put every byte back still left the repo\n * dirty, which is the one thing a caller checks to decide whether it worked.\n */\nexport async function sweepPidTemps(dirs: Iterable<string>, pid: number): Promise<void> {\n  for (const dir of new Set(dirs)) {\n    let entries: string[];\n    try {\n      entries = await readdir(dir);\n    } catch {\n      continue;\n    }\n    for (const name of entries) {\n      if (!TEMP_FILE_RE.test(name) || !name.includes(`.loam-${pid}-`)) continue;\n      await quietRm(join(dir, name));\n    }\n  }\n}\n"]}