@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/core/verify/{file.js → read/shape.js}

@@ -1,83 +1,17 @@
 /**
- * `verification.yaml` read back, and refused when it cannot be trusted.
+ * What a file must hold to be a verification record — the shape check and the
+ * self-consistency check every file of the record passes on the way in.
  *
- * Reading is deliberately not the inverse of rendering. A record loam wrote is
- * re-graded on the way in — unreadable YAML, a shape that is not a
- * verification, a `summary` that disagrees with the claims below it — because
- * the file is data meant to survive without loam, and anything may have edited
- * it since. The render lives with the writer it feeds (`store/render.ts`
- * produces exactly the bytes `store/commit.ts` swaps into place; races and
- * kills mid-write live there too), and the lock that serialises writers is
- * taken by `commands/verify/verify.ts` before this module's authoritative
- * read. Nothing here touches the filesystem except to read.
+ * Moved out of `./file.ts` when the record became several files: that module
+ * now owns WHICH files make up a record and how a damaged one is reported,
+ * while this one owns what any single file has to say to be read at all. The
+ * two are phases — find the files, then grade each — and the grading never
+ * needed to know where its bytes came from.
  */
-import { lstat, readFile } from "node:fs/promises";
-import { parse } from "yaml";
-import { isRecord } from "../kernel/records.js";
-import { VERDICTS } from "./answers.js";
-import { isEvidencePinList } from "./pins/pin.js";
-import { tallyAnswers, verificationPath } from "./record.js";
-export async function readVerificationState(featureDir) {
-    const path = verificationPath(featureDir);
-    let raw;
-    try {
-        raw = await readFile(path);
-    }
-    catch (err) {
-        if (err.code === "ENOENT") {
-            // ENOENT is "absent" — except from a symlink whose target is gone, which
-            // `existsSync` used to fold into the same answer. That mislabel was a
-            // trap: the read said "no record" while the commit's exclusive link(2)
-            // saw the link itself and refused EEXIST, so every `--record` answered
-            // `record-raced` with advice (re-run) that could never work. The lstat
-            // must CONFIRM the link before the message asserts one: a real file can
-            // also appear between the two calls, and telling its owner to "remove
-            // the link" would delete a valid record.
-            let entry;
-            try {
-                entry = await lstat(path);
-            }
-            catch {
-                return { state: "absent" };
-            }
-            if (entry.isSymbolicLink()) {
-                return {
-                    state: "unreadable",
-                    reason: "it is a symlink whose target does not exist — replace the link with a real record, or remove it",
-                };
-            }
-            return {
-                state: "unreadable",
-                reason: "it appeared while being read — another writer is landing; re-run",
-            };
-        }
-        return { state: "unreadable", reason: err instanceof Error ? err.message : String(err) };
-    }
-    let doc;
-    try {
-        doc = parse(raw.toString("utf8"));
-    }
-    catch (err) {
-        return { state: "unreadable", reason: yamlReason(err) };
-    }
-    const verification = asVerification(doc);
-    if (verification === null) {
-        return {
-            state: "unreadable",
-            reason: "it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)",
-        };
-    }
-    const miscount = summaryDisagreement(verification);
-    if (miscount === null)
-        return { state: "ok", verification, raw };
-    return {
-        state: "unreadable",
-        // Spelled twice on purpose: the field is what a caller branches on, the
-        // prose is what a terminal prints and what somebody greps for.
-        code: "verify.record-miscounted",
-        reason: `verify.record-miscounted: ${miscount}`,
-    };
-}
+import { isRecord } from "../../kernel/records.js";
+import { VERDICTS } from "../answers.js";
+import { isEvidencePinList } from "../pins/pin.js";
+import { tallyAnswers } from "../record.js";
 /**
  * Does the record's `summary` add up from its own `claims[]`?
  *
@@ -89,7 +23,7 @@ export async function readVerificationState(featureDir) {
  * record that contradicts itself is refused like any other file loam cannot
  * use. The code is in the reason: it travels wherever the reason is printed.
  */
-function summaryDisagreement(v) {
+export function summaryDisagreement(v) {
     const t = tallyAnswers(v.claims);
     const unanswered = v.summary.unanswered ?? 0;
     const says = [];
@@ -114,31 +48,9 @@ function summaryDisagreement(v) {
         ? null
         : `its summary ${says.join(", ")} — the record contradicts itself, so neither half can be believed`;
 }
-/** A YAML failure with its line, when the parser located one: that line is the fix. */
-function yamlReason(err) {
-    const message = err instanceof Error ? err.message.split("\n")[0].trim() : String(err);
-    const pos = err?.linePos;
-    const line = Array.isArray(pos) ? pos[0]?.line : undefined;
-    return line === undefined ? `YAML error: ${message}` : `YAML error at line ${line}: ${message}`;
-}
-/**
- * The record beside a feature, or null when there is none loam can use. Kept
- * for readers that have nothing to say about the difference (`loam list`'s
- * verification column shows one glyph either way); anything that WRITES must
- * use {@link readVerificationState} instead, or it overwrites what it could not
- * read.
- *
- * A record whose summary contradicts its own claims is one of the nulls now, so
- * no reader can print its counts as fact. Reading it as ABSENT is the safe half
- * of the truth and not the whole of it: a reader that can say why should take
- * {@link readVerificationState} and its `code`.
- */
-export async function readVerification(featureDir) {
-    const read = await readVerificationState(featureDir);
-    return read.state === "ok" ? read.verification : null;
-}
 /**
- * The shape check `readVerification` stands behind: everything its readers
+ * The shape check `readVerificationState` (`./file.ts`) stands behind:
+ * everything its readers
  * dereference (verify's report/frozen views, list's verification column) must
  * be present and typed, or the cast would manufacture a Verification that
  * crashes them. Deliberately no tighter than the readers need: extra keys pass
@@ -146,7 +58,7 @@ export async function readVerification(featureDir) {
  * predate `--results`) and is any string, like `kind` — the readers only ever
  * compare them, and a record written by a newer loam must not read as absent.
  */
-function asVerification(doc) {
+export function asVerification(doc) {
     if (!isRecord(doc))
         return null;
     const summary = doc["summary"];
@@ -254,4 +166,4 @@ function isConsumedContractReport(v) {
 function isCount(v) {
     return typeof v === "number" && Number.isInteger(v);
 }
-//# sourceMappingURL=file.js.map
+//# sourceMappingURL=shape.js.map

package/dist/core/verify/read/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../../src/core/verify/read/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAqB,MAAM,cAAc,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAe;IACjD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACrE,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,6BAA6B,KAAK,KAAK,KAAK,GAAG,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,SAAS,mCAAmC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,WAAW,qCAAqC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACtD,IAAI,CAAC,IAAI,CACP,QAAQ,CAAC,CAAC,OAAO,CAAC,MAAM,YAAY,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,UAAU,aAAa,yBAAyB,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAC5I,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC;QACtB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,eAAe,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,mEAAmE,CAAC;AACxG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IACE,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,QAAQ;QAClC,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,QAAQ;QACnC,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ;QACpC,CAAC,QAAQ,CAAC,OAAO,CAAC;QAClB,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC9B,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAChC,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QACxE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAC7B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9B,IAAI,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChH,IAAI,CAAC,CAAC,SAAS,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAChF,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,CAAE,QAA8B,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC7G,8EAA8E;QAC9E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QACnG,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1E,IAAI,CAAC,CAAC,aAAa,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,aAAa,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxF,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,uEAAuE;QACvE,cAAc;QACd,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,IAAI,GAAG,CAAC,cAAc,CAAC,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACrD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC9B,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC1H,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YACzD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC;gBAAE,OAAO,IAAI,CAAC;YACjG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChD,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,GAA8B,CAAC;AACxC,CAAC;AAED,wGAAwG;AACxG,SAAS,gBAAgB,CAAC,CAAU;IAClC,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CACL,QAAQ,CAAC,CAAC,CAAC;QACX,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CACxB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,wBAAwB,CAAC,CAAU;IAC1C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,CACL,QAAQ,CAAC,CAAC,CAAC;QACX,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ;QAC/B,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ;QAC9B,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC","sourcesContent":["/**\n * What a file must hold to be a verification record — the shape check and the\n * self-consistency check every file of the record passes on the way in.\n *\n * Moved out of `./file.ts` when the record became several files: that module\n * now owns WHICH files make up a record and how a damaged one is reported,\n * while this one owns what any single file has to say to be read at all. The\n * two are phases — find the files, then grade each — and the grading never\n * needed to know where its bytes came from.\n */\nimport { isRecord } from \"../../kernel/records.js\";\nimport { VERDICTS } from \"../answers.js\";\nimport { isEvidencePinList } from \"../pins/pin.js\";\nimport { tallyAnswers, type Verification } from \"../record.js\";\n\n/**\n * Does the record's `summary` add up from its own `claims[]`?\n *\n * The summary is what wrote the file; the claims are what it answered. Nothing\n * ever compared them, so every reader that took the shortcut — verify's frozen\n * verdict for a shipped feature, list's column, status's block — reported a\n * record full of unconfirmed claims as fully confirmed. Believing either side\n * over the other would be a guess about which half was tampered with, so a\n * record that contradicts itself is refused like any other file loam cannot\n * use. The code is in the reason: it travels wherever the reason is printed.\n */\nexport function summaryDisagreement(v: Verification): string | null {\n  const t = tallyAnswers(v.claims);\n  const unanswered = v.summary.unanswered ?? 0;\n  const says: string[] = [];\n  // Before the arithmetic, because a negative count defeats it: `unanswered:\n  // -2` is never something loam wrote, and it is the one value that lets a\n  // hand-edited summary balance its own books — every comparison below then\n  // agrees, and a record contradicting its claims reported `verified`.\n  for (const [field, value] of Object.entries(v.summary)) {\n    if (typeof value === \"number\" && value < 0) says.push(`carries a negative count (${field}: ${value})`);\n  }\n  if (v.summary.confirmed !== t.confirmed) {\n    says.push(`says ${v.summary.confirmed} confirmed where claims[] holds ${t.confirmed}`);\n  }\n  if (v.summary.unconfirmed !== t.unconfirmed) {\n    says.push(`says ${v.summary.unconfirmed} unconfirmed where claims[] holds ${t.unconfirmed}`);\n  }\n  if (v.summary.claims !== v.claims.length + unanswered) {\n    says.push(\n      `says ${v.summary.claims} claim(s)${unanswered === 0 ? \"\" : ` including ${unanswered} unanswered`} where claims[] holds ${v.claims.length}`,\n    );\n  }\n  return says.length === 0\n    ? null\n    : `its summary ${says.join(\", \")} — the record contradicts itself, so neither half can be believed`;\n}\n\n/**\n * The shape check `readVerificationState` (`./file.ts`) stands behind:\n * everything its readers\n * dereference (verify's report/frozen views, list's verification column) must\n * be present and typed, or the cast would manufacture a Verification that\n * crashes them. Deliberately no tighter than the readers need: extra keys pass\n * (a human may annotate), `answered_by` stays optional (absent in records that\n * predate `--results`) and is any string, like `kind` — the readers only ever\n * compare them, and a record written by a newer loam must not read as absent.\n */\nexport function asVerification(doc: unknown): Verification | null {\n  if (!isRecord(doc)) return null;\n  const summary = doc[\"summary\"];\n  if (\n    typeof doc[\"feature\"] !== \"string\" ||\n    typeof doc[\"recorded\"] !== \"string\" ||\n    typeof doc[\"checklist\"] !== \"string\" ||\n    !isRecord(summary) ||\n    !isCount(summary[\"claims\"]) ||\n    !isCount(summary[\"confirmed\"]) ||\n    !isCount(summary[\"unconfirmed\"]) ||\n    (summary[\"unanswered\"] !== undefined && !isCount(summary[\"unanswered\"])) ||\n    !Array.isArray(doc[\"claims\"])\n  ) {\n    return null;\n  }\n  for (const c of doc[\"claims\"]) {\n    if (!isRecord(c)) return null;\n    if (typeof c[\"id\"] !== \"string\" || typeof c[\"kind\"] !== \"string\" || typeof c[\"claim\"] !== \"string\") return null;\n    if (c[\"subject\"] !== undefined && typeof c[\"subject\"] !== \"string\") return null;\n    if (typeof c[\"verdict\"] !== \"string\" || !(VERDICTS as readonly string[]).includes(c[\"verdict\"])) return null;\n    // The frozen view iterates evidence per claim — a scalar here would crash it.\n    if (!Array.isArray(c[\"evidence\"]) || c[\"evidence\"].some((e) => typeof e !== \"string\")) return null;\n    if (c[\"note\"] !== undefined && typeof c[\"note\"] !== \"string\") return null;\n    if (c[\"answered_by\"] !== undefined && typeof c[\"answered_by\"] !== \"string\") return null;\n    // Absent fine, present whole — the isConsumedContractReport precedent, and\n    // the guard body lives with the pin shape it vouches for (pins/pin.ts). A\n    // broken pins block makes the whole record unreadable and therefore never\n    // overwritten: skipping it instead would read a hand-damaged record as\n    // drift-free.\n    if (!isEvidencePinList(c[\"evidence_pins\"])) return null;\n  }\n  if (doc[\"schema\"] !== undefined && doc[\"schema\"] !== 2) return null;\n  if (!isConsumedReport(doc[\"report\"])) return null;\n  if (!isConsumedContractReport(doc[\"contractReport\"])) return null;\n  if (doc[\"attestations\"] !== undefined) {\n    if (!Array.isArray(doc[\"attestations\"])) return null;\n    for (const a of doc[\"attestations\"]) {\n      if (!isRecord(a)) return null;\n      if (typeof a[\"service\"] !== \"string\" || typeof a[\"commit\"] !== \"string\" || typeof a[\"recorded\"] !== \"string\") return null;\n      if (!/^[0-9a-f]{40,64}$/i.test(a[\"commit\"])) return null;\n      if (!Array.isArray(a[\"claims\"]) || a[\"claims\"].some((id) => typeof id !== \"string\")) return null;\n      if (!isConsumedReport(a[\"report\"])) return null;\n      if (!isConsumedContractReport(a[\"contractReport\"])) return null;\n    }\n  }\n  return doc as unknown as Verification;\n}\n\n/** Absent is fine — most records answer nothing from a report. Present must be whole: it is printed. */\nfunction isConsumedReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"scenarios\"])\n  );\n}\n\n/**\n * The contract report's pin, exactly as loose as {@link isConsumedReport}:\n * absent fine, present whole — for the fields the readers dereference.\n * `format` is OPTIONAL here even though loam always writes it: nothing in the\n * readers dereferences it (it is provenance for a person, echoed only inside\n * whole-object payloads), and the generated AGENTS.md teaches the pin as\n * path/sha256/mtime/operation-count — so a hand-written block faithful to that\n * teaching must not make the WHOLE record unreadable over a field no reader\n * uses. When present it must be a string, and any string: a record written by\n * a newer loam that learned a second report format must not read as\n * unreadable here.\n */\nfunction isConsumedContractReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"operations\"]) &&\n    (v[\"format\"] === undefined || typeof v[\"format\"] === \"string\")\n  );\n}\n\n/**\n * A summary count: an integer. YAML hands back strings for anything quoted.\n * Negativity is deliberately NOT checked here: a negative count is a summary\n * that disagrees with the claims below it, and `summaryDisagreement` owns that\n * refusal — failing the SHAPE check instead made the message list five keys\n * that were all present, while the miscount branch one call away holds the\n * advice the case actually needs.\n */\nfunction isCount(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v);\n}\n"]}

package/dist/core/verify/read/union.js

@@ -0,0 +1,105 @@
+/**
+ * The record as the union of its files: the one-file `verification.yaml` and
+ * one `verification/<svc>.yaml` per attesting service, added up into the single
+ * `Verification` every reader already takes.
+ *
+ * Pure on purpose — `./file.ts` reads and grades the bytes, the writer in
+ * `commands/verify/record.ts` hands in the files as they will stand after its
+ * commit, and both get the same answer from the same arithmetic. A writer that
+ * computed the post-record verdict its own way would be the second opinion
+ * `../record.ts` exists to prevent; this way what `--record` prints is exactly
+ * what the next read will say.
+ *
+ * Nothing here reads a `summary` as fact. Each file's own `summary` was graded
+ * against its own `claims[]` on the way in, and the union's is recomputed here
+ * from the claims it actually counts — so the block that used to be the
+ * hottest conflict in a fleet's docs PRs is now derived, never merged.
+ */
+import { tallyAnswers } from "../record.js";
+/**
+ * Add the files up. `services` are the graded per-service files, each a
+ * schema-2 record holding exactly its own service's attestation (the reader
+ * refuses one that does not). Null only when there is nothing at all.
+ *
+ * With no per-service file the one-file record is returned VERBATIM — a record
+ * written before the directory existed, or by the all-at-once form, reads
+ * exactly as it always did, retained answers and all.
+ *
+ * Otherwise the record answers ONE version of the checklist. A file that
+ * answered a different version keeps its attestation on the list — that is
+ * what `verify.checklist-forked` reads to name it — but its answers do not
+ * count. The single shared file used to settle this by rewriting: the last
+ * writer pruned everybody's answers to ITS checklist. Per-service files are
+ * never rewritten by anyone else, so nothing can prune them, and counting an
+ * answer filed against another question set would let an old id that the
+ * feature no longer asks fill the slot of a new one it does — a record reading
+ * `verified` over a question nobody answered. Excluding is the honest half:
+ * the service behind is named, and recording it again is the whole fix.
+ *
+ * WHICH version is `live`'s to say whenever the caller knows it: the digest of
+ * the checklist the feature asks now (`loam verify`, its writer, `tasks`, and
+ * `status`/`list`/`gate` for an in-flight feature all derive it anyway), or
+ * the one `loam archive` captured as it merged. The files that answered it
+ * count. Only when no caller knows — the frozen view of an archived feature
+ * with no capture — or when no file answered it does the newest file decide
+ * (by `recorded`, a later service id breaking a same-day tie, and any
+ * per-service file outranking the one-file record). Newest-by-date used to
+ * decide always, and `recorded` is a DATE: a service recording this morning
+ * against the current checklist lost the tie to a service with a later id that
+ * recorded an older checklist an hour before — or a day later, from a docs
+ * branch that was behind — so the current answers were dropped, every reader
+ * called the record stale, and the writer printed a tally its own answers were
+ * not in.
+ */
+export function assembleRecord(legacy, services, live) {
+    if (services.length === 0)
+        return legacy;
+    const filed = new Set(services.flatMap((s) => (s.attestations ?? []).map((a) => a.service)));
+    const parts = [...legacyRemnant(legacy, filed), ...services];
+    // The question being asked now, when somebody answered it; every part only
+    // when nobody did — then the record is stale under every reader whichever
+    // part represents it, and the newest is the one a reader recognises.
+    const answering = live === undefined ? [] : parts.filter((part) => part.checklist === live);
+    const pool = answering.length > 0 ? answering : parts;
+    // `>=` so a later part wins a same-day tie: services arrive sorted by id,
+    // and after the one-file remnant, which is exactly the precedence above.
+    const current = pool.reduce((newest, part) => (part.recorded >= newest.recorded ? part : newest));
+    const claims = parts.filter((part) => part.checklist === current.checklist).flatMap((part) => part.claims);
+    const tally = tallyAnswers(claims);
+    return {
+        schema: 2,
+        feature: current.feature,
+        recorded: current.recorded,
+        checklist: current.checklist,
+        summary: {
+            claims: current.summary.claims,
+            confirmed: tally.confirmed,
+            unconfirmed: tally.unconfirmed,
+            unanswered: current.summary.claims - claims.length,
+        },
+        claims,
+        attestations: parts.flatMap((part) => part.attestations ?? []).sort((a, b) => a.service.localeCompare(b.service)),
+    };
+}
+/**
+ * What of the one-file record still counts once services have files of their
+ * own: the attestations of the services that have NOT re-recorded since, and
+ * their answers.
+ *
+ * A schema-1 (all-at-once) file contributes nothing. Its answers carry no
+ * commit attestation, so a federated record could never count them — the rule
+ * the first federated write applied when it used to overwrite the file, and the
+ * reason that write now deletes it. A schema-2 file's attestation for a service
+ * that has a file of its own is superseded by that file and drops out, answers
+ * with it; when every attestation in it is superseded, nothing in it counts.
+ */
+function legacyRemnant(legacy, filed) {
+    if (legacy === null || legacy.schema !== 2)
+        return [];
+    const attestations = (legacy.attestations ?? []).filter((a) => !filed.has(a.service));
+    if (attestations.length === 0)
+        return [];
+    const kept = new Set(attestations.map((a) => a.service));
+    return [{ ...legacy, attestations, claims: legacy.claims.filter((c) => c.subject !== undefined && kept.has(c.subject)) }];
+}
+//# sourceMappingURL=union.js.map

package/dist/core/verify/read/union.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"union.js","sourceRoot":"","sources":["../../../../src/core/verify/read/union.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The record as the union of its files: the one-file `verification.yaml` and\n * one `verification/<svc>.yaml` per attesting service, added up into the single\n * `Verification` every reader already takes.\n *\n * Pure on purpose — `./file.ts` reads and grades the bytes, the writer in\n * `commands/verify/record.ts` hands in the files as they will stand after its\n * commit, and both get the same answer from the same arithmetic. A writer that\n * computed the post-record verdict its own way would be the second opinion\n * `../record.ts` exists to prevent; this way what `--record` prints is exactly\n * what the next read will say.\n *\n * Nothing here reads a `summary` as fact. Each file's own `summary` was graded\n * against its own `claims[]` on the way in, and the union's is recomputed here\n * from the claims it actually counts — so the block that used to be the\n * hottest conflict in a fleet's docs PRs is now derived, never merged.\n */\nimport { tallyAnswers, type Verification } from \"../record.js\";\n\n/**\n * Add the files up. `services` are the graded per-service files, each a\n * schema-2 record holding exactly its own service's attestation (the reader\n * refuses one that does not). Null only when there is nothing at all.\n *\n * With no per-service file the one-file record is returned VERBATIM — a record\n * written before the directory existed, or by the all-at-once form, reads\n * exactly as it always did, retained answers and all.\n *\n * Otherwise the record answers ONE version of the checklist. A file that\n * answered a different version keeps its attestation on the list — that is\n * what `verify.checklist-forked` reads to name it — but its answers do not\n * count. The single shared file used to settle this by rewriting: the last\n * writer pruned everybody's answers to ITS checklist. Per-service files are\n * never rewritten by anyone else, so nothing can prune them, and counting an\n * answer filed against another question set would let an old id that the\n * feature no longer asks fill the slot of a new one it does — a record reading\n * `verified` over a question nobody answered. Excluding is the honest half:\n * the service behind is named, and recording it again is the whole fix.\n *\n * WHICH version is `live`'s to say whenever the caller knows it: the digest of\n * the checklist the feature asks now (`loam verify`, its writer, `tasks`, and\n * `status`/`list`/`gate` for an in-flight feature all derive it anyway), or\n * the one `loam archive` captured as it merged. The files that answered it\n * count. Only when no caller knows — the frozen view of an archived feature\n * with no capture — or when no file answered it does the newest file decide\n * (by `recorded`, a later service id breaking a same-day tie, and any\n * per-service file outranking the one-file record). Newest-by-date used to\n * decide always, and `recorded` is a DATE: a service recording this morning\n * against the current checklist lost the tie to a service with a later id that\n * recorded an older checklist an hour before — or a day later, from a docs\n * branch that was behind — so the current answers were dropped, every reader\n * called the record stale, and the writer printed a tally its own answers were\n * not in.\n */\nexport function assembleRecord(\n  legacy: Verification | null,\n  services: readonly Verification[],\n  live?: string,\n): Verification | null {\n  if (services.length === 0) return legacy;\n  const filed = new Set(services.flatMap((s) => (s.attestations ?? []).map((a) => a.service)));\n  const parts = [...legacyRemnant(legacy, filed), ...services];\n  // The question being asked now, when somebody answered it; every part only\n  // when nobody did — then the record is stale under every reader whichever\n  // part represents it, and the newest is the one a reader recognises.\n  const answering = live === undefined ? [] : parts.filter((part) => part.checklist === live);\n  const pool = answering.length > 0 ? answering : parts;\n  // `>=` so a later part wins a same-day tie: services arrive sorted by id,\n  // and after the one-file remnant, which is exactly the precedence above.\n  const current = pool.reduce((newest, part) => (part.recorded >= newest.recorded ? part : newest));\n  const claims = parts.filter((part) => part.checklist === current.checklist).flatMap((part) => part.claims);\n  const tally = tallyAnswers(claims);\n  return {\n    schema: 2,\n    feature: current.feature,\n    recorded: current.recorded,\n    checklist: current.checklist,\n    summary: {\n      claims: current.summary.claims,\n      confirmed: tally.confirmed,\n      unconfirmed: tally.unconfirmed,\n      unanswered: current.summary.claims - claims.length,\n    },\n    claims,\n    attestations: parts.flatMap((part) => part.attestations ?? []).sort((a, b) => a.service.localeCompare(b.service)),\n  };\n}\n\n/**\n * What of the one-file record still counts once services have files of their\n * own: the attestations of the services that have NOT re-recorded since, and\n * their answers.\n *\n * A schema-1 (all-at-once) file contributes nothing. Its answers carry no\n * commit attestation, so a federated record could never count them — the rule\n * the first federated write applied when it used to overwrite the file, and the\n * reason that write now deletes it. A schema-2 file's attestation for a service\n * that has a file of its own is superseded by that file and drops out, answers\n * with it; when every attestation in it is superseded, nothing in it counts.\n */\nfunction legacyRemnant(legacy: Verification | null, filed: ReadonlySet<string>): Verification[] {\n  if (legacy === null || legacy.schema !== 2) return [];\n  const attestations = (legacy.attestations ?? []).filter((a) => !filed.has(a.service));\n  if (attestations.length === 0) return [];\n  const kept = new Set(attestations.map((a) => a.service));\n  return [{ ...legacy, attestations, claims: legacy.claims.filter((c) => c.subject !== undefined && kept.has(c.subject)) }];\n}\n"]}

package/dist/core/verify/record.js

@@ -12,9 +12,8 @@
  * away, which is the fleet loam exists for — the record marks it attested, and
  * `attestedNotice` says so on every surface that reads the record.
  */
-import { join } from "node:path";
 import {} from "./claims/identity.js";
-import {} from "./answers.js";
+import { ANSWERED_BY } from "./answers.js";
 import {} from "./pins/pin.js";
 /**
  * The confirmed `scenario.tested` claims that no test run answered.
@@ -45,6 +44,20 @@ export function confirmedProvenance(claims) {
     const ran = { runner: by("runner"), "external-runner": by("external-runner") };
     return { ...ran, agent: done.length - ran.runner - ran["external-runner"] };
 }
+/**
+ * The confirmed split as the per-feature human views print it — `13 runner · 6 agent`, empty
+ * buckets left out. `loam status <FEAT>` and `list`'s verification column print it beside the
+ * verdict because the verdict turns on the scenario claims alone ({@link verificationVerdict}), so
+ * `verified 19/19 confirmed` read as nineteen runs over a record where six were an agent's word —
+ * the split `--json` and the fleet scorecard already carried. The scorecard keeps all three keys
+ * for its stable-shape reason (validate's scorecard/print.ts); a one-feature line has no shape to
+ * keep, and a column of zeros is width the reader pays for nothing.
+ */
+export function answeredSplit(answered) {
+    return ANSWERED_BY.filter((who) => answered[who] > 0)
+        .map((who) => `${answered[who]} ${who}`)
+        .join(" · ");
+}
 /**
  * `unanswered` is the count the answers themselves cannot show: a federated
  * record holds only what somebody answered, and the claims still owed to other
@@ -71,6 +84,24 @@ export function tallyAnswers(claims, unanswered = 0) {
 export function tallyRecord(v) {
     return tallyAnswers(v.claims, v.summary.unanswered ?? 0);
 }
+/**
+ * The recorded rows that may answer a checklist, keyed by claim id — the one
+ * spelling of the attestation-scoping rule. A legacy (no `schema`) record is
+ * all-at-once, so every row answers. In a federated record a row only counts
+ * where an attestation from the claim's OWN subject (per `claims`, the live
+ * checklist) listed it, so one repository cannot answer another's claims by
+ * writing their ids into its own attestation. `verify`'s read view and `loam
+ * tasks` each used to carry a copy, the second labelled "a deliberate mirror"
+ * because core could not import the command module the first lived in; the
+ * rule lives here now and both import it.
+ */
+export function countedAnswers(claims, recorded) {
+    const subjects = new Map(claims.map((claim) => [claim.id, claim.subject]));
+    const attested = recorded.schema !== 2
+        ? null
+        : new Set((recorded.attestations ?? []).flatMap((a) => a.claims.filter((id) => subjects.get(id) === a.service)));
+    return new Map(recorded.claims.filter((c) => attested === null || attested.has(c.id)).map((c) => [c.id, c]));
+}
 /**
  * Three states, because two were a lie. `verified` is the strong claim — every
  * question answered, every answer confirmed, and every scenario answered by a
@@ -101,7 +132,8 @@ export function attestedNotice(claims, feature) {
         code: "verify.scenario-attested",
         severity: "warn",
         message: `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(", ")}. ` +
-            `Answer them mechanically once the suite runs: \`loam verify ${feature} --results <cucumber.json>\`.`,
+            `Answer them mechanically once the suite runs: \`loam verify ${feature} --results <report.json>\` — ` +
+            "a cucumber JSON report, or loam's runner-neutral loamScenarioReport shape for any other runner.",
         claims: ids,
     };
 }
@@ -130,13 +162,4 @@ export function openClaimsNotice(tally, feature) {
             `treat ${feature} as unverified until every claim is answered and confirmed.`,
     };
 }
-/**
- * Where the record lives: inside the feature, so `archive` carries it into
- * `features/archive/` with everything else and a reviewer finds it next to the
- * delta it is about. YAML rather than frontmatter or JSON — it is data, it has
- * to survive without loam, and one claim per block is a diff a person can read.
- */
-export function verificationPath(featureDir) {
-    return join(featureDir, "verification.yaml");
-}
 //# sourceMappingURL=record.js.map

package/dist/core/verify/record.js.map

@@ -1 +1 @@
-{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/core/verify/record.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What gets written down, and how a set of answers counts up to a verdict.\n *\n * The shapes and the arithmetic are one module because they are one claim about\n * the same numbers: `tallyRecord` recounts from the answers rather than reading\n * the `summary` field back, so a record whose header disagrees with its own\n * claims is caught rather than believed. A separate counter would be a second\n * opinion, which is precisely what this file exists to prevent.\n *\n * `verified` is reserved for a checklist whose scenarios a RUN answered.\n * Where an agent answered one instead — a legacy service whose suite is months\n * away, which is the fleet loam exists for — the record marks it attested, and\n * `attestedNotice` says so on every surface that reads the record.\n */\nimport { join } from \"node:path\";\nimport { type ClaimKind } from \"./claims/identity.js\";\nimport { type AnsweredBy, type Verdict } from \"./answers.js\";\nimport { type EvidencePin } from \"./pins/pin.js\";\n\nexport interface RecordedClaim {\n  id: string;\n  kind: ClaimKind;\n  /** Present in federated records; omitted by legacy records written before schema 2. */\n  subject?: string;\n  claim: string;\n  verdict: Verdict;\n  /** Who answered — absent only in records written before `--results` existed. */\n  answered_by?: AnsweredBy;\n  evidence: string[];\n  note?: string;\n  /**\n   * One pin per file:line citation of a federated agent-confirmed answer: the\n   * cited file's normalized sha256 at the attested commit, the cited line's\n   * text, and the claim's token where it asserts one. A pin records which\n   * text was cited at that commit so `loam validate`, run later in the\n   * service's own repo, can convict drift; it does not prove the claim true —\n   * a faithful pin of the wrong line is still a wrong answer. Absent on\n   * runner-answered claims (their evidence names a report entry, not a file)\n   * and on every record written before pins existed.\n   */\n  evidence_pins?: EvidencePin[];\n}\n\n/**\n * The test report a `--results` run consumed.\n *\n * Nothing can prove a JSON file came from executing a particular commit — a\n * report is bytes, and bytes are writable. What loam can do is stop leaving the\n * question open: it records exactly which file it read (inside the attesting\n * repository, resolved by the same path rules as evidence), the sha256 of the\n * bytes it read, the file's own mtime and how many digest-tagged scenarios it\n * carried. A reviewer holding the repository can tell whether this is that\n * file; before this, `answered_by: runner` named nothing at all.\n */\nexport interface ConsumedReport {\n  /** As it was passed to `--results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read, so `shasum -a 256 <path>` answers the question. */\n  digest: string;\n  /** ISO-8601 mtime of the report file — when the run that wrote it finished. */\n  mtime: string;\n  /** How many digest-tagged scenarios the report carried. */\n  scenarios: number;\n}\n\n/**\n * The contract-test report a `--contract-results` run consumed — the same pin,\n * the same honesty, for the report that answers `api.exposes` claims by\n * operationId. Nothing here proves the file came from executing the attested\n * commit either; the digest identifies WHICH file was consumed, and the\n * federated form binds a committed one to the commit exactly as `report:` is.\n */\nexport interface ConsumedContractReport {\n  /** As it was passed to `--contract-results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read. */\n  digest: string;\n  /** ISO-8601 mtime of the report file. */\n  mtime: string;\n  /** How many distinct operationIds the report's entries name. */\n  operations: number;\n  /**\n   * Which accepted shape the report was read as — `\"generic\"` for the\n   * documented `loamContractReport: 1` shape, the only one v1 accepts. loam\n   * always writes it, but the READ shape keeps it optional: no reader\n   * dereferences it, so a hand-written pin without it stays a readable record\n   * (`isConsumedContractReport` in ./file.ts says why) — and it is a string\n   * rather than a closed union so a format a NEWER loam learned to read stays\n   * readable here too.\n   */\n  format?: string;\n}\n\n/**\n * Both mechanical answer sheets one recording run may consume, together\n * because they are validated together (`validateServiceEvidence` binds each to\n * the attested commit) and filed together (on the record all-at-once, inside\n * the service's attestation federated). Two loose optional parameters made the\n * inconsistent pair representable at every call site.\n */\nexport interface ConsumedReports {\n  results?: ConsumedReport;\n  contract?: ConsumedContractReport;\n}\n\n/** A service repository's commit-bound contribution to a federated record. */\nexport interface ServiceAttestation {\n  service: string;\n  commit: string;\n  recorded: string;\n  /** Claim ids this commit answered. Kept explicit so stale answers can be pruned safely. */\n  claims: string[];\n  /**\n   * The checklist digest THIS attestation answered.\n   *\n   * The record carries one `checklist` for the whole file, which is the right\n   * field for the all-at-once form and an incomplete one for a federated\n   * record: two services attesting a week apart across a changed delta write\n   * the same top-level digest, and nothing in the file can say they answered\n   * different questions. With this, `verify.checklist-forked` can.\n   *\n   * Optional forever. An attestation written before this field existed carries\n   * no claim about which checklist it answered, and inventing one from the\n   * record-level digest would be asserting exactly the thing that cannot be\n   * known — the `evidence.unpinned` precedent, one axis over.\n   */\n  checklist?: string;\n  /**\n   * The docs-repo commit the checklist was computed from, when the docs repo is\n   * a git repository with a committed HEAD.\n   *\n   * `commit` pins the SERVICE repo — the code the evidence points into.\n   * Nothing pinned the side the QUESTION came from, so a reader could not tell\n   * a re-record against an unchanged feature from one against a rewritten\n   * delta. Absent whenever git cannot answer: a docs repo is not required to be\n   * a git checkout, and a missing pin is not a defect.\n   */\n  docsCommit?: string;\n  /** The report that answered this service's scenario claims, when `--results` did. */\n  report?: ConsumedReport;\n  /** The report that answered this service's api.exposes claims, when `--contract-results` did. */\n  contractReport?: ConsumedContractReport;\n}\n\nexport interface Verification {\n  /** Federated, partial records use schema 2. Absent means the original all-at-once format. */\n  schema?: 2;\n  feature: string;\n  /** The day the answers were recorded. */\n  recorded: string;\n  /** The checklist digest they answer — how a later reader spots a record gone stale. */\n  checklist: string;\n  summary: { claims: number; confirmed: number; unconfirmed: number; unanswered?: number };\n  claims: RecordedClaim[];\n  /** The all-at-once form's consumed report; the federated form files it per attestation. */\n  report?: ConsumedReport;\n  /** The all-at-once form's consumed contract report — filed per attestation when federated. */\n  contractReport?: ConsumedContractReport;\n  attestations?: ServiceAttestation[];\n}\n\n/**\n * Anything carrying an answer, whichever surface holds it: a recorded claim, or\n * the read view's per-claim status. Structural on purpose — the same questions\n * are asked of both, and neither should have to convert into the other to be\n * counted.\n */\nexport interface AnsweredClaim {\n  id: string;\n  kind: string;\n  verdict: string;\n  answered_by?: string;\n}\n\n/**\n * The confirmed `scenario.tested` claims that no test run answered.\n *\n * A scenario claim's whole premise is that a run answers it — its digest IS the\n * tag `loam gherkin` stamps, and `--results` matches the two mechanically. An\n * agent may still answer one, because a legacy service has no runnable suite\n * for months and that fleet is who loam is for; but the answer is somebody's\n * word about a test, and it must not read as the run. A record written before\n * `--results` existed carries no `answered_by` at all: unknown counts as agent\n * here, because the alternative is to credit a run nobody can point at.\n */\nexport function attestedClaims(claims: readonly AnsweredClaim[]): string[] {\n  return claims\n    .filter((c) => c.kind === \"scenario.tested\" && c.verdict === \"confirmed\" && c.answered_by !== \"runner\")\n    .map((c) => c.id);\n}\n\n/**\n * Of the CONFIRMED answers, one count per `answered_by` value. Anything that is not a runner spelling\n * counts as the agent's word — a record too old to carry the field says nothing, and crediting a run\n * nobody can point at is the error that matters. Never derive it by subtracting {@link attestedClaims}\n * from the confirmed total: that count is `scenario.tested` ALONE, so the fleet scorecard filed every\n * other kind an agent confirmed under a runner that never ran.\n */\nexport function confirmedProvenance(claims: readonly AnsweredClaim[]): Record<AnsweredBy, number> {\n  const done = claims.filter((c) => c.verdict === \"confirmed\");\n  const by = (who: AnsweredBy): number => done.filter((c) => c.answered_by === who).length;\n  const ran = { runner: by(\"runner\"), \"external-runner\": by(\"external-runner\") };\n  return { ...ran, agent: done.length - ran.runner - ran[\"external-runner\"] };\n}\n\n/** How a set of answers counts up — recounted from the answers, never read off a `summary`. */\nexport interface RecordTally {\n  /** Questions asked: answered, plus the ones a federated record leaves for other repos. */\n  claims: number;\n  confirmed: number;\n  unconfirmed: number;\n  unanswered: number;\n  /** Of the confirmed, the scenario claims on an agent's word. See {@link attestedClaims}. */\n  attested: number;\n}\n\n/**\n * `unanswered` is the count the answers themselves cannot show: a federated\n * record holds only what somebody answered, and the claims still owed to other\n * repositories exist on the checklist, not in `claims[]`. Read views that carry\n * an `unanswered` status inside the list pass 0 and are counted in place.\n */\nexport function tallyAnswers(claims: readonly AnsweredClaim[], unanswered = 0): RecordTally {\n  const of = (verdict: string): number => claims.filter((c) => c.verdict === verdict).length;\n  return {\n    claims: claims.length + unanswered,\n    confirmed: of(\"confirmed\"),\n    unconfirmed: of(\"unconfirmed\"),\n    unanswered: of(\"unanswered\") + unanswered,\n    attested: attestedClaims(claims).length,\n  };\n}\n\n/**\n * The record's own answers, recounted. Never `v.summary`: the summary is what\n * whoever wrote the file said the answers add up to, and every reader that\n * believed it reported a record full of unconfirmed claims as fully confirmed.\n * `readVerificationState` refuses a record whose summary contradicts this, so a\n * caller holding a Verification may use either — and should use this one.\n */\nexport function tallyRecord(v: Verification): RecordTally {\n  return tallyAnswers(v.claims, v.summary.unanswered ?? 0);\n}\n\n/**\n * Three states, because two were a lie. `verified` is the strong claim — every\n * question answered, every answer confirmed, and every scenario answered by a\n * digest-matched green run. `attested` is the same completeness resting, for at\n * least one scenario, on an agent's word. `unverified` is everything else:\n * nothing recorded, a record gone stale, a claim unanswered or unconfirmed, or\n * a checklist that asks nothing at all.\n */\nexport const VERIFICATION_VERDICTS = [\"verified\", \"attested\", \"unverified\"] as const;\nexport type VerificationVerdict = (typeof VERIFICATION_VERDICTS)[number];\n\nexport function verificationVerdict(t: RecordTally, stale = false): VerificationVerdict {\n  if (stale || t.claims === 0 || t.confirmed !== t.claims) return \"unverified\";\n  return t.attested > 0 ? \"attested\" : \"verified\";\n}\n\n/** A finding a verify surface reports about a record. Stable code, prose that may change. */\nexport interface VerifyNotice {\n  code: string;\n  severity: \"warn\";\n  message: string;\n  /** The claims it is about, when it is about claims. */\n  claims?: string[];\n}\n\n/**\n * The one notice `verify`, `list` and `status` all show: this record's scenario\n * claims were confirmed without a run.\n *\n * It is a warning and it gates nothing — verify has never gated, and a service\n * with no suite yet has to be able to ship. What it must never do is read the\n * same as a green run.\n */\nexport function attestedNotice(claims: readonly AnsweredClaim[], feature: string): VerifyNotice | null {\n  const ids = attestedClaims(claims);\n  if (ids.length === 0) return null;\n  return {\n    code: \"verify.scenario-attested\",\n    severity: \"warn\",\n    message:\n      `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(\", \")}. ` +\n      `Answer them mechanically once the suite runs: \\`loam verify ${feature} --results <cucumber.json>\\`.`,\n    claims: ids,\n  };\n}\n\n/**\n * The one-line honesty summary of a record that leaves claims open: partial is\n * not a clean result, and the counts alone did not say so — `summary` carries\n * them on every surface, and a reader skimming for the ⚠ lines shipped a\n * half-answered record as done anyway. Null when nothing is open, and the\n * callers fire it only when a record EXISTS: a feature with no record already\n * says \"Not verified\", and calling that \"not a clean result\" would conflate\n * not-started with partial. A pure-attested record (all confirmed, some on an\n * agent's word) never reaches the message either — its counts are closed, and\n * `attestedNotice` above owns that honesty; two notices about one fact is the\n * double-reporting this file's notices exist to prevent.\n */\nexport function openClaimsNotice(tally: RecordTally, feature: string): VerifyNotice | null {\n  const open = tally.unconfirmed + tally.unanswered;\n  if (open === 0) return null;\n  return {\n    code: \"verify.claims-open\",\n    severity: \"warn\",\n    message:\n      `not a clean result: of ${tally.claims} claim(s), ${tally.confirmed} confirmed` +\n      (tally.attested > 0 ? ` (${tally.attested} on an agent's word)` : \"\") +\n      `, ${tally.unconfirmed} unconfirmed, ${tally.unanswered} unanswered — ` +\n      `treat ${feature} as unverified until every claim is answered and confirmed.`,\n  };\n}\n\n/**\n * Where the record lives: inside the feature, so `archive` carries it into\n * `features/archive/` with everything else and a reviewer finds it next to the\n * delta it is about. YAML rather than frontmatter or JSON — it is data, it has\n * to survive without loam, and one claim per block is a diff a person can read.\n */\nexport function verificationPath(featureDir: string): string {\n  return join(featureDir, \"verification.yaml\");\n}\n\n"]}
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/core/verify/record.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What gets written down, and how a set of answers counts up to a verdict.\n *\n * The shapes and the arithmetic are one module because they are one claim about\n * the same numbers: `tallyRecord` recounts from the answers rather than reading\n * the `summary` field back, so a record whose header disagrees with its own\n * claims is caught rather than believed. A separate counter would be a second\n * opinion, which is precisely what this file exists to prevent.\n *\n * `verified` is reserved for a checklist whose scenarios a RUN answered.\n * Where an agent answered one instead — a legacy service whose suite is months\n * away, which is the fleet loam exists for — the record marks it attested, and\n * `attestedNotice` says so on every surface that reads the record.\n */\nimport { type ClaimKind } from \"./claims/identity.js\";\nimport { ANSWERED_BY, type AnsweredBy, type Verdict } from \"./answers.js\";\nimport { type EvidencePin } from \"./pins/pin.js\";\n\nexport interface RecordedClaim {\n  id: string;\n  kind: ClaimKind;\n  /** Present in federated records; omitted by legacy records written before schema 2. */\n  subject?: string;\n  claim: string;\n  verdict: Verdict;\n  /** Who answered — absent only in records written before `--results` existed. */\n  answered_by?: AnsweredBy;\n  evidence: string[];\n  note?: string;\n  /**\n   * One pin per file:line citation of a federated agent-confirmed answer: the\n   * cited file's normalized sha256 at the attested commit, the cited line's\n   * text, and the claim's token where it asserts one. A pin records which\n   * text was cited at that commit so `loam validate`, run later in the\n   * service's own repo, can convict drift; it does not prove the claim true —\n   * a faithful pin of the wrong line is still a wrong answer. Absent on\n   * runner-answered claims (their evidence names a report entry, not a file)\n   * and on every record written before pins existed.\n   */\n  evidence_pins?: EvidencePin[];\n}\n\n/**\n * The test report a `--results` run consumed.\n *\n * Nothing can prove a JSON file came from executing a particular commit — a\n * report is bytes, and bytes are writable. What loam can do is stop leaving the\n * question open: it records exactly which file it read (inside the attesting\n * repository, resolved by the same path rules as evidence), the sha256 of the\n * bytes it read, the file's own mtime and how many digest-tagged scenarios it\n * carried. A reviewer holding the repository can tell whether this is that\n * file; before this, `answered_by: runner` named nothing at all.\n */\nexport interface ConsumedReport {\n  /** As it was passed to `--results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read, so `shasum -a 256 <path>` answers the question. */\n  digest: string;\n  /** ISO-8601 mtime of the report file — when the run that wrote it finished. */\n  mtime: string;\n  /** How many digest-tagged scenarios the report carried. */\n  scenarios: number;\n}\n\n/**\n * The contract-test report a `--contract-results` run consumed — the same pin,\n * the same honesty, for the report that answers `api.exposes` claims by\n * operationId. Nothing here proves the file came from executing the attested\n * commit either; the digest identifies WHICH file was consumed, and the\n * federated form binds a committed one to the commit exactly as `report:` is.\n */\nexport interface ConsumedContractReport {\n  /** As it was passed to `--contract-results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read. */\n  digest: string;\n  /** ISO-8601 mtime of the report file. */\n  mtime: string;\n  /** How many distinct operationIds the report's entries name. */\n  operations: number;\n  /**\n   * Which accepted shape the report was read as — `\"generic\"` for the\n   * documented `loamContractReport: 1` shape, the only one v1 accepts. loam\n   * always writes it, but the READ shape keeps it optional: no reader\n   * dereferences it, so a hand-written pin without it stays a readable record\n   * (`isConsumedContractReport` in ./read/shape.ts says why) — and it is a string\n   * rather than a closed union so a format a NEWER loam learned to read stays\n   * readable here too.\n   */\n  format?: string;\n}\n\n/**\n * Both mechanical answer sheets one recording run may consume, together\n * because they are validated together (`validateServiceEvidence` binds each to\n * the attested commit) and filed together (on the record all-at-once, inside\n * the service's attestation federated). Two loose optional parameters made the\n * inconsistent pair representable at every call site.\n */\nexport interface ConsumedReports {\n  results?: ConsumedReport;\n  contract?: ConsumedContractReport;\n}\n\n/** A service repository's commit-bound contribution to a federated record. */\nexport interface ServiceAttestation {\n  service: string;\n  commit: string;\n  recorded: string;\n  /** Claim ids this commit answered. Kept explicit so stale answers can be pruned safely. */\n  claims: string[];\n  /**\n   * The checklist digest THIS attestation answered.\n   *\n   * The record carries one `checklist` for the whole file, which is the right\n   * field for the all-at-once form and an incomplete one for a federated\n   * record: two services attesting a week apart across a changed delta write\n   * the same top-level digest, and nothing in the file can say they answered\n   * different questions. With this, `verify.checklist-forked` can.\n   *\n   * Optional forever. An attestation written before this field existed carries\n   * no claim about which checklist it answered, and inventing one from the\n   * record-level digest would be asserting exactly the thing that cannot be\n   * known — the `evidence.unpinned` precedent, one axis over.\n   */\n  checklist?: string;\n  /**\n   * The docs-repo commit the checklist was computed from, when the docs repo is\n   * a git repository with a committed HEAD.\n   *\n   * `commit` pins the SERVICE repo — the code the evidence points into.\n   * Nothing pinned the side the QUESTION came from, so a reader could not tell\n   * a re-record against an unchanged feature from one against a rewritten\n   * delta. Absent whenever git cannot answer: a docs repo is not required to be\n   * a git checkout, and a missing pin is not a defect.\n   */\n  docsCommit?: string;\n  /** The report that answered this service's scenario claims, when `--results` did. */\n  report?: ConsumedReport;\n  /** The report that answered this service's api.exposes claims, when `--contract-results` did. */\n  contractReport?: ConsumedContractReport;\n}\n\nexport interface Verification {\n  /** Federated, partial records use schema 2. Absent means the original all-at-once format. */\n  schema?: 2;\n  feature: string;\n  /** The day the answers were recorded. */\n  recorded: string;\n  /** The checklist digest they answer — how a later reader spots a record gone stale. */\n  checklist: string;\n  summary: { claims: number; confirmed: number; unconfirmed: number; unanswered?: number };\n  claims: RecordedClaim[];\n  /** The all-at-once form's consumed report; the federated form files it per attestation. */\n  report?: ConsumedReport;\n  /** The all-at-once form's consumed contract report — filed per attestation when federated. */\n  contractReport?: ConsumedContractReport;\n  attestations?: ServiceAttestation[];\n}\n\n/**\n * Anything carrying an answer, whichever surface holds it: a recorded claim, or\n * the read view's per-claim status. Structural on purpose — the same questions\n * are asked of both, and neither should have to convert into the other to be\n * counted.\n */\nexport interface AnsweredClaim {\n  id: string;\n  kind: string;\n  verdict: string;\n  answered_by?: string;\n}\n\n/**\n * The confirmed `scenario.tested` claims that no test run answered.\n *\n * A scenario claim's whole premise is that a run answers it — its digest IS the\n * tag `loam gherkin` stamps, and `--results` matches the two mechanically. An\n * agent may still answer one, because a legacy service has no runnable suite\n * for months and that fleet is who loam is for; but the answer is somebody's\n * word about a test, and it must not read as the run. A record written before\n * `--results` existed carries no `answered_by` at all: unknown counts as agent\n * here, because the alternative is to credit a run nobody can point at.\n */\nexport function attestedClaims(claims: readonly AnsweredClaim[]): string[] {\n  return claims\n    .filter((c) => c.kind === \"scenario.tested\" && c.verdict === \"confirmed\" && c.answered_by !== \"runner\")\n    .map((c) => c.id);\n}\n\n/**\n * Of the CONFIRMED answers, one count per `answered_by` value. Anything that is not a runner spelling\n * counts as the agent's word — a record too old to carry the field says nothing, and crediting a run\n * nobody can point at is the error that matters. Never derive it by subtracting {@link attestedClaims}\n * from the confirmed total: that count is `scenario.tested` ALONE, so the fleet scorecard filed every\n * other kind an agent confirmed under a runner that never ran.\n */\nexport function confirmedProvenance(claims: readonly AnsweredClaim[]): Record<AnsweredBy, number> {\n  const done = claims.filter((c) => c.verdict === \"confirmed\");\n  const by = (who: AnsweredBy): number => done.filter((c) => c.answered_by === who).length;\n  const ran = { runner: by(\"runner\"), \"external-runner\": by(\"external-runner\") };\n  return { ...ran, agent: done.length - ran.runner - ran[\"external-runner\"] };\n}\n\n/**\n * The confirmed split as the per-feature human views print it — `13 runner · 6 agent`, empty\n * buckets left out. `loam status <FEAT>` and `list`'s verification column print it beside the\n * verdict because the verdict turns on the scenario claims alone ({@link verificationVerdict}), so\n * `verified 19/19 confirmed` read as nineteen runs over a record where six were an agent's word —\n * the split `--json` and the fleet scorecard already carried. The scorecard keeps all three keys\n * for its stable-shape reason (validate's scorecard/print.ts); a one-feature line has no shape to\n * keep, and a column of zeros is width the reader pays for nothing.\n */\nexport function answeredSplit(answered: Record<AnsweredBy, number>): string {\n  return ANSWERED_BY.filter((who) => answered[who] > 0)\n    .map((who) => `${answered[who]} ${who}`)\n    .join(\" · \");\n}\n\n/** How a set of answers counts up — recounted from the answers, never read off a `summary`. */\nexport interface RecordTally {\n  /** Questions asked: answered, plus the ones a federated record leaves for other repos. */\n  claims: number;\n  confirmed: number;\n  unconfirmed: number;\n  unanswered: number;\n  /** Of the confirmed, the scenario claims on an agent's word. See {@link attestedClaims}. */\n  attested: number;\n}\n\n/**\n * `unanswered` is the count the answers themselves cannot show: a federated\n * record holds only what somebody answered, and the claims still owed to other\n * repositories exist on the checklist, not in `claims[]`. Read views that carry\n * an `unanswered` status inside the list pass 0 and are counted in place.\n */\nexport function tallyAnswers(claims: readonly AnsweredClaim[], unanswered = 0): RecordTally {\n  const of = (verdict: string): number => claims.filter((c) => c.verdict === verdict).length;\n  return {\n    claims: claims.length + unanswered,\n    confirmed: of(\"confirmed\"),\n    unconfirmed: of(\"unconfirmed\"),\n    unanswered: of(\"unanswered\") + unanswered,\n    attested: attestedClaims(claims).length,\n  };\n}\n\n/**\n * The record's own answers, recounted. Never `v.summary`: the summary is what\n * whoever wrote the file said the answers add up to, and every reader that\n * believed it reported a record full of unconfirmed claims as fully confirmed.\n * `readVerificationState` refuses a record whose summary contradicts this, so a\n * caller holding a Verification may use either — and should use this one.\n */\nexport function tallyRecord(v: Verification): RecordTally {\n  return tallyAnswers(v.claims, v.summary.unanswered ?? 0);\n}\n\n/**\n * The recorded rows that may answer a checklist, keyed by claim id — the one\n * spelling of the attestation-scoping rule. A legacy (no `schema`) record is\n * all-at-once, so every row answers. In a federated record a row only counts\n * where an attestation from the claim's OWN subject (per `claims`, the live\n * checklist) listed it, so one repository cannot answer another's claims by\n * writing their ids into its own attestation. `verify`'s read view and `loam\n * tasks` each used to carry a copy, the second labelled \"a deliberate mirror\"\n * because core could not import the command module the first lived in; the\n * rule lives here now and both import it.\n */\nexport function countedAnswers(\n  claims: readonly { id: string; subject: string }[],\n  recorded: Verification,\n): Map<string, RecordedClaim> {\n  const subjects = new Map(claims.map((claim) => [claim.id, claim.subject]));\n  const attested =\n    recorded.schema !== 2\n      ? null\n      : new Set(\n          (recorded.attestations ?? []).flatMap((a) => a.claims.filter((id) => subjects.get(id) === a.service)),\n        );\n  return new Map(recorded.claims.filter((c) => attested === null || attested.has(c.id)).map((c) => [c.id, c]));\n}\n\n/**\n * Three states, because two were a lie. `verified` is the strong claim — every\n * question answered, every answer confirmed, and every scenario answered by a\n * digest-matched green run. `attested` is the same completeness resting, for at\n * least one scenario, on an agent's word. `unverified` is everything else:\n * nothing recorded, a record gone stale, a claim unanswered or unconfirmed, or\n * a checklist that asks nothing at all.\n */\nexport const VERIFICATION_VERDICTS = [\"verified\", \"attested\", \"unverified\"] as const;\nexport type VerificationVerdict = (typeof VERIFICATION_VERDICTS)[number];\n\nexport function verificationVerdict(t: RecordTally, stale = false): VerificationVerdict {\n  if (stale || t.claims === 0 || t.confirmed !== t.claims) return \"unverified\";\n  return t.attested > 0 ? \"attested\" : \"verified\";\n}\n\n/** A finding a verify surface reports about a record. Stable code, prose that may change. */\nexport interface VerifyNotice {\n  code: string;\n  severity: \"warn\";\n  message: string;\n  /** The claims it is about, when it is about claims. */\n  claims?: string[];\n}\n\n/**\n * The one notice `verify`, `list` and `status` all show: this record's scenario\n * claims were confirmed without a run.\n *\n * It is a warning and it gates nothing — verify has never gated, and a service\n * with no suite yet has to be able to ship. What it must never do is read the\n * same as a green run.\n */\nexport function attestedNotice(claims: readonly AnsweredClaim[], feature: string): VerifyNotice | null {\n  const ids = attestedClaims(claims);\n  if (ids.length === 0) return null;\n  return {\n    code: \"verify.scenario-attested\",\n    severity: \"warn\",\n    message:\n      `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(\", \")}. ` +\n      `Answer them mechanically once the suite runs: \\`loam verify ${feature} --results <report.json>\\` — ` +\n      \"a cucumber JSON report, or loam's runner-neutral loamScenarioReport shape for any other runner.\",\n    claims: ids,\n  };\n}\n\n/**\n * The one-line honesty summary of a record that leaves claims open: partial is\n * not a clean result, and the counts alone did not say so — `summary` carries\n * them on every surface, and a reader skimming for the ⚠ lines shipped a\n * half-answered record as done anyway. Null when nothing is open, and the\n * callers fire it only when a record EXISTS: a feature with no record already\n * says \"Not verified\", and calling that \"not a clean result\" would conflate\n * not-started with partial. A pure-attested record (all confirmed, some on an\n * agent's word) never reaches the message either — its counts are closed, and\n * `attestedNotice` above owns that honesty; two notices about one fact is the\n * double-reporting this file's notices exist to prevent.\n */\nexport function openClaimsNotice(tally: RecordTally, feature: string): VerifyNotice | null {\n  const open = tally.unconfirmed + tally.unanswered;\n  if (open === 0) return null;\n  return {\n    code: \"verify.claims-open\",\n    severity: \"warn\",\n    message:\n      `not a clean result: of ${tally.claims} claim(s), ${tally.confirmed} confirmed` +\n      (tally.attested > 0 ? ` (${tally.attested} on an agent's word)` : \"\") +\n      `, ${tally.unconfirmed} unconfirmed, ${tally.unanswered} unanswered — ` +\n      `treat ${feature} as unverified until every claim is answered and confirmed.`,\n  };\n}\n"]}

package/dist/core/verify/store/commit.js

@@ -1,6 +1,9 @@
 /**
  * The verification record's commit: staged beside the target, compared against
- * the byte pre-image the merge consumed, swapped in by one rename(2).
+ * the byte pre-image the merge consumed, swapped in by one rename(2) per file.
+ * A write is one file, or two: a service's own `verification/<svc>.yaml`, and
+ * — once nothing in it counts any more — the removal of the one-file record it
+ * supersedes. Never another service's file: those are not this run's to touch.
  *
  * The record used to go down as a plain `writeFile`, which cost three ways at
  * once: two `--record` runs read the same pre-image and the last writer
@@ -21,45 +24,51 @@ import { message, rollbackMessage, rollbackStaged, stageWrites, StagingRaceError
 import { repoPath } from "../../envelope/json.js";
 import {} from "../../staging/writes.js";
 import { renderVerification } from "./render.js";
-import { verificationPath } from "../record.js";
+import {} from "../record.js";
 /**
- * `preImage` is the exact bytes the caller's merge was computed from, or null
- * when the record was absent at the authoritative read — in which case the
- * commit may only CREATE (link(2) refuses a file that appeared since), never
- * replace one it has not read.
+ * Writes land in the order given, so a caller puts what must survive a kill
+ * FIRST: a service's own file before the one-file record it supersedes, so a
+ * process killed between the two renames leaves a record that still reads
+ * whole — the new file counted, the old one superseded by it — rather than one
+ * with the old file gone and nothing in its place.
  */
-export async function commitVerification(featureDir, v, preImage, docsDir) {
-    const path = verificationPath(featureDir);
-    const display = repoPath(docsDir, path);
-    const write = preImage === null ? { path, content: renderVerification(v), exclusive: true } : { path, content: renderVerification(v) };
+export async function commitVerification(writes, docsDir) {
+    const planned = writes.map((w) => w.record === null
+        ? { path: w.path, content: null }
+        : w.preImage === null
+            ? { path: w.path, content: renderVerification(w.record), exclusive: true }
+            : { path: w.path, content: renderVerification(w.record) });
     // Staging touches the filesystem — a read-only feature directory, a full
     // disk, a pre-image that will not read. None of that is a bug in loam, and
     // letting it escape as `internal` sends the reader looking for one (archive
     // draws the same line around its own `stageWrites`). Nothing was written.
     let staged;
     try {
-        staged = await stageWrites([write]);
+        staged = await stageWrites(planned);
     }
     catch (err) {
         return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
     }
-    // Joined by path, not by index — vouch's rule, for vouch's reason: one entry
-    // per planned write in order is true today and promised nowhere, and a
-    // compare-and-set over the wrong pair would vouch for bytes the merge never
-    // saw. A missing entry fails closed as a merge that never happened.
-    const s = staged.find((x) => x.write.path === path);
-    if (s === undefined) {
-        await rollbackStaged(staged);
-        return { ok: false, code: "merge-failed", message: `staging returned no entry for ${display} — nothing was recorded` };
-    }
-    // The compare the read promised: the file as staging found it must be the
-    // file the merge consumed. `swapStaged` re-checks against ITS read just
-    // before the rename, so together the two compares cover the whole window
-    // from the authoritative read to the swap.
-    const edited = preImage === null ? s.before !== null : s.before === null || !s.before.equals(preImage);
-    if (edited) {
-        await rollbackStaged(staged);
-        return { ok: false, code: "record-raced", message: racedMessage(display) };
+    for (const w of writes) {
+        const display = repoPath(docsDir, w.path);
+        // Joined by path, not by index — vouch's rule, for vouch's reason: one
+        // entry per planned write in order is true today and promised nowhere, and
+        // a compare-and-set over the wrong pair would vouch for bytes the merge
+        // never saw. A missing entry fails closed as a merge that never happened.
+        const s = staged.find((x) => x.write.path === w.path);
+        if (s === undefined) {
+            await rollbackStaged(staged);
+            return { ok: false, code: "merge-failed", message: `staging returned no entry for ${display} — nothing was recorded` };
+        }
+        // The compare the read promised: the file as staging found it must be the
+        // file the merge consumed. `swapStaged` re-checks against ITS read just
+        // before the rename, so together the two compares cover the whole window
+        // from the authoritative read to the swap.
+        const edited = w.preImage === null ? s.before !== null : s.before === null || !s.before.equals(w.preImage);
+        if (edited) {
+            await rollbackStaged(staged);
+            return { ok: false, code: "record-raced", message: racedMessage(display) };
+        }
     }
     try {
         await swapStaged(staged);
@@ -76,11 +85,12 @@ export async function commitVerification(featureDir, v, preImage, docsDir) {
         // EEXIST is the exclusive create losing its race — same fact as the CAS
         // refusal, discovered by link(2) instead of by the compare.
         if (err instanceof StagingRaceError || err.code === "EEXIST") {
-            return { ok: false, code: "record-raced", message: racedMessage(display) };
+            const path = err instanceof StagingRaceError ? err.path : (writes.find((w) => w.preImage === null)?.path ?? writes[0].path);
+            return { ok: false, code: "record-raced", message: racedMessage(repoPath(docsDir, path)) };
         }
         return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
     }
-    return { ok: true, path };
+    return { ok: true };
 }
 function racedMessage(display) {
     return (`${display} changed while this record was being written — another writer or an editor landed between the read and the write. ` +