@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

@@ -0,0 +1,188 @@
+/**
+ * Where the undo snapshot lives and what its manifest says — the half of
+ * `./snapshot.ts` a command can know without being able to take a snapshot.
+ *
+ * Split from that module when the snapshot became a package of its own: taking
+ * a snapshot (and refusing to clobber one) is a commit, and the MCP server's
+ * read-only claim is DERIVED from the import graph — a served command whose
+ * imports reach `./snapshot.ts` is, by that test, a command that can commit.
+ * The layout below is pure naming and shape, and the readers that only need
+ * to find a snapshot, or read what one recorded, import it from here.
+ */
+import { isUtf8 } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolvePortableFileInsideLexically } from "../../kernel/path-safety.js";
+import { isRecord } from "../../kernel/records.js";
+import { sha256 } from "../writes.js";
+/** Where archive parks the pre-images, inside the feature directory so they travel with it — `./snapshot.ts`'s module doc says why. */
+export const SNAPSHOT_DIR = ".loam-before";
+export const SNAPSHOT_MANIFEST = "manifest.json";
+/**
+ * Bumped only when the layout changes in a way `unarchive` must refuse to guess
+ * at. 2 added `before`: a version-1 snapshot says nothing about the bytes it
+ * would RESTORE, so an edited pre-image read back as an intact one. 3 re-keys
+ * `services/` entries by `(service, artifact)`: a literal path pins the service
+ * directory where it stood on the day of the archive, and once the subsystem
+ * tree lets it move — re-cutting is expected to be routine — an undo addressed
+ * by path restores into a location that is gone. The service id never moves.
+ * 4 stores each pre-image under its own name PLUS {@link PRE_IMAGE_SUFFIX}: a
+ * pre-image kept under its living name is a second copy of a living document
+ * that every tool reading by extension takes for one. The snapshot of a
+ * landscape is a `.likec4` inside the archived feature, so a feature with its
+ * own `likec4.config.json` — or rendered alone, `likec4 start
+ * features/archive/<FEAT>`, as the brief recommends — loaded the map twice
+ * beside the delta and failed on duplicate elements, and a fleet project that
+ * did not exclude `features/` failed the same way.
+ */
+export const SNAPSHOT_VERSION = 4;
+/**
+ * Version 2 is still READ, forever: version-2 snapshots already sit inside
+ * archived features, which carry them across loam upgrades, and each must keep
+ * restoring — and keep being graded for staleness by a retried archive — under
+ * its own literal-path rules. Only version 1 is refused (no restore digests).
+ */
+export const SNAPSHOT_COMPAT_VERSION = 2;
+/**
+ * Version 3 is read forever for the same reason, under its own rules: rows
+ * keyed by `(service, artifact)` like version 4's, pre-images stored under
+ * their living names. A version-3 snapshot keeps its layout — it is restored
+ * from where it was written, never migrated, because rewriting a snapshot is
+ * rewriting the only copy of what the living docs once said.
+ */
+const SNAPSHOT_KEYED_VERSION = 3;
+/** Appended to every pre-image a version-4 snapshot stores; see {@link SNAPSHOT_VERSION}. */
+export const PRE_IMAGE_SUFFIX = ".before";
+/** A manifest version this loam reads: the one it writes and the two it reads forever. */
+export function isReadableSnapshotVersion(version) {
+    return version === SNAPSHOT_COMPAT_VERSION || version === SNAPSHOT_KEYED_VERSION || version === 4;
+}
+/** Does a manifest of this version key its `services/` rows by `(service, artifact)`? Version 3 on. */
+export function keysServiceRows(version) {
+    return version >= SNAPSHOT_KEYED_VERSION;
+}
+/**
+ * Where a row's pre-image sits inside `files/`, forward slashes, under the
+ * layout the manifest's VERSION names — never the layout this loam would
+ * write, since a snapshot is read where it was written. Suffixed from version
+ * 4 on.
+ */
+export function preImageRel(version, path) {
+    return version >= 4 ? `${path}${PRE_IMAGE_SUFFIX}` : path;
+}
+export function snapshotDir(featureDir) {
+    return join(featureDir, SNAPSHOT_DIR);
+}
+/**
+ * The checklist digest an archived feature's snapshot captured as it merged,
+ * or null when it carries none.
+ *
+ * It lives in the manifest because the manifest is the one file `archive`
+ * already writes into the feature at the moment of the merge, travels with it
+ * into `features/archive/`, and is taken away by `unarchive` — so a feature
+ * archived again gets a fresh one, captured against what it then asked. A
+ * frozen verification record cannot be judged against a checklist re-derived
+ * after the merge (the merge moved the feature's operations into the living
+ * contract, so the derivation can only mismatch); this is the question as it
+ * stood when the feature shipped, which is what `loam gate --since` holds the
+ * record to. Here rather than beside the writer for the reason this module
+ * exists: the gate is a read-only command, served over MCP as one.
+ *
+ * Tolerant to the last byte, and every failure is "none captured": a manifest
+ * an older loam wrote, a feature archived with no record, a manifest that is
+ * missing or does not parse. The reader that grades on it reads null as the
+ * frozen history it always read, and says so — it never refuses a deploy
+ * question over bookkeeping.
+ */
+export async function readSnapshotChecklist(featureDir) {
+    const manifest = await manifestRecord(featureDir);
+    if (manifest === null)
+        return null;
+    const { checklist } = manifest;
+    return typeof checklist === "string" && checklist !== "" ? checklist : null;
+}
+/**
+ * The bytes one service artifact held the moment this feature merged — the
+ * pre-image the snapshot parked under `files/` — or one of the two answers
+ * that say the merge took nothing out of it ({@link SnapshotPreImage}), or
+ * null when there is nothing to trust.
+ *
+ * Read for the questions only the pre-image can answer, both asked by the
+ * retired-operation revival check (core/coherence/retired/): what a merge TOOK
+ * that its delta never spelled — a channel-slot removal in an asyncapi delta is
+ * a bare marker, while the messages it retired with the channel are written in
+ * the living contract it merged into and nowhere else — and whether a removal
+ * marker took anything at all, since the merge deletes only what it finds at
+ * the marker's slot. Here, beside `readSnapshotChecklist`, for that reader's
+ * reason: the readers are read-only commands, and this module is the half of
+ * the snapshot they may import.
+ *
+ * The entry is found by `(service, artifact)` on a keyed (version 3 or 4) manifest — the
+ * key that survives a subsystem re-cut — and by the literal path's last two
+ * segments on a version-2 one, which recorded nothing else. Tolerant to the
+ * last byte, like the checklist reader: no manifest, a layout this loam would
+ * have to guess at, no row for the artifact while some row cannot be read (it
+ * might have been this one's, so absence cannot be concluded past it), a path
+ * that does not stay inside `files/`, a pre-image that no longer hashes to the digest
+ * the manifest recorded for it, or bytes that are not UTF-8 — every one is
+ * null, and the caller grades without it. An edited pre-image is refused
+ * rather than read for the reason `unarchive` refuses to restore one: its
+ * bytes are no longer what the merge saw.
+ */
+export async function readSnapshotPreImage(featureDir, key) {
+    const manifest = await manifestRecord(featureDir);
+    if (manifest === null || !Array.isArray(manifest.files))
+        return null;
+    const { version } = manifest;
+    if (!isReadableSnapshotVersion(version))
+        return null;
+    // `Array.isArray` narrows to `any[]`; naming the element type keeps that
+    // `any` from spreading past the row being read (snapshot.ts's reason).
+    const rows = manifest.files;
+    const entry = rows.find((row) => isRecord(row) && entryIs(row, key));
+    if (entry === undefined) {
+        // Absence is an answer only when every row could be read: a row that is
+        // not a record with a path might have been this artifact's.
+        return rows.every((row) => isRecord(row) && typeof row.path === "string") ? { kind: "unwritten" } : null;
+    }
+    if (!isRecord(entry) || typeof entry.path !== "string")
+        return null;
+    if (entry.existed === false && entry.before === null)
+        return { kind: "created" };
+    if (typeof entry.before !== "string")
+        return null;
+    let bytes;
+    try {
+        // The manifest is data and this path is one we go and read: the lexical
+        // containment `unarchive` and the staleness check apply to the same field.
+        bytes = await readFile(resolvePortableFileInsideLexically(join(snapshotDir(featureDir), "files"), preImageRel(version, entry.path), "snapshot pre-image"));
+    }
+    catch {
+        return null;
+    }
+    if (sha256(bytes) !== entry.before || !isUtf8(bytes))
+        return null;
+    return { kind: "held", text: bytes.toString("utf8") };
+}
+/** Does this manifest row record `key`'s artifact? The `(service, artifact)` key when it has one, the literal path otherwise. */
+function entryIs(row, key) {
+    if (typeof row.service === "string" && typeof row.artifact === "string") {
+        return row.service === key.service && row.artifact === key.artifact;
+    }
+    if (typeof row.path !== "string")
+        return false;
+    const parts = row.path.split("/");
+    return parts.length >= 3 && parts[0] === "services" && parts.at(-2) === key.service && parts.at(-1) === key.artifact;
+}
+/** The manifest as a record, or null — the one tolerant read behind both readers above. */
+async function manifestRecord(featureDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(snapshotDir(featureDir), SNAPSHOT_MANIFEST), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    return isRecord(manifest) ? manifest : null;
+}
+//# sourceMappingURL=manifest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../../src/core/staging/snapshot/manifest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where the undo snapshot lives and what its manifest says — the half of\n * `./snapshot.ts` a command can know without being able to take a snapshot.\n *\n * Split from that module when the snapshot became a package of its own: taking\n * a snapshot (and refusing to clobber one) is a commit, and the MCP server's\n * read-only claim is DERIVED from the import graph — a served command whose\n * imports reach `./snapshot.ts` is, by that test, a command that can commit.\n * The layout below is pure naming and shape, and the readers that only need\n * to find a snapshot, or read what one recorded, import it from here.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { resolvePortableFileInsideLexically } from \"../../kernel/path-safety.js\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { sha256 } from \"../writes.js\";\n\n/** Where archive parks the pre-images, inside the feature directory so they travel with it — `./snapshot.ts`'s module doc says why. */\nexport const SNAPSHOT_DIR = \".loam-before\";\nexport const SNAPSHOT_MANIFEST = \"manifest.json\";\n/**\n * Bumped only when the layout changes in a way `unarchive` must refuse to guess\n * at. 2 added `before`: a version-1 snapshot says nothing about the bytes it\n * would RESTORE, so an edited pre-image read back as an intact one. 3 re-keys\n * `services/` entries by `(service, artifact)`: a literal path pins the service\n * directory where it stood on the day of the archive, and once the subsystem\n * tree lets it move — re-cutting is expected to be routine — an undo addressed\n * by path restores into a location that is gone. The service id never moves.\n * 4 stores each pre-image under its own name PLUS {@link PRE_IMAGE_SUFFIX}: a\n * pre-image kept under its living name is a second copy of a living document\n * that every tool reading by extension takes for one. The snapshot of a\n * landscape is a `.likec4` inside the archived feature, so a feature with its\n * own `likec4.config.json` — or rendered alone, `likec4 start\n * features/archive/<FEAT>`, as the brief recommends — loaded the map twice\n * beside the delta and failed on duplicate elements, and a fleet project that\n * did not exclude `features/` failed the same way.\n */\nexport const SNAPSHOT_VERSION = 4;\n/**\n * Version 2 is still READ, forever: version-2 snapshots already sit inside\n * archived features, which carry them across loam upgrades, and each must keep\n * restoring — and keep being graded for staleness by a retried archive — under\n * its own literal-path rules. Only version 1 is refused (no restore digests).\n */\nexport const SNAPSHOT_COMPAT_VERSION = 2;\n/**\n * Version 3 is read forever for the same reason, under its own rules: rows\n * keyed by `(service, artifact)` like version 4's, pre-images stored under\n * their living names. A version-3 snapshot keeps its layout — it is restored\n * from where it was written, never migrated, because rewriting a snapshot is\n * rewriting the only copy of what the living docs once said.\n */\nconst SNAPSHOT_KEYED_VERSION = 3;\n/** Appended to every pre-image a version-4 snapshot stores; see {@link SNAPSHOT_VERSION}. */\nexport const PRE_IMAGE_SUFFIX = \".before\";\n\n/**\n * The layouts this loam reads, by LITERAL — never \"the version this loam\n * writes\". Each rule below names the version that introduced it, so the next\n * bump cannot quietly re-read an older layout under the new one's rules: the\n * key rule was spelled `version === SNAPSHOT_VERSION` until this bump, and\n * would have stopped keying every version-3 row the day the constant moved. A\n * version added to the writer and not to this union is a compile error at the\n * writer's own call to {@link preImageRel}.\n */\nexport type ReadableSnapshotVersion = typeof SNAPSHOT_COMPAT_VERSION | typeof SNAPSHOT_KEYED_VERSION | 4;\n\n/** A manifest version this loam reads: the one it writes and the two it reads forever. */\nexport function isReadableSnapshotVersion(version: unknown): version is ReadableSnapshotVersion {\n  return version === SNAPSHOT_COMPAT_VERSION || version === SNAPSHOT_KEYED_VERSION || version === 4;\n}\n\n/** Does a manifest of this version key its `services/` rows by `(service, artifact)`? Version 3 on. */\nexport function keysServiceRows(version: ReadableSnapshotVersion): boolean {\n  return version >= SNAPSHOT_KEYED_VERSION;\n}\n\n/**\n * Where a row's pre-image sits inside `files/`, forward slashes, under the\n * layout the manifest's VERSION names — never the layout this loam would\n * write, since a snapshot is read where it was written. Suffixed from version\n * 4 on.\n */\nexport function preImageRel(version: ReadableSnapshotVersion, path: string): string {\n  return version >= 4 ? `${path}${PRE_IMAGE_SUFFIX}` : path;\n}\n\nexport interface SnapshotEntry {\n  /**\n   * Docs-repo-relative path, forward slashes, AS ARCHIVED — where the archive\n   * left the bytes. Load-bearing even beside the key below: it names the\n   * pre-image under `.loam-before/files/` (through {@link preImageRel}), and\n   * it is the literal fallback when the id stops being enumerated.\n   *\n   * For the feature's OWN documents — the ones the archive relinks for the\n   * move (`commands/archive/plan/document/links.ts`) — that is inside\n   * `features/archive/<FEAT>/`, not where they were written: the rename\n   * carried them there, and that is where `unarchive` finds and restores them\n   * before it moves the directory back. Recorded that way, every reader of\n   * this layout restores them by its literal-path rule with nothing new to\n   * learn, which is why the rows needed no version of their own; the two\n   * readers that meet a snapshot before its feature moved — the clobber guard\n   * and the crash repair — look across the move for them.\n   */\n  path: string;\n  /**\n   * For a `services/` entry: the service id (the leaf directory name — the one\n   * thing a re-cut never changes) and the artifact's path inside its directory,\n   * resolved through the CURRENT enumeration at restore time. Absent on\n   * landscape and `features/` entries: the landscape does not move, and a\n   * feature's own documents move only with the feature, which `path` already\n   * says.\n   */\n  service?: string;\n  artifact?: string;\n  /** False when archive CREATED the file: restoring it means deleting it again. */\n  existed: boolean;\n  /** sha256 of what archive wrote, so unarchive can tell its own merge from later edits. */\n  after: string;\n  /**\n   * sha256 of the pre-image beside this manifest — the bytes `unarchive` will\n   * RESTORE. Null when archive created the file (there is no pre-image).\n   * `after` only describes what archive wrote; while nothing described the\n   * restore source, a pre-image edited in the archived feature directory — a\n   * bad merge, a rebase, a stray editor — was written back verbatim and every\n   * loam surface certified the result.\n   */\n  before: string | null;\n}\n\nexport interface SnapshotManifest {\n  version: number;\n  feature: string;\n  dirName: string;\n  archivedAt: string;\n  /**\n   * The digest of the checklist a fresh `loam verify` derived for the feature\n   * just before this merge — present when the feature carried a record then,\n   * absent otherwise and in every manifest an older loam wrote. Additive, so\n   * the layout version does not move: `unarchive` never reads it, and a reader\n   * that predates it ignores it. See {@link readSnapshotChecklist}.\n   */\n  checklist?: string;\n  files: SnapshotEntry[];\n}\n\nexport function snapshotDir(featureDir: string): string {\n  return join(featureDir, SNAPSHOT_DIR);\n}\n\n/**\n * The checklist digest an archived feature's snapshot captured as it merged,\n * or null when it carries none.\n *\n * It lives in the manifest because the manifest is the one file `archive`\n * already writes into the feature at the moment of the merge, travels with it\n * into `features/archive/`, and is taken away by `unarchive` — so a feature\n * archived again gets a fresh one, captured against what it then asked. A\n * frozen verification record cannot be judged against a checklist re-derived\n * after the merge (the merge moved the feature's operations into the living\n * contract, so the derivation can only mismatch); this is the question as it\n * stood when the feature shipped, which is what `loam gate --since` holds the\n * record to. Here rather than beside the writer for the reason this module\n * exists: the gate is a read-only command, served over MCP as one.\n *\n * Tolerant to the last byte, and every failure is \"none captured\": a manifest\n * an older loam wrote, a feature archived with no record, a manifest that is\n * missing or does not parse. The reader that grades on it reads null as the\n * frozen history it always read, and says so — it never refuses a deploy\n * question over bookkeeping.\n */\nexport async function readSnapshotChecklist(featureDir: string): Promise<string | null> {\n  const manifest = await manifestRecord(featureDir);\n  if (manifest === null) return null;\n  const { checklist } = manifest;\n  return typeof checklist === \"string\" && checklist !== \"\" ? checklist : null;\n}\n\n/**\n * What a snapshot says about one service artifact as this feature's merge found\n * it. `held` is the pre-image itself. The other two are answers too, and the\n * same one for the question the reader asks — what did the merge take OUT of\n * the artifact: nothing. `created` is a row archive wrote for a file it\n * created (there was nothing before it); `unwritten` is an intact manifest\n * with no row for the artifact at all — archive records every file it writes,\n * so the artifact is what the merge found. Only the EVENT merge leaves a\n * contract unwritten: it returns no text when it changes nothing\n * (asyncapi/merge/merge.ts, `text: null` — a delta whose every marker missed\n * its target is exactly that). The OpenAPI merge returns text whenever the\n * delta has a path entry, so its no-op is an ordinary row whose pre-image\n * equals what it wrote — `held`, which answers the same question the same\n * way: every marker misses against it again.\n */\nexport type SnapshotPreImage =\n  | { kind: \"held\"; text: string }\n  | { kind: \"created\" }\n  | { kind: \"unwritten\" };\n\n/**\n * The bytes one service artifact held the moment this feature merged — the\n * pre-image the snapshot parked under `files/` — or one of the two answers\n * that say the merge took nothing out of it ({@link SnapshotPreImage}), or\n * null when there is nothing to trust.\n *\n * Read for the questions only the pre-image can answer, both asked by the\n * retired-operation revival check (core/coherence/retired/): what a merge TOOK\n * that its delta never spelled — a channel-slot removal in an asyncapi delta is\n * a bare marker, while the messages it retired with the channel are written in\n * the living contract it merged into and nowhere else — and whether a removal\n * marker took anything at all, since the merge deletes only what it finds at\n * the marker's slot. Here, beside `readSnapshotChecklist`, for that reader's\n * reason: the readers are read-only commands, and this module is the half of\n * the snapshot they may import.\n *\n * The entry is found by `(service, artifact)` on a keyed (version 3 or 4) manifest — the\n * key that survives a subsystem re-cut — and by the literal path's last two\n * segments on a version-2 one, which recorded nothing else. Tolerant to the\n * last byte, like the checklist reader: no manifest, a layout this loam would\n * have to guess at, no row for the artifact while some row cannot be read (it\n * might have been this one's, so absence cannot be concluded past it), a path\n * that does not stay inside `files/`, a pre-image that no longer hashes to the digest\n * the manifest recorded for it, or bytes that are not UTF-8 — every one is\n * null, and the caller grades without it. An edited pre-image is refused\n * rather than read for the reason `unarchive` refuses to restore one: its\n * bytes are no longer what the merge saw.\n */\nexport async function readSnapshotPreImage(\n  featureDir: string,\n  key: { service: string; artifact: string },\n): Promise<SnapshotPreImage | null> {\n  const manifest = await manifestRecord(featureDir);\n  if (manifest === null || !Array.isArray(manifest.files)) return null;\n  const { version } = manifest;\n  if (!isReadableSnapshotVersion(version)) return null;\n  // `Array.isArray` narrows to `any[]`; naming the element type keeps that\n  // `any` from spreading past the row being read (snapshot.ts's reason).\n  const rows: unknown[] = manifest.files;\n  const entry = rows.find((row) => isRecord(row) && entryIs(row, key));\n  if (entry === undefined) {\n    // Absence is an answer only when every row could be read: a row that is\n    // not a record with a path might have been this artifact's.\n    return rows.every((row) => isRecord(row) && typeof row.path === \"string\") ? { kind: \"unwritten\" } : null;\n  }\n  if (!isRecord(entry) || typeof entry.path !== \"string\") return null;\n  if (entry.existed === false && entry.before === null) return { kind: \"created\" };\n  if (typeof entry.before !== \"string\") return null;\n  let bytes: Buffer;\n  try {\n    // The manifest is data and this path is one we go and read: the lexical\n    // containment `unarchive` and the staleness check apply to the same field.\n    bytes = await readFile(\n      resolvePortableFileInsideLexically(\n        join(snapshotDir(featureDir), \"files\"),\n        preImageRel(version, entry.path),\n        \"snapshot pre-image\",\n      ),\n    );\n  } catch {\n    return null;\n  }\n  if (sha256(bytes) !== entry.before || !isUtf8(bytes)) return null;\n  return { kind: \"held\", text: bytes.toString(\"utf8\") };\n}\n\n/** Does this manifest row record `key`'s artifact? The `(service, artifact)` key when it has one, the literal path otherwise. */\nfunction entryIs(row: Record<string, unknown>, key: { service: string; artifact: string }): boolean {\n  if (typeof row.service === \"string\" && typeof row.artifact === \"string\") {\n    return row.service === key.service && row.artifact === key.artifact;\n  }\n  if (typeof row.path !== \"string\") return false;\n  const parts = row.path.split(\"/\");\n  return parts.length >= 3 && parts[0] === \"services\" && parts.at(-2) === key.service && parts.at(-1) === key.artifact;\n}\n\n/** The manifest as a record, or null — the one tolerant read behind both readers above. */\nasync function manifestRecord(featureDir: string): Promise<Record<string, unknown> | null> {\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(await readFile(join(snapshotDir(featureDir), SNAPSHOT_MANIFEST), \"utf8\"));\n  } catch {\n    return null;\n  }\n  return isRecord(manifest) ? manifest : null;\n}\n"]}

package/dist/core/staging/{snapshot.js → snapshot/snapshot.js}

@@ -11,37 +11,15 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { repoPath } from "../envelope/json.js";
-import { resolvePortableFileInsideLexically, UnsafePathError } from "../kernel/path-safety.js";
-// Every `isRecord` below guards a record loam itself wrote and is reading back
-// — the lock, the snapshot manifest — whose fields are asked for on the very
-// next line, inside a REFUSAL path. `JSON.parse` answers with any JSON value,
-// not with an object, and that is where a thrown `TypeError` costs the most: it
-// does not make the command fail safely, it replaces a designed refusal with
-// `internal`.
-import { isRecord } from "../kernel/records.js";
-import { isDigest, sha256 } from "./writes.js";
-import { message, quietRm } from "./commit.js";
-/** Where archive parks the pre-images, inside the feature directory so they travel with it — the module doc above says why. */
-export const SNAPSHOT_DIR = ".loam-before";
-export const SNAPSHOT_MANIFEST = "manifest.json";
-/**
- * Bumped only when the layout changes in a way `unarchive` must refuse to guess
- * at. 2 added `before`: a version-1 snapshot says nothing about the bytes it
- * would RESTORE, so an edited pre-image read back as an intact one. 3 re-keys
- * `services/` entries by `(service, artifact)`: a literal path pins the service
- * directory where it stood on the day of the archive, and once the subsystem
- * tree lets it move — re-cutting is expected to be routine — an undo addressed
- * by path restores into a location that is gone. The service id never moves.
- */
-export const SNAPSHOT_VERSION = 3;
-/**
- * Version 2 is still READ, forever: version-2 snapshots already sit inside
- * archived features, which carry them across loam upgrades, and each must keep
- * restoring — and keep being graded for staleness by a retried archive — under
- * its own literal-path rules. Only version 1 is refused (no restore digests).
- */
-export const SNAPSHOT_COMPAT_VERSION = 2;
+import { repoPath } from "../../envelope/json.js";
+import { acrossRename, resolvePortableFileInsideLexically, UnsafePathError } from "../../kernel/path-safety.js";
+// Every `isRecord` below guards the manifest loam itself wrote, read back inside
+// a REFUSAL path — `../lock.ts` records why that is where a thrown `TypeError`
+// costs the most.
+import { isRecord } from "../../kernel/records.js";
+import { isDigest, sha256 } from "../writes.js";
+import { message, quietRm } from "../commit.js";
+import { isReadableSnapshotVersion, preImageRel, SNAPSHOT_DIR, SNAPSHOT_MANIFEST, SNAPSHOT_VERSION, snapshotDir, } from "./manifest.js";
 /** A snapshot directory that must not be replaced, because it is the only copy of the true pre-images. */
 export class SnapshotClobberError extends Error {
     dir;
@@ -54,19 +32,18 @@ export class SnapshotClobberError extends Error {
         this.dir = dir;
     }
 }
-export function snapshotDir(featureDir) {
-    return join(featureDir, SNAPSHOT_DIR);
-}
 export async function writeSnapshot(request) {
     const { featureDir, docsDir, staged } = request;
     const { featureId, dirName } = request.feature;
     const dir = snapshotDir(featureDir);
-    await assertSnapshotReplaceable(dir, docsDir, request.serviceDirOf);
+    await assertSnapshotReplaceable(request);
     // A leftover from a rolled-back run would describe a merge that never happened.
     await quietRm(dir);
     const files = [];
     for (const s of staged) {
-        const rel = repoPath(docsDir, s.write.path);
+        // The feature's own documents by where the move leaves them; everything
+        // else by where it is written (`SnapshotRequest.movesTo` says why).
+        const rel = repoPath(docsDir, acrossRename(s.write.path, featureDir, request.movesTo));
         // services/ entries are re-keyed by (service, artifact) so they survive the
         // service directory moving between archive and unarchive; the literal path
         // is still recorded — it keys the pre-image below, and it is the fallback.
@@ -79,7 +56,10 @@ export async function writeSnapshot(request) {
             before: s.before === null ? null : sha256(s.before),
         });
         if (s.before !== null) {
-            const dest = join(dir, "files", rel);
+            // Under the suffixed name (`./manifest.ts`, version 4): a pre-image kept
+            // under its living name is a second living document to every tool that
+            // reads by extension.
+            const dest = join(dir, "files", preImageRel(SNAPSHOT_VERSION, rel));
             await mkdir(dirname(dest), { recursive: true });
             await writeFile(dest, s.before);
         }
@@ -89,6 +69,7 @@ export async function writeSnapshot(request) {
         feature: featureId,
         dirName,
         archivedAt: new Date().toISOString(),
+        ...(request.checklist === undefined ? {} : { checklist: request.checklist }),
         files,
     };
     // Manifest last: its presence is what says the pre-images beside it are complete.
@@ -108,11 +89,16 @@ export async function writeSnapshot(request) {
  * clear turned a repairable half-merge into a permanent one — after which
  * `unarchive` restored the half-merged text and said the docs were back.
  *
- * Version 2 manifests are graded by the same staleness question over their
- * literal paths — refusing them as "a different loam" would turn every leftover
- * version-2 snapshot into a permanent archive refusal on upgrade.
+ * Version 2 and 3 manifests are graded by the same staleness question — version
+ * 2 over its literal paths — because refusing them as "a different loam" would
+ * turn every leftover snapshot an older loam wrote into a permanent archive
+ * refusal on upgrade. The question reads only the manifest and the living docs,
+ * never a pre-image, so where each layout stores its pre-images does not enter
+ * into it.
  */
-async function assertSnapshotReplaceable(dir, docsDir, serviceDirOf) {
+async function assertSnapshotReplaceable(request) {
+    const { docsDir, serviceDirOf } = request;
+    const dir = snapshotDir(request.featureDir);
     const manifestPath = join(dir, SNAPSHOT_MANIFEST);
     // The manifest is written LAST, so a `files/` tree without one is a snapshot
     // whose run died before it could swap anything: it describes no merge.
@@ -134,8 +120,7 @@ async function assertSnapshotReplaceable(dir, docsDir, serviceDirOf) {
     if (!isRecord(manifest)) {
         throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);
     }
-    if ((manifest.version !== SNAPSHOT_VERSION && manifest.version !== SNAPSHOT_COMPAT_VERSION) ||
-        !Array.isArray(manifest.files)) {
+    if (!isReadableSnapshotVersion(manifest.version) || !Array.isArray(manifest.files)) {
         throw new SnapshotClobberError(dir, `it was written by a different loam and cannot be checked against the living docs`);
     }
     // `Array.isArray` narrows to `any[]`; naming the element type here is what
@@ -172,12 +157,21 @@ async function assertSnapshotReplaceable(dir, docsDir, serviceDirOf) {
                 throw err;
             throw new SnapshotClobberError(dir, `${message(err)}, so nothing can say whether it is stale`);
         }
-        const now = existsSync(target) ? sha256(await readFile(target)) : null;
+        // A row of the feature's own documents names where the move WOULD have
+        // left it, and a snapshot found here is one whose feature never moved: the
+        // bytes to grade are still under this feature directory. Graded at the
+        // literal path instead, every such row read as absent — a landed merge —
+        // and an archive that a crash or a rollback interrupted could never be
+        // retried over its own leftover. Named where it was graded, too: the
+        // refusal sends a person to restore the file from version control, and
+        // the archived path names a directory that does not exist yet.
+        const graded = acrossRename(target, request.movesTo, request.featureDir);
+        const now = existsSync(graded) ? sha256(await readFile(graded)) : null;
         // `existed: false` means archive created the file, so "nothing landed"
         // means it is still absent.
         const untouched = entry.existed ? now === entry.before : now === null;
         if (!untouched)
-            landed.push(entry.path);
+            landed.push(graded === target ? entry.path : repoPath(docsDir, graded));
     }
     if (landed.length > 0)
         throw new SnapshotClobberError(dir, `${landed.length} file(s) already carry that merge: ${landed.join(", ")}`);

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../../../src/core/staging/snapshot/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,kCAAkC,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAChH,iFAAiF;AACjF,+EAA+E;AAC/E,kBAAkB;AAClB,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAoB,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,yBAAyB,EACzB,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,GAGZ,MAAM,eAAe,CAAC;AAEvB,0GAA0G;AAC1G,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAGxB,GAAG;IAFN,IAAI,GAAG,sBAAsB,CAAC;IAEhD,YAAqB,GAAW,EAAE,MAAc;QAC9C,KAAK,CACH,GAAG,GAAG,wEAAwE,MAAM,4BAA4B;YAC9G,6GAA6G;YAC7G,6GAA6G;YAC7G,mEAAmE,YAAY,uCAAuC,CACzH,CAAC;mBANiB,GAAG;IAOxB,CAAC;CACF;AA2CD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAwB;IAC1D,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAChD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAC/C,MAAM,GAAG,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACpC,MAAM,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACzC,gFAAgF;IAChF,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnB,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,wEAAwE;QACxE,oEAAoE;QACpE,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QACvF,4EAA4E;QAC5E,2EAA2E;QAC3E,2EAA2E;QAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,GAAG;YACT,GAAG,GAAG;YACN,OAAO,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI;YAC1B,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC3C,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;SACpD,CAAC,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACtB,yEAAyE;YACzE,uEAAuE;YACvE,sBAAsB;YACtB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC;YACpE,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAqB;QACjC,OAAO,EAAE,gBAAgB;QACzB,OAAO,EAAE,SAAS;QAClB,OAAO;QACP,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;QAC5E,KAAK;KACN,CAAC;IACF,kFAAkF;IAClF,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAClG,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,KAAK,UAAU,yBAAyB,CAAC,OAAwB;IAC/D,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAC1C,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAClD,6EAA6E;IAC7E,uEAAuE;IACvE,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO;IACtC,IAAI,QAAiB,CAAC;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,iBAAiB,yDAAyD,CAAC,CAAC;IACrH,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,8EAA8E;IAC9E,yEAAyE;IACzE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,iBAAiB,yDAAyD,CAAC,CAAC;IACrH,CAAC;IACD,IAAI,CAAC,yBAAyB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,kFAAkF,CAAC,CAAC;IAC1H,CAAC;IACD,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,IAAI,GAAc,QAAQ,CAAC,KAAK,CAAC;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,iBAAiB,uDAAuD,CAAC,CAAC;QACnH,CAAC;QACD,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,qEAAqE;YACrE,uEAAuE;YACvE,yEAAyE;YACzE,0EAA0E;YAC1E,MAAM,GAAG,kCAAkC,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,kBAAkB,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;YAClG,uEAAuE;YACvE,uEAAuE;YACvE,sEAAsE;YACtE,yEAAyE;YACzE,oEAAoE;YACpE,iEAAiE;YACjE,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChE,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC5C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;oBACrB,MAAM,GAAG,kCAAkC,CACzC,OAAO,EACP,GAAG,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,EAC9B,kBAAkB,KAAK,CAAC,IAAI,GAAG,CAChC,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,eAAe,CAAC;gBAAE,MAAM,GAAG,CAAC;YACjD,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACjG,CAAC;QACD,uEAAuE;QACvE,2EAA2E;QAC3E,uEAAuE;QACvE,yEAAyE;QACzE,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,+DAA+D;QAC/D,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;QACzE,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACvE,uEAAuE;QACvE,4BAA4B;QAC5B,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC;QACtE,IAAI,CAAC,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,sCAAsC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxI,CAAC;AA8BD,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC3D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,GAAkE,CAAC;IACvE,IAAI,OAAO,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS;QAAE,GAAG,GAAG,EAAE,CAAC;SACzD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,GAAG,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;;QAC7F,OAAO,IAAI,CAAC;IACjB,IAAI,OAAO;QAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChF,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACpE,CAAC","sourcesContent":["/**\n * The undo snapshot: the bytes `archive` is about to overwrite, parked inside\n * the feature directory so they travel with it into `features/archive/`.\n *\n * Separate from the commit because the merge is not invertible — a MODIFIED\n * requirement's previous text appears nowhere in the delta, and a landscape\n * rewritten by hand since cannot be un-rewritten by re-reading one. `unarchive`\n * puts bytes back; it does not recompute them. Nothing on the commit path reads\n * this module: only `archive` writes a snapshot and only `unarchive` honours one.\n */\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { acrossRename, resolvePortableFileInsideLexically, UnsafePathError } from \"../../kernel/path-safety.js\";\n// Every `isRecord` below guards the manifest loam itself wrote, read back inside\n// a REFUSAL path — `../lock.ts` records why that is where a thrown `TypeError`\n// costs the most.\nimport { isRecord } from \"../../kernel/records.js\";\nimport { isDigest, sha256, type StagedWrite } from \"../writes.js\";\nimport { message, quietRm } from \"../commit.js\";\nimport {\n  isReadableSnapshotVersion,\n  preImageRel,\n  SNAPSHOT_DIR,\n  SNAPSHOT_MANIFEST,\n  SNAPSHOT_VERSION,\n  snapshotDir,\n  type SnapshotEntry,\n  type SnapshotManifest,\n} from \"./manifest.js\";\n\n/** A snapshot directory that must not be replaced, because it is the only copy of the true pre-images. */\nexport class SnapshotClobberError extends Error {\n  override readonly name = \"SnapshotClobberError\";\n\n  constructor(readonly dir: string, detail: string) {\n    super(\n      `${dir} already holds an undo snapshot that does NOT match the living docs (${detail}) — a previous archive of ` +\n        `this feature wrote to the living docs and never took them back, and these are the only copies of what they ` +\n        `said before. Overwriting them would make that merge permanent and unreportable. Run \\`loam archive\\` again ` +\n        `after restoring the living docs from version control, or delete ${SNAPSHOT_DIR}/ if you know the merge never landed.`,\n    );\n  }\n}\n\n/** The (service, artifact) key a `services/` path decomposes into. */\nexport interface ServiceKey {\n  service: string;\n  artifact: string;\n}\n\n/**\n * Everything `writeSnapshot` needs, as one object. The resolvers are INJECTED\n * by the caller — `archive` builds them from its view of the tree — because\n * how a path decomposes into a service identity is repo-layout knowledge, and\n * this module's subject is parking and checking bytes.\n */\nexport interface SnapshotRequest {\n  featureDir: string;\n  /**\n   * Where the archive moves `featureDir` — the directory this snapshot is\n   * about to travel into. A staged write INSIDE `featureDir` is one of the\n   * feature's own documents (the archive re-expresses their links for the\n   * move), and it is recorded at its image under here: that is where its bytes\n   * sit whenever an undo can be asked for, so `unarchive` restores it by its\n   * literal path before moving the directory back, exactly as it restores\n   * every other row. The other reader, the clobber guard below, meets a\n   * snapshot BEFORE its feature moved and grades such a row at its image back\n   * under `featureDir`.\n   */\n  movesTo: string;\n  docsDir: string;\n  feature: { featureId: string; dirName: string };\n  staged: StagedWrite[];\n  /** Docs-relative path → the service it belongs to; null for landscape/features paths. */\n  serviceKeyOf: (rel: string) => ServiceKey | null;\n  /** Service id → its CURRENT docs-relative directory; null when not enumerated. */\n  serviceDirOf: (service: string) => string | null;\n  /**\n   * Recorded verbatim as the manifest's `checklist` when given. Opaque here —\n   * this module parks bytes and never learns what a checklist is; `archive`\n   * derives it and `gate --since` reads it back (`./manifest.ts`).\n   */\n  checklist?: string;\n}\n\nexport async function writeSnapshot(request: SnapshotRequest): Promise<void> {\n  const { featureDir, docsDir, staged } = request;\n  const { featureId, dirName } = request.feature;\n  const dir = snapshotDir(featureDir);\n  await assertSnapshotReplaceable(request);\n  // A leftover from a rolled-back run would describe a merge that never happened.\n  await quietRm(dir);\n\n  const files: SnapshotEntry[] = [];\n  for (const s of staged) {\n    // The feature's own documents by where the move leaves them; everything\n    // else by where it is written (`SnapshotRequest.movesTo` says why).\n    const rel = repoPath(docsDir, acrossRename(s.write.path, featureDir, request.movesTo));\n    // services/ entries are re-keyed by (service, artifact) so they survive the\n    // service directory moving between archive and unarchive; the literal path\n    // is still recorded — it keys the pre-image below, and it is the fallback.\n    const key = request.serviceKeyOf(rel);\n    files.push({\n      path: rel,\n      ...key,\n      existed: s.before !== null,\n      after: sha256(s.content ?? Buffer.alloc(0)),\n      before: s.before === null ? null : sha256(s.before),\n    });\n    if (s.before !== null) {\n      // Under the suffixed name (`./manifest.ts`, version 4): a pre-image kept\n      // under its living name is a second living document to every tool that\n      // reads by extension.\n      const dest = join(dir, \"files\", preImageRel(SNAPSHOT_VERSION, rel));\n      await mkdir(dirname(dest), { recursive: true });\n      await writeFile(dest, s.before);\n    }\n  }\n\n  const manifest: SnapshotManifest = {\n    version: SNAPSHOT_VERSION,\n    feature: featureId,\n    dirName,\n    archivedAt: new Date().toISOString(),\n    ...(request.checklist === undefined ? {} : { checklist: request.checklist }),\n    files,\n  };\n  // Manifest last: its presence is what says the pre-images beside it are complete.\n  await mkdir(dir, { recursive: true });\n  await writeFile(join(dir, SNAPSHOT_MANIFEST), JSON.stringify(manifest, null, 2) + \"\\n\", \"utf8\");\n}\n\n/**\n * Refuse to replace a snapshot whose pre-images are still the only record of\n * what the living docs said.\n *\n * A snapshot in an ACTIVE feature directory means a previous archive of this\n * same feature wrote it — and since a clean rollback deletes it, finding one\n * means that run either died mid-commit or reported `rollback-incomplete`. If\n * its pre-images still match the living docs, nothing of that run landed and\n * the snapshot is stale bookkeeping. If they do not, the living docs carry\n * that run's writes, these files are the only way back, and the unconditional\n * clear turned a repairable half-merge into a permanent one — after which\n * `unarchive` restored the half-merged text and said the docs were back.\n *\n * Version 2 and 3 manifests are graded by the same staleness question — version\n * 2 over its literal paths — because refusing them as \"a different loam\" would\n * turn every leftover snapshot an older loam wrote into a permanent archive\n * refusal on upgrade. The question reads only the manifest and the living docs,\n * never a pre-image, so where each layout stores its pre-images does not enter\n * into it.\n */\nasync function assertSnapshotReplaceable(request: SnapshotRequest): Promise<void> {\n  const { docsDir, serviceDirOf } = request;\n  const dir = snapshotDir(request.featureDir);\n  const manifestPath = join(dir, SNAPSHOT_MANIFEST);\n  // The manifest is written LAST, so a `files/` tree without one is a snapshot\n  // whose run died before it could swap anything: it describes no merge.\n  if (!existsSync(manifestPath)) return;\n  let manifest: unknown;\n  try {\n    manifest = JSON.parse(await readFile(manifestPath, \"utf8\"));\n  } catch {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  // The cast that used to stand here asserted the shape rather than checking\n  // it: well-formed JSON that is not an object answered `undefined` to every\n  // field below and slipped through as \"a different loam\", and a bare `null`\n  // threw a TypeError out of the refusal itself. Both left this directory —\n  // which may hold the only copies of what the living docs said — one step from\n  // being replaced, without the staleness question ever having been asked.\n  if (!isRecord(manifest)) {\n    throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} cannot be read, so nothing can say whether it is stale`);\n  }\n  if (!isReadableSnapshotVersion(manifest.version) || !Array.isArray(manifest.files)) {\n    throw new SnapshotClobberError(dir, `it was written by a different loam and cannot be checked against the living docs`);\n  }\n  // `Array.isArray` narrows to `any[]`; naming the element type here is what\n  // keeps that `any` from spreading past the one row being read.\n  const rows: unknown[] = manifest.files;\n  const landed: string[] = [];\n  for (const row of rows) {\n    const entry = readSnapshotClaim(row);\n    if (entry === null) {\n      throw new SnapshotClobberError(dir, `${SNAPSHOT_MANIFEST} is malformed, so nothing can say whether it is stale`);\n    }\n    let target: string;\n    try {\n      // These paths are data, and they are the ones this function goes and\n      // reads. They name living documents, so containment is lexical: a docs\n      // repo may legitimately mount a service directory through a symlink, and\n      // `unarchive` resolves the same field the same way before it writes back.\n      target = resolvePortableFileInsideLexically(docsDir, entry.path, `snapshot path '${entry.path}'`);\n      // A re-keyed entry's CURRENT location is wherever the enumeration says\n      // its service lives today — grading staleness at the old address would\n      // call a merely-moved file a landed merge. The literal path was still\n      // resolved above on purpose: its containment is part of what \"loam wrote\n      // this manifest\" means, and it stays the pre-image's key. An id the\n      // enumeration no longer answers falls back to that literal path.\n      if (entry.service !== undefined && entry.artifact !== undefined) {\n        const current = serviceDirOf(entry.service);\n        if (current !== null) {\n          target = resolvePortableFileInsideLexically(\n            docsDir,\n            `${current}/${entry.artifact}`,\n            `snapshot path '${entry.path}'`,\n          );\n        }\n      }\n    } catch (err) {\n      if (!(err instanceof UnsafePathError)) throw err;\n      throw new SnapshotClobberError(dir, `${message(err)}, so nothing can say whether it is stale`);\n    }\n    // A row of the feature's own documents names where the move WOULD have\n    // left it, and a snapshot found here is one whose feature never moved: the\n    // bytes to grade are still under this feature directory. Graded at the\n    // literal path instead, every such row read as absent — a landed merge —\n    // and an archive that a crash or a rollback interrupted could never be\n    // retried over its own leftover. Named where it was graded, too: the\n    // refusal sends a person to restore the file from version control, and\n    // the archived path names a directory that does not exist yet.\n    const graded = acrossRename(target, request.movesTo, request.featureDir);\n    const now = existsSync(graded) ? sha256(await readFile(graded)) : null;\n    // `existed: false` means archive created the file, so \"nothing landed\"\n    // means it is still absent.\n    const untouched = entry.existed ? now === entry.before : now === null;\n    if (!untouched) landed.push(graded === target ? entry.path : repoPath(docsDir, graded));\n  }\n  if (landed.length > 0) throw new SnapshotClobberError(dir, `${landed.length} file(s) already carry that merge: ${landed.join(\", \")}`);\n}\n\n/**\n * One manifest row read back as the record `writeSnapshot` wrote, or null when\n * the file does not actually say.\n *\n * Every field the staleness question consumes is checked, because an unchecked\n * field does not read as missing here — it reads as an ANSWER. An `existed`\n * that is not a boolean is falsy, and a `false` claim is graded by asking\n * whether the file is ABSENT: a manifest recording a pre-image for a deleted\n * file therefore graded as stale bookkeeping and was cleared, taking the only\n * copy of that pre-image with it. A `before` of the wrong type equals no digest\n * at all, so the opposite row accused an untouched file of carrying a merge.\n *\n * `unarchive` asks a stricter version of the same question of the same file\n * (`after`, `archivedAt`, the feature name, no duplicates) because it is about\n * to write THROUGH it; that check stays where it is, with its own refusals.\n *\n * `service`/`artifact` are read when present (a keyed `services/` row) and\n * must arrive as a pair: half a key is a manifest that does not say where the\n * file lives, and grading through the literal path anyway would be a guess.\n */\ninterface SnapshotClaim {\n  path: string;\n  existed: boolean;\n  before: string | null;\n  service?: string;\n  artifact?: string;\n}\n\nfunction readSnapshotClaim(value: unknown): SnapshotClaim | null {\n  if (!isRecord(value)) return null;\n  const { path, existed, before, service, artifact } = value;\n  if (typeof path !== \"string\" || typeof existed !== \"boolean\") return null;\n  let key: { service: string; artifact: string } | Record<string, never>;\n  if (service === undefined && artifact === undefined) key = {};\n  else if (typeof service === \"string\" && typeof artifact === \"string\") key = { service, artifact };\n  else return null;\n  if (existed) return isDigest(before) ? { path, existed, before, ...key } : null;\n  return before === null ? { path, existed, before, ...key } : null;\n}\n\n"]}

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

@@ -23,21 +23,7 @@ import { sha256 } from "../writes.js";
 import { COMMIT_INTENT, InterruptedCommitError, sweepPidTemps } from "../interrupted.js";
 import { clearTxnIntent } from "./journal.js";
 export async function recoverForward(root, intent) {
-    const target = (f) => join(root, ...f.path.split("/"));
     const abs = (rel) => join(root, ...rel.split("/"));
-    const done = [];
-    const pending = [];
-    const unknown = [];
-    for (const f of intent.files) {
-        const file = target(f);
-        const now = existsSync(file) ? sha256(await readFile(file)) : null;
-        if (now === f.after)
-            done.push(f);
-        else if (now === f.before)
-            pending.push(f);
-        else
-            unknown.push(f.path);
-    }
     // A directory rename is classified by pure existence — a rename moves the
     // inode, so "which end exists" is exactly as discriminating as a digest is
     // for a file. Both ends existing (or neither) is a state no step of the
@@ -56,6 +42,30 @@ export async function recoverForward(root, intent) {
         else
             unknownMoves.push(`${m.from} -> ${m.to}`);
     }
+    // Where a recorded file IS now. The journal records a file at the path its
+    // swap wrote — and a `subsystem move` swaps the documents whose links it
+    // rewrites INSIDE a directory it then renames, so once that rename has
+    // landed the file is under the moved directory, not at the recorded path.
+    // Looked for there, it would read as absent: "edited since", a refusal over
+    // a commit that only needed its journal cleared. Classified moves first for
+    // exactly this; a file under a move still pending is where it was recorded.
+    const target = (f) => {
+        const landed = movesDone.find((m) => f.path.startsWith(`${m.from}/`));
+        return landed === undefined ? abs(f.path) : abs(`${landed.to}${f.path.slice(landed.from.length)}`);
+    };
+    const done = [];
+    const pending = [];
+    const unknown = [];
+    for (const f of intent.files) {
+        const file = target(f);
+        const now = existsSync(file) ? sha256(await readFile(file)) : null;
+        if (now === f.after)
+            done.push(f);
+        else if (now === f.before)
+            pending.push(f);
+        else
+            unknown.push(f.path);
+    }
     if (unknown.length > 0 || unknownMoves.length > 0) {
         // Two vocabularies on purpose: a FILE in neither recorded state holds
         // edited bytes, while a DIRECTORY rename in neither state means both ends

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"writes.js","sourceRoot":"","sources":["../../../src/core/staging/writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA8B5C,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,OAA+B;IACrD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAA+B;IACrE,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAsBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAI1B,IAAI;IAHG,IAAI,GAAG,cAAc,CAAC;IAExC,YACW,IAAY,EACrB,MAAc;QAEd,KAAK,CAAC,GAAG,IAAI,IAAI,MAAM,yDAAyD,CAAC,CAAC;oBAHzE,IAAI;IAIf,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,UAAU,CAAC,KAAa,EAAE,IAAY;IAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,mGAAmG;YACjG,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,2GAA2G;YACzG,iGAAiG;YACjG,yGAAyG;YACzG,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,SAAS,CAAC,CAAgB,EAAE,CAAgB;IAC1D,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,OAAO,OAAO,KAAK,QAAQ;QAChC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC5D,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC","sourcesContent":["/**\n * What a write IS before anything touches disk: the planned record, the staged\n * record, and the bytes both are made of.\n *\n * This is the package's floor. Everything else here — the lock, the swap, the\n * snapshot, the recovery journal — is a rule about WHEN bytes may land; only\n * this module decides what they are. Decoding lives here for the same reason:\n * text is produced only where a parser needs it and `readUtf8` is the one door,\n * so no later addition can reach a docs file through `readFile(…, \"utf8\")` and\n * silently substitute U+FFFD for bytes loam did not understand.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\n\n/**\n * A planned file write — the merge is computed fully before anything touches\n * disk. `content: null` means \"delete this file\"; only `unarchive` plans those,\n * to take back a file the archive created.\n *\n * BYTES, not text. The whole write path — pre-image, staged content, snapshot,\n * the compare-and-set before each swap — moves Buffers, because a docs repo is\n * not guaranteed to hold text loam can decode: `Buffer.toString(\"utf8\")` never\n * fails, it substitutes U+FFFD, so reading a file as a string and writing the\n * string back is a silent, permanent rewrite of every byte loam did not\n * understand. It reached the snapshot too, so `unarchive` restored the damage\n * and reported success. Text is now produced only where a PARSER needs it, by\n * `decodeUtf8`, which refuses instead of substituting.\n */\nexport interface PlannedWrite {\n  path: string;\n  /**\n   * A `string` is accepted for the callers whose new version IS text they\n   * composed from nothing (a re-pinned delta, a restamped spec) and is encoded\n   * as UTF-8 once, at staging. A caller holding BYTES — anything derived from a\n   * file loam read — must hand over the Buffer: the round trip through a string\n   * is the corruption above.\n   */\n  content: string | Buffer | null;\n  /** Create the target atomically without replacing a concurrently created file. */\n  exclusive?: boolean;\n}\n\n/** The one place a planned write becomes bytes. */\nexport function toBytes(content: string | Buffer | null): Buffer | null {\n  return typeof content === \"string\" ? Buffer.from(content, \"utf8\") : content;\n}\n\n/**\n * The one place that decides whether a planned write is a CREATE *from the\n * filesystem*. (`core/verify/store/commit.ts` is the deliberate second rule:\n * it decides from the caller's held pre-image instead, because a CAS must\n * follow the read it promised, not what `existsSync` says now.)\n *\n * `exclusive` is a no-clobber create (link(2)), so it can only be asked of a\n * path that does not exist yet: asking it of an overwrite would fail EEXIST on\n * every single run. Deciding here — rather than at each of the dozen\n * `writes.push` sites in archive and unarchive — is what keeps the two commands\n * from disagreeing about which of their writes may safely lose a race. An\n * OVERWRITE is not left unguarded: `swapStaged` compares the target against the\n * pre-image immediately before the rename, so a file another writer changed\n * under us stops the commit instead of silently burying their bytes.\n */\nexport function planWrite(path: string, content: string | Buffer | null): PlannedWrite {\n  if (content !== null && !existsSync(path)) return { path, content, exclusive: true };\n  return { path, content };\n}\n\n/** A planned write with its new bytes parked next to the target, ready to swap in. */\nexport interface StagedWrite {\n  write: PlannedWrite;\n  /** What this write puts on disk — `write.content` encoded once. Null for a delete. */\n  content: Buffer | null;\n  /** Temp file holding the new bytes, in the target's OWN directory. Null for a delete. */\n  tmp: string | null;\n  /** The target's bytes before the swap; null when it did not exist. */\n  before: Buffer | null;\n  /**\n   * Topmost directory this write had to create, if any — a rollback owes the repo\n   * its directories back too. An empty `services/<svc>/` left standing is the\n   * fleet claiming a service that was never merged.\n   */\n  createdDir: string | null;\n  swapped: boolean;\n}\n\n\n\n/**\n * A file loam must PARSE that does not decode as the UTF-8 text loam owns.\n *\n * Commands map this to `merge-failed`: nothing was written, the file is named,\n * and re-saving it as UTF-8 makes the command work. The read-only migration\n * ingest already refuses non-UTF-8 input outright (core/openspec/) —\n * the destructive path has strictly more to lose, so it refuses the same way\n * rather than substituting U+FFFD and rewriting the file over the author.\n *\n * `reason` says what the bytes actually ARE, because the two ways a document\n * fails this test destroy different things: one substitutes bytes, the other\n * erases the whole document's meaning. A reader told the wrong one goes looking\n * in the wrong place. The advice that follows is the same either way, so it is\n * spelled once, here.\n */\nexport class NotUtf8Error extends Error {\n  override readonly name = \"NotUtf8Error\";\n\n  constructor(\n    readonly path: string,\n    reason: string,\n  ) {\n    super(`${path} ${reason} Nothing was written. Re-save it as UTF-8, then re-run.`);\n  }\n}\n\n/**\n * Decode bytes a parser is about to be handed, or refuse naming the file.\n *\n * Two tests, the same two the read path makes (document-bytes.ts's\n * `decodeDocument`), because this side has strictly more to lose by missing\n * either. `isUtf8` catches the byte sequences that cannot be UTF-8 at all —\n * which is what a byte-order mark makes UTF-16 into. Without a BOM, UTF-16LE of\n * ASCII is a sequence of perfectly VALID UTF-8 bytes: every other byte is NUL,\n * so `isUtf8` says yes, the file decodes with a U+0000 between every character,\n * and every parser loam owns reads its requirements, frontmatter and headings\n * as absent rather than as unreadable. On the read path that is a document\n * graded green while nothing in it was checked; here it is worse, because\n * `archive` merges against that empty baseline and writes the result back — the\n * author's requirements are not mis-read, they are gone, and the undo snapshot\n * records the same emptiness as the pre-image.\n */\nfunction decodeUtf8(bytes: Buffer, path: string): string {\n  if (!isUtf8(bytes)) {\n    throw new NotUtf8Error(\n      path,\n      `is not valid UTF-8 — loam parses this file as text and writes it back, which would replace every ` +\n        `undecodable byte with U+FFFD, in the living document AND in the undo snapshot.`,\n    );\n  }\n  const text = bytes.toString(\"utf8\");\n  if (text.includes(\"\\u0000\")) {\n    throw new NotUtf8Error(\n      path,\n      `holds NUL characters, which no document loam owns does — almost always UTF-16 saved without a byte-order ` +\n        `mark. Its bytes are valid UTF-8, so it decodes without complaint into text whose requirements, ` +\n        `frontmatter and headings all parse as ABSENT: the merge would compute over an empty baseline and write ` +\n        `that back, taking every requirement in the file with it.`,\n    );\n  }\n  return text;\n}\n\n/** Read a file loam is going to parse. The only supported way to turn a docs file into a string. */\nexport async function readUtf8(path: string): Promise<string> {\n  return decodeUtf8(await readFile(path), path);\n}\n\n/** Same bytes? Absence is its own value: a file that is gone is not a file that is empty. */\nexport function sameBytes(a: Buffer | null, b: Buffer | null): boolean {\n  return a === null || b === null ? a === b : a.equals(b);\n}\n\n/* ------------------------------------------------------------------ */\n/* Reading loam's own records back off the disk                        */\n/* ------------------------------------------------------------------ */\n\n/** The one spelling of a sha256 loam wrote, for reading one back out of a record. */\nexport function isDigest(value: unknown): value is string {\n  return typeof value === \"string\" && /^[0-9a-f]{64}$/.test(value);\n}\n\nexport function sha256(content: Buffer | string): string {\n  return typeof content === \"string\"\n    ? createHash(\"sha256\").update(content, \"utf8\").digest(\"hex\")\n    : createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\n"]}
+{"version":3,"file":"writes.js","sourceRoot":"","sources":["../../../src/core/staging/writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA+B5C,mDAAmD;AACnD,MAAM,UAAU,OAAO,CAAC,OAA+B;IACrD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAA+B;IACrE,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAuBD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAI1B,IAAI;IAHG,IAAI,GAAG,cAAc,CAAC;IAExC,YACW,IAAY,EACrB,MAAc;QAEd,KAAK,CAAC,GAAG,IAAI,IAAI,MAAM,yDAAyD,CAAC,CAAC;oBAHzE,IAAI;IAIf,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,UAAU,CAAC,KAAa,EAAE,IAAY;IAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,mGAAmG;YACjG,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CACpB,IAAI,EACJ,2GAA2G;YACzG,iGAAiG;YACjG,yGAAyG;YACzG,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oGAAoG;AACpG,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,SAAS,CAAC,CAAgB,EAAE,CAAgB;IAC1D,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,OAAO,OAAO,KAAK,QAAQ;QAChC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC5D,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC","sourcesContent":["/**\n * What a write IS before anything touches disk: the planned record, the staged\n * record, and the bytes both are made of.\n *\n * This is the package's floor. Everything else here — the lock, the swap, the\n * snapshot, the recovery journal — is a rule about WHEN bytes may land; only\n * this module decides what they are. Decoding lives here for the same reason:\n * text is produced only where a parser needs it and `readUtf8` is the one door,\n * so no later addition can reach a docs file through `readFile(…, \"utf8\")` and\n * silently substitute U+FFFD for bytes loam did not understand.\n */\nimport { isUtf8 } from \"node:buffer\";\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\n\n/**\n * A planned file write — the merge is computed fully before anything touches\n * disk. `content: null` means \"delete this file\": `unarchive` takes back a file the\n * archive created, and `subsystem sync` removes the generated views file and a\n * stray per-service project file beside an extending model.\n *\n * BYTES, not text. The whole write path — pre-image, staged content, snapshot,\n * the compare-and-set before each swap — moves Buffers, because a docs repo is\n * not guaranteed to hold text loam can decode: `Buffer.toString(\"utf8\")` never\n * fails, it substitutes U+FFFD, so reading a file as a string and writing the\n * string back is a silent, permanent rewrite of every byte loam did not\n * understand. It reached the snapshot too, so `unarchive` restored the damage\n * and reported success. Text is now produced only where a PARSER needs it, by\n * `decodeUtf8`, which refuses instead of substituting.\n */\nexport interface PlannedWrite {\n  path: string;\n  /**\n   * A `string` is accepted for the callers whose new version IS text they\n   * composed from nothing (a re-pinned delta, a restamped spec) and is encoded\n   * as UTF-8 once, at staging. A caller holding BYTES — anything derived from a\n   * file loam read — must hand over the Buffer: the round trip through a string\n   * is the corruption above.\n   */\n  content: string | Buffer | null;\n  /** Create the target atomically without replacing a concurrently created file. */\n  exclusive?: boolean;\n}\n\n/** The one place a planned write becomes bytes. */\nexport function toBytes(content: string | Buffer | null): Buffer | null {\n  return typeof content === \"string\" ? Buffer.from(content, \"utf8\") : content;\n}\n\n/**\n * The one place that decides whether a planned write is a CREATE *from the\n * filesystem*. (`core/verify/store/commit.ts` is the deliberate second rule:\n * it decides from the caller's held pre-image instead, because a CAS must\n * follow the read it promised, not what `existsSync` says now.)\n *\n * `exclusive` is a no-clobber create (link(2)), so it can only be asked of a\n * path that does not exist yet: asking it of an overwrite would fail EEXIST on\n * every single run. Deciding here — rather than at each of the dozen\n * `writes.push` sites in archive and unarchive — is what keeps the two commands\n * from disagreeing about which of their writes may safely lose a race. An\n * OVERWRITE is not left unguarded: `swapStaged` compares the target against the\n * pre-image immediately before the rename, so a file another writer changed\n * under us stops the commit instead of silently burying their bytes.\n */\nexport function planWrite(path: string, content: string | Buffer | null): PlannedWrite {\n  if (content !== null && !existsSync(path)) return { path, content, exclusive: true };\n  return { path, content };\n}\n\n/** A planned write with its new bytes parked next to the target, ready to swap in. */\nexport interface StagedWrite {\n  write: PlannedWrite;\n  /** What this write puts on disk — `write.content` encoded once. Null for a delete. */\n  content: Buffer | null;\n  /** Temp file holding the new bytes, in the target's OWN directory. Null for a delete. */\n  tmp: string | null;\n  /** The target's bytes before the swap; null when it did not exist. */\n  before: Buffer | null;\n  /**\n   * Topmost directory this write had to create, if any — a rollback owes the repo\n   * its directories back too. An empty `services/<svc>/` left standing is the\n   * fleet claiming a service that was never merged. Spelled as\n   * `mkdirReportingCreated` returns it, never as Node's raw `mkdir` report.\n   */\n  createdDir: string | null;\n  swapped: boolean;\n}\n\n\n\n/**\n * A file loam must PARSE that does not decode as the UTF-8 text loam owns.\n *\n * Commands map this to `merge-failed`: nothing was written, the file is named,\n * and re-saving it as UTF-8 makes the command work. The read-only migration\n * ingest already refuses non-UTF-8 input outright (core/openspec/) —\n * the destructive path has strictly more to lose, so it refuses the same way\n * rather than substituting U+FFFD and rewriting the file over the author.\n *\n * `reason` says what the bytes actually ARE, because the two ways a document\n * fails this test destroy different things: one substitutes bytes, the other\n * erases the whole document's meaning. A reader told the wrong one goes looking\n * in the wrong place. The advice that follows is the same either way, so it is\n * spelled once, here.\n */\nexport class NotUtf8Error extends Error {\n  override readonly name = \"NotUtf8Error\";\n\n  constructor(\n    readonly path: string,\n    reason: string,\n  ) {\n    super(`${path} ${reason} Nothing was written. Re-save it as UTF-8, then re-run.`);\n  }\n}\n\n/**\n * Decode bytes a parser is about to be handed, or refuse naming the file.\n *\n * Two tests, the same two the read path makes (document-bytes.ts's\n * `decodeDocument`), because this side has strictly more to lose by missing\n * either. `isUtf8` catches the byte sequences that cannot be UTF-8 at all —\n * which is what a byte-order mark makes UTF-16 into. Without a BOM, UTF-16LE of\n * ASCII is a sequence of perfectly VALID UTF-8 bytes: every other byte is NUL,\n * so `isUtf8` says yes, the file decodes with a U+0000 between every character,\n * and every parser loam owns reads its requirements, frontmatter and headings\n * as absent rather than as unreadable. On the read path that is a document\n * graded green while nothing in it was checked; here it is worse, because\n * `archive` merges against that empty baseline and writes the result back — the\n * author's requirements are not mis-read, they are gone, and the undo snapshot\n * records the same emptiness as the pre-image.\n */\nfunction decodeUtf8(bytes: Buffer, path: string): string {\n  if (!isUtf8(bytes)) {\n    throw new NotUtf8Error(\n      path,\n      `is not valid UTF-8 — loam parses this file as text and writes it back, which would replace every ` +\n        `undecodable byte with U+FFFD, in the living document AND in the undo snapshot.`,\n    );\n  }\n  const text = bytes.toString(\"utf8\");\n  if (text.includes(\"\\u0000\")) {\n    throw new NotUtf8Error(\n      path,\n      `holds NUL characters, which no document loam owns does — almost always UTF-16 saved without a byte-order ` +\n        `mark. Its bytes are valid UTF-8, so it decodes without complaint into text whose requirements, ` +\n        `frontmatter and headings all parse as ABSENT: the merge would compute over an empty baseline and write ` +\n        `that back, taking every requirement in the file with it.`,\n    );\n  }\n  return text;\n}\n\n/** Read a file loam is going to parse. The only supported way to turn a docs file into a string. */\nexport async function readUtf8(path: string): Promise<string> {\n  return decodeUtf8(await readFile(path), path);\n}\n\n/** Same bytes? Absence is its own value: a file that is gone is not a file that is empty. */\nexport function sameBytes(a: Buffer | null, b: Buffer | null): boolean {\n  return a === null || b === null ? a === b : a.equals(b);\n}\n\n/* ------------------------------------------------------------------ */\n/* Reading loam's own records back off the disk                        */\n/* ------------------------------------------------------------------ */\n\n/** The one spelling of a sha256 loam wrote, for reading one back out of a record. */\nexport function isDigest(value: unknown): value is string {\n  return typeof value === \"string\" && /^[0-9a-f]{64}$/.test(value);\n}\n\nexport function sha256(content: Buffer | string): string {\n  return typeof content === \"string\"\n    ? createHash(\"sha256\").update(content, \"utf8\").digest(\"hex\")\n    : createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\n"]}