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

package/dist/commands/vouch/pack/sections.js.map

@@ -1 +1 @@
-{"version":3,"file":"sections.js","sourceRoot":"","sources":["../../../../src/commands/vouch/pack/sections.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The reading pack's section-level derivations: pure text in, lists of\n * headings out. Three of them, and the last two are why a sampled vouch does\n * not quietly weaken this command —\n *\n *  - `sectionDelta`, the heading summary printed beside the raw git diff and\n *    the source of the \"already covered\" list;\n *  - `forwardSample`, what the next `--sample <n>` vouch will read;\n *  - `priorScope`, what the last sampled vouch actually did read, so the\n *    covered list cannot count sections nobody opened.\n *\n * It lives in the vouch command package rather than `core/document` because\n * that package sits at its five-file limit and this command package already\n * holds vouch's non-printing logic (`../vet/verify.ts` precedent); the one\n * structural question — what is an H2 heading — is still answered by\n * `core/document/parse.ts`'s `sectionHeadings`, fence- and BOM-aware, so this\n * module can never disagree with the rest of loam about whether a `## ` line\n * inside a code fence is structure.\n */\nimport { rawBody, type Frontmatter } from \"../../../core/document/frontmatter.js\";\nimport { sectionHeadings } from \"../../../core/document/parse.js\";\nimport { splitSections } from \"../../../core/provenance/sample/sections.js\";\nimport { planSample, readVouchScope, sampledSections, scopeText, type VouchScope } from \"../../../core/provenance/sample/scope.js\";\nimport { contentDigest } from \"../../../core/provenance/stamp.js\";\n\n/** How the delta names the text above the first H2 — a section with no heading to call it by. */\nconst PREAMBLE_LABEL = \"(before the first heading)\";\n\n/** The four verdicts, each a list of H2 heading lines as the document spells them. */\nexport interface SectionDelta {\n  /** Present in both bodies with different text — in the new body's order. */\n  changed: string[];\n  /** Present only in the new body, in its order. */\n  added: string[];\n  /** Present only in the old body, in its order. */\n  removed: string[];\n  /** Present in both with identical text — the \"already covered\" list. */\n  unchanged: string[];\n}\n\n/**\n * CRLF/CR to LF, the `core/verify/pins/pin.ts` recipe: the old body comes out\n * of a git blob (LF) while the new one comes off a checkout that may be CRLF,\n * and a comparison that let the line endings vote would report every section\n * changed on exactly the machines whose config differs from the repo's.\n * A pure line-ending change is invisible here — the same cost the pins\n * accept, and for a reading list it is the right one: there is nothing to\n * re-read in a CR.\n */\nfunction normalized(text: string): string {\n  return text.replace(/\\r\\n|\\r/g, \"\\n\");\n}\n\n/**\n * One body as heading -> section text. The heading LINE is the key and is not\n * part of the value, so a section whose only change is its own heading reads\n * as removed+added — which is what a reader must do about it: find it under\n * its new name. A duplicated heading concatenates its sections under the one\n * key rather than letting the last occurrence shadow the rest: the compare\n * then sees all of the text, so an edit under either twin still reads as\n * changed. Text before the first heading files under PREAMBLE_LABEL when any\n * of it is more than whitespace.\n */\nfunction sectionMap(body: string): Map<string, string> {\n  const text = normalized(body);\n  const lines = text.split(\"\\n\");\n  const headings = sectionHeadings(text);\n  const map = new Map<string, string>();\n  const file = (key: string, segment: string): void => {\n    map.set(key, map.has(key) ? `${map.get(key)}\\n${segment}` : segment);\n  };\n  const firstHeadingLine = headings[0]?.line ?? lines.length + 1;\n  const preamble = lines.slice(0, firstHeadingLine - 1).join(\"\\n\");\n  if (preamble.trim() !== \"\") map.set(PREAMBLE_LABEL, preamble);\n  headings.forEach((heading, i) => {\n    const end = headings[i + 1]?.line ?? lines.length + 1;\n    file(heading.text, lines.slice(heading.line, end - 1).join(\"\\n\"));\n  });\n  return map;\n}\n\n/** The forward-looking sample: what a `--sample <n>` vouch of this file would cover. */\nexport interface PackSample {\n  /** The seed the stamp will carry, derivable now because the body it hashes will not change. */\n  seed: string;\n  /** Every section the body has. */\n  of: number;\n  /** The sections to read, in document order. Headings only — the pack does not renumber lines. */\n  headings: string[];\n  /** True when `<n>` reached every section: the read is the whole file, and no scope is stamped. */\n  covers: boolean;\n}\n\n/**\n * What `loam vouch --sample <n>` would read of this file — computed through\n * the same `planSample` the stamp uses, so a pack and the vouch that follows\n * it cannot prescribe different samples of one document. Both digests are the\n * ones the stamp will carry: `contentDigest` survives stamping because the\n * body does, and the sources digest is the vetting's own.\n */\nexport function forwardSample(doc: {\n  service: string;\n  /** The file as read, frontmatter included — the same string the stamp is applied to. */\n  raw: string;\n  sourcesDigest: string;\n  n: number;\n}): PackSample {\n  const planned = planSample({\n    service: doc.service,\n    contentDigest: contentDigest(doc.raw),\n    sourcesDigest: doc.sourcesDigest,\n    body: rawBody(doc.raw),\n    n: doc.n,\n  });\n  return {\n    seed: planned.seed,\n    of: planned.of,\n    headings: planned.picked.map((section) => section.heading),\n    covers: planned.picked.length >= planned.of,\n  };\n}\n\n/**\n * What the LAST vouch actually covered, when it was a sampled one.\n *\n * This is the pack's answer to the one way sampling could quietly undo the\n * whole point of it: the \"already covered\" list licenses a person to NOT\n * re-read a section, on the strength of somebody having read it before. After\n * a sampled vouch that strength is not there — most of those sections were\n * never read by anyone — so the licence has to be withdrawn, and withdrawn\n * with the detail that makes it actionable rather than as a blanket warning.\n *\n * The detail is recomputable because the stamp records the seed: run the same\n * pick over the body that vouch was taken over and you get back the exact\n * list that person was shown. `read` is that list; `unread` is every other\n * section of that body — text that has now survived a vouch without anybody\n * looking at it, which is precisely what a re-voucher most needs to know.\n *\n * Three things come back null-but-still-sampled, and all three fail the same\n * way, closed: a scope that does not decode (mangled by hand), no vouched\n * body to recompute over (the document has changed since the stamp, so the\n * pick cannot be reproduced), and a body whose section count no longer\n * matches what the scope claims. In each case the pack reports the scope and\n * refuses to name a covered set — never the reverse.\n */\nexport interface PackVouchScope {\n  /** The `vouch_scope` value as a reader is shown it — verbatim where it is text at all. */\n  stamped: string;\n  /** Decoded, or null when the field is not one this loam wrote. */\n  scope: VouchScope | null;\n  /** The headings that vouch read, in document order — null when they cannot be recomputed. */\n  read: string[] | null;\n  /** The headings it did not read: present at that stamp, and never read by anyone. */\n  unread: string[] | null;\n}\n\nexport function priorScope(fm: Frontmatter, vouchedBody: string | null): PackVouchScope | null {\n  // One reader, `readVouchScope`, decides what \"sampled\" means — so the pack\n  // cannot be the surface that quietly grades a mangled scope as a full vouch\n  // while `loam validate` grades it sampled.\n  const stamp = readVouchScope(fm);\n  if (stamp.kind === \"none\") return null;\n  const stamped = scopeText(fm) ?? \"\";\n  const scope = stamp.kind === \"sampled\" ? stamp.scope : null;\n  const blind: PackVouchScope = { stamped, scope, read: null, unread: null };\n  if (scope === null || vouchedBody === null) return blind;\n  const picked = sampledSections(vouchedBody, scope);\n  if (picked === null) return blind;\n  // Partitioned by LINE, not by heading text: a body with two `## Notes`\n  // sections has two units, and matching on the text would report both as\n  // read when one was picked — turning a section nobody opened into a covered\n  // one, which is the exact misreading this function exists to prevent.\n  const read = new Set(picked.map((section) => section.line));\n  return {\n    stamped,\n    scope,\n    read: picked.map((section) => section.heading),\n    unread: splitSections(vouchedBody)\n      .filter((section) => !read.has(section.line))\n      .map((section) => section.heading),\n  };\n}\n\n/**\n * Compare two bodies section by section. Exact text per heading after line\n * endings are normalized — no reflow tolerance, because \"unchanged\" here\n * licenses a person to NOT re-read a section, and the only claim safe to make\n * at that stakes is byte equality.\n */\nexport function sectionDelta(oldBody: string, newBody: string): SectionDelta {\n  const before = sectionMap(oldBody);\n  const after = sectionMap(newBody);\n  const changed: string[] = [];\n  const added: string[] = [];\n  const unchanged: string[] = [];\n  for (const [heading, text] of after) {\n    const prior = before.get(heading);\n    if (prior === undefined) added.push(heading);\n    else if (prior === text) unchanged.push(heading);\n    else changed.push(heading);\n  }\n  const removed = [...before.keys()].filter((heading) => !after.has(heading));\n  return { changed, added, removed, unchanged };\n}\n"]}
+{"version":3,"file":"sections.js","sourceRoot":"","sources":["../../../../src/commands/vouch/pack/sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,aAAa,EAAE,OAAO,EAAoB,MAAM,uCAAuC,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,6CAA6C,CAAC;AAC5E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAmB,MAAM,0CAA0C,CAAC;AAEnI,iGAAiG;AACjG,MAAM,cAAc,GAAG,4BAA4B,CAAC;AAcpD;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,OAAe,EAAQ,EAAE;QAClD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACvE,CAAC,CAAC;IACF,MAAM,gBAAgB,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC9D,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAM7B;IACC,MAAM,OAAO,GAAG,UAAU,CAAC;QACzB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,aAAa,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC;QACrC,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QACtB,CAAC,EAAE,GAAG,CAAC,CAAC;KACT,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1D,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,EAAE;KAC5C,CAAC;AACJ,CAAC;AAoCD,MAAM,UAAU,UAAU,CAAC,EAAe,EAAE,WAA0B;IACpE,2EAA2E;IAC3E,4EAA4E;IAC5E,2CAA2C;IAC3C,MAAM,KAAK,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,MAAM,KAAK,GAAmB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3E,IAAI,KAAK,KAAK,IAAI,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACzD,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClC,uEAAuE;IACvE,wEAAwE;IACxE,4EAA4E;IAC5E,sEAAsE;IACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,OAAO;QACP,KAAK;QACL,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;QAC9C,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC;aAC/B,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;aAC5C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;KACrC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,OAAe;IAC3D,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;aACxC,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;YAC5C,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAChD,CAAC","sourcesContent":["/**\n * The reading pack's section-level derivations: pure text in, lists of\n * headings out. Three of them, and the last two are why a sampled vouch does\n * not quietly weaken this command —\n *\n *  - `sectionDelta`, the heading summary printed beside the raw git diff and\n *    the source of the \"already covered\" list;\n *  - `forwardSample`, what the next `--sample <n>` vouch will read;\n *  - `priorScope`, what the last sampled vouch actually did read, so the\n *    covered list cannot count sections nobody opened.\n *\n * It lives in the vouch command package rather than `core/document` because\n * that package sits at its five-file limit and this command package already\n * holds vouch's non-printing logic (`../vet/verify.ts` precedent); the one\n * structural question — what is an H2 heading — is still answered by\n * `core/document/parse.ts`'s `sectionHeadings`, fence- and BOM-aware, so this\n * module can never disagree with the rest of loam about whether a `## ` line\n * inside a code fence is structure.\n */\nimport { contentDigest, rawBody, type Frontmatter } from \"../../../core/document/frontmatter.js\";\nimport { sectionHeadings } from \"../../../core/document/parse.js\";\nimport { splitSections } from \"../../../core/provenance/sample/sections.js\";\nimport { planSample, readVouchScope, sampledSections, scopeText, type VouchScope } from \"../../../core/provenance/sample/scope.js\";\n\n/** How the delta names the text above the first H2 — a section with no heading to call it by. */\nconst PREAMBLE_LABEL = \"(before the first heading)\";\n\n/** The four verdicts, each a list of H2 heading lines as the document spells them. */\nexport interface SectionDelta {\n  /** Present in both bodies with different text — in the new body's order. */\n  changed: string[];\n  /** Present only in the new body, in its order. */\n  added: string[];\n  /** Present only in the old body, in its order. */\n  removed: string[];\n  /** Present in both with identical text — the \"already covered\" list. */\n  unchanged: string[];\n}\n\n/**\n * CRLF/CR to LF, the `core/verify/pins/pin.ts` recipe: the old body comes out\n * of a git blob (LF) while the new one comes off a checkout that may be CRLF,\n * and a comparison that let the line endings vote would report every section\n * changed on exactly the machines whose config differs from the repo's.\n * A pure line-ending change is invisible here — the same cost the pins\n * accept, and for a reading list it is the right one: there is nothing to\n * re-read in a CR.\n */\nfunction normalized(text: string): string {\n  return text.replace(/\\r\\n|\\r/g, \"\\n\");\n}\n\n/**\n * One body as heading -> section text. The heading LINE is the key and is not\n * part of the value, so a section whose only change is its own heading reads\n * as removed+added — which is what a reader must do about it: find it under\n * its new name. A duplicated heading concatenates its sections under the one\n * key rather than letting the last occurrence shadow the rest: the compare\n * then sees all of the text, so an edit under either twin still reads as\n * changed. Text before the first heading files under PREAMBLE_LABEL when any\n * of it is more than whitespace.\n */\nfunction sectionMap(body: string): Map<string, string> {\n  const text = normalized(body);\n  const lines = text.split(\"\\n\");\n  const headings = sectionHeadings(text);\n  const map = new Map<string, string>();\n  const file = (key: string, segment: string): void => {\n    map.set(key, map.has(key) ? `${map.get(key)}\\n${segment}` : segment);\n  };\n  const firstHeadingLine = headings[0]?.line ?? lines.length + 1;\n  const preamble = lines.slice(0, firstHeadingLine - 1).join(\"\\n\");\n  if (preamble.trim() !== \"\") map.set(PREAMBLE_LABEL, preamble);\n  headings.forEach((heading, i) => {\n    const end = headings[i + 1]?.line ?? lines.length + 1;\n    file(heading.text, lines.slice(heading.line, end - 1).join(\"\\n\"));\n  });\n  return map;\n}\n\n/** The forward-looking sample: what a `--sample <n>` vouch of this file would cover. */\nexport interface PackSample {\n  /** The seed the stamp will carry, derivable now because the body it hashes will not change. */\n  seed: string;\n  /** Every section the body has. */\n  of: number;\n  /** The sections to read, in document order. Headings only — the pack does not renumber lines. */\n  headings: string[];\n  /** True when `<n>` reached every section: the read is the whole file, and no scope is stamped. */\n  covers: boolean;\n}\n\n/**\n * What `loam vouch --sample <n>` would read of this file — computed through\n * the same `planSample` the stamp uses, so a pack and the vouch that follows\n * it cannot prescribe different samples of one document. Both digests are the\n * ones the stamp will carry: `contentDigest` survives stamping because the\n * body does, and the sources digest is the vetting's own.\n */\nexport function forwardSample(doc: {\n  service: string;\n  /** The file as read, frontmatter included — the same string the stamp is applied to. */\n  raw: string;\n  sourcesDigest: string;\n  n: number;\n}): PackSample {\n  const planned = planSample({\n    service: doc.service,\n    contentDigest: contentDigest(doc.raw),\n    sourcesDigest: doc.sourcesDigest,\n    body: rawBody(doc.raw),\n    n: doc.n,\n  });\n  return {\n    seed: planned.seed,\n    of: planned.of,\n    headings: planned.picked.map((section) => section.heading),\n    covers: planned.picked.length >= planned.of,\n  };\n}\n\n/**\n * What the LAST vouch actually covered, when it was a sampled one.\n *\n * This is the pack's answer to the one way sampling could quietly undo the\n * whole point of it: the \"already covered\" list licenses a person to NOT\n * re-read a section, on the strength of somebody having read it before. After\n * a sampled vouch that strength is not there — most of those sections were\n * never read by anyone — so the licence has to be withdrawn, and withdrawn\n * with the detail that makes it actionable rather than as a blanket warning.\n *\n * The detail is recomputable because the stamp records the seed: run the same\n * pick over the body that vouch was taken over and you get back the exact\n * list that person was shown. `read` is that list; `unread` is every other\n * section of that body — text that has now survived a vouch without anybody\n * looking at it, which is precisely what a re-voucher most needs to know.\n *\n * Three things come back null-but-still-sampled, and all three fail the same\n * way, closed: a scope that does not decode (mangled by hand), no vouched\n * body to recompute over (the document has changed since the stamp, so the\n * pick cannot be reproduced), and a body whose section count no longer\n * matches what the scope claims. In each case the pack reports the scope and\n * refuses to name a covered set — never the reverse.\n */\nexport interface PackVouchScope {\n  /** The `vouch_scope` value as a reader is shown it — verbatim where it is text at all. */\n  stamped: string;\n  /** Decoded, or null when the field is not one this loam wrote. */\n  scope: VouchScope | null;\n  /** The headings that vouch read, in document order — null when they cannot be recomputed. */\n  read: string[] | null;\n  /** The headings it did not read: present at that stamp, and never read by anyone. */\n  unread: string[] | null;\n}\n\nexport function priorScope(fm: Frontmatter, vouchedBody: string | null): PackVouchScope | null {\n  // One reader, `readVouchScope`, decides what \"sampled\" means — so the pack\n  // cannot be the surface that quietly grades a mangled scope as a full vouch\n  // while `loam validate` grades it sampled.\n  const stamp = readVouchScope(fm);\n  if (stamp.kind === \"none\") return null;\n  const stamped = scopeText(fm) ?? \"\";\n  const scope = stamp.kind === \"sampled\" ? stamp.scope : null;\n  const blind: PackVouchScope = { stamped, scope, read: null, unread: null };\n  if (scope === null || vouchedBody === null) return blind;\n  const picked = sampledSections(vouchedBody, scope);\n  if (picked === null) return blind;\n  // Partitioned by LINE, not by heading text: a body with two `## Notes`\n  // sections has two units, and matching on the text would report both as\n  // read when one was picked — turning a section nobody opened into a covered\n  // one, which is the exact misreading this function exists to prevent.\n  const read = new Set(picked.map((section) => section.line));\n  return {\n    stamped,\n    scope,\n    read: picked.map((section) => section.heading),\n    unread: splitSections(vouchedBody)\n      .filter((section) => !read.has(section.line))\n      .map((section) => section.heading),\n  };\n}\n\n/**\n * Compare two bodies section by section. Exact text per heading after line\n * endings are normalized — no reflow tolerance, because \"unchanged\" here\n * licenses a person to NOT re-read a section, and the only claim safe to make\n * at that stakes is byte equality.\n */\nexport function sectionDelta(oldBody: string, newBody: string): SectionDelta {\n  const before = sectionMap(oldBody);\n  const after = sectionMap(newBody);\n  const changed: string[] = [];\n  const added: string[] = [];\n  const unchanged: string[] = [];\n  for (const [heading, text] of after) {\n    const prior = before.get(heading);\n    if (prior === undefined) added.push(heading);\n    else if (prior === text) unchanged.push(heading);\n    else changed.push(heading);\n  }\n  const removed = [...before.keys()].filter((heading) => !after.has(heading));\n  return { changed, added, removed, unchanged };\n}\n"]}

package/dist/commands/vouch/run.js

@@ -21,22 +21,18 @@
  * `loam validate` can see either side move. (This paragraph came from a
  * docblock stranded at the foot of `vouch.ts` when the stamp moved down here.)
  */
-import { existsSync } from "node:fs";
-import { withFrontmatterFields } from "../../core/document/frontmatter.js";
+import { contentDigest, withFrontmatterFields } from "../../core/document/frontmatter.js";
 import { encodeVouchScope } from "../../core/provenance/sample/scope.js";
-import { contentDigest, encodeSourceIndex } from "../../core/provenance/stamp.js";
-import { SPEC_AXES } from "../../core/repo/paths.js";
-import { locateServicePaths } from "../../core/repo/service-target.js";
+import { encodeSourceIndex } from "../../core/provenance/stamp.js";
 import { rollbackStaged, stageWrites } from "../../core/staging/commit.js";
-import { join } from "node:path";
-import { COMMIT_INTENT, InterruptedCommitError } from "../../core/staging/interrupted.js";
-import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import {} from "../../core/staging/interrupted.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow, recoverIfJournaled } from "../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../core/staging/txn/transaction.js";
 import {} from "../../core/staging/writes.js";
 import {} from "./contract.js";
 import { axisScope, sampleDrift } from "./sample/plan.js";
-import { noLivingSpecMessage, verifySpec } from "./vet/verify.js";
+import { verifyAxes } from "./vet/verify.js";
 export async function vouch(req) {
     // A predecessor's journal is rolled forward BEFORE verification reads a
     // byte. Recovery under the commit lock alone was tried first and kept as
@@ -44,54 +40,18 @@ export async function vouch(req) {
     // run's own raced check then refused a sound stamp and the fix doctor
     // prints took two runs instead of one. Cheap when there is nothing to do:
     // one existsSync.
-    let recoveredEarly = null;
-    if (existsSync(join(req.docsDir, COMMIT_INTENT))) {
-        let release;
-        try {
-            release = await acquireDocsLockWaiting(req.docsDir, LOCK_WAIT_MS);
-        }
-        catch (err) {
-            if (err instanceof DocsBusyError)
-                return { ok: false, code: "docs-busy", message: err.message };
-            throw err;
-        }
-        try {
-            recoveredEarly = await recoverInterruptedCommit(req.docsDir);
-        }
-        catch (err) {
-            if (err instanceof InterruptedCommitError)
-                return { ok: false, code: "commit-interrupted", message: err.message };
-            throw err;
-        }
-        finally {
-            await release();
-        }
-    }
-    const paths = await locateServicePaths(req.docsDir, req.service);
-    if (!existsSync(paths.spec)) {
-        return {
-            ok: false,
-            code: "unknown-target",
-            message: noLivingSpecMessage(paths.spec, req.service),
-        };
-    }
-    // Verify first, stamp after: spec.md is required (checked above), arch.spec.md
-    // rides when it exists, and one file that cannot be verified refuses the run
-    // before anything is written. The two axes are walked by name rather than
-    // accumulated in a loop, because everything downstream needs to know WHICH
-    // file it is holding — the required one or the optional one — and a loop can
-    // only say that positionally.
-    const [specAxis, archAxis] = SPEC_AXES;
-    const specVerified = await verifySpec(req, paths[specAxis.key], specAxis.file);
-    if (!specVerified.ok)
-        return specVerified;
-    let archVerified = null;
-    if (existsSync(paths[archAxis.key])) {
-        const outcome = await verifySpec(req, paths[archAxis.key], archAxis.file);
-        if (!outcome.ok)
-            return outcome;
-        archVerified = outcome;
-    }
+    const early = await recoverIfJournaled(req.docsDir);
+    if (!early.ok)
+        return early;
+    // Verify first, stamp after: spec.md is required (a missing one is
+    // `unknown-target`), arch.spec.md rides when it exists, and one file that
+    // cannot be verified refuses the run before anything is written. The walk is
+    // `verifyAxes` (vet/verify.ts), shared with the reading list, and it hands
+    // the two files back by name — vet/verify.ts says why not a loop.
+    const axes = await verifyAxes(req);
+    if (!axes.ok)
+        return axes;
+    const { spec: specVerified, arch: archVerified } = axes;
     const verified = [specVerified, ...(archVerified === null ? [] : [archVerified])];
     // The READING window's race, which the commit window's byte compare cannot
     // see. Under `--sample` a person spends minutes on the list before they
@@ -114,31 +74,17 @@ export async function vouch(req) {
     // could stage against bytes an archive was mid-swap over, and the byte
     // compare below would refuse a perfectly sound stamp — or worse, an
     // interrupted commit's journal would be silently written over.
-    let releaseLock;
-    try {
-        releaseLock = await acquireDocsLockWaiting(req.docsDir, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (err instanceof DocsBusyError)
-            return { ok: false, code: "docs-busy", message: err.message };
-        throw err;
-    }
+    //
+    // A journal under the lock means the last writer never finished; the window
+    // recovers or refuses before reading the pre-images this commit will compare.
+    const opened = await openCommitWindow(req.docsDir, LOCK_WAIT_MS);
+    if (!opened.ok)
+        return opened;
     try {
-        // A journal under the lock means the last writer never finished; recover
-        // or refuse before reading the pre-images this commit will compare.
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(req.docsDir);
-        }
-        catch (err) {
-            if (err instanceof InterruptedCommitError)
-                return { ok: false, code: "commit-interrupted", message: err.message };
-            throw err;
-        }
-        return await commitStamp(req, { writes, specPlan, archPlan, verified }, recovered ?? recoveredEarly);
+        return await commitStamp(req, { writes, specPlan, archPlan, verified }, opened.recovered ?? early.recovered);
     }
     finally {
-        await releaseLock();
+        await opened.release();
     }
 }
 /**
@@ -281,5 +227,4 @@ export function planStamp(v, req) {
         },
     };
 }
-/** A spec-axis file whose sources all check out, carrying what the stamp needs. */
 //# sourceMappingURL=run.js.map

package/dist/commands/vouch/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/vouch/run.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The stamp itself: verify every spec, then write them all or none.\n *\n * Separate from the command because this half has nothing to say to a terminal.\n * It refuses on any spec it cannot verify and stamps none of them — a vouch is\n * a person's claim that the documents match the code, and a partial one would\n * put that claim on files nobody checked.\n *\n * What lands in each file: `status`, `last_verified`, `vouched_by`,\n * `sources_digest`, the `sources_files` index, `content_digest` — and\n * `vouch_scope` when the person read a sample rather than the document — with\n * every byte below the frontmatter left identical. Nothing is written unless\n * all of it can be stamped truthfully for EVERY file: a half-stamp (verified\n * with no digest behind it, or one file stamped and its sibling not) is\n * exactly the claim this command exists to stop being possible, so every\n * present file is verified before any is written, and the writing itself is\n * staged and swapped in like archive's merge, so a failure between the pair's\n * two writes rolls the first back instead of leaving it. The two digests are\n * the two halves of one promise — `sources_digest` pins the code that was\n * read, `content_digest` pins the words it was read against — so\n * `loam validate` can see either side move. (This paragraph came from a\n * docblock stranded at the foot of `vouch.ts` when the stamp moved down here.)\n */\nimport { existsSync } from \"node:fs\";\nimport { withFrontmatterFields } from \"../../core/document/frontmatter.js\";\nimport { encodeVouchScope } from \"../../core/provenance/sample/scope.js\";\nimport { contentDigest, encodeSourceIndex } from \"../../core/provenance/stamp.js\";\nimport { SPEC_AXES } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { join } from \"node:path\";\nimport { COMMIT_INTENT, type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type StampedSpec, type VouchOutcome, type VouchRequest } from \"./contract.js\";\nimport { axisScope, sampleDrift } from \"./sample/plan.js\";\nimport { noLivingSpecMessage, verifySpec, type VerifiedSpec } from \"./vet/verify.js\";\n\nexport async function vouch(req: VouchRequest): Promise<VouchOutcome> {\n  // A predecessor's journal is rolled forward BEFORE verification reads a\n  // byte. Recovery under the commit lock alone was tried first and kept as\n  // the backstop, but it changes files verification has already read, so the\n  // run's own raced check then refused a sound stamp and the fix doctor\n  // prints took two runs instead of one. Cheap when there is nothing to do:\n  // one existsSync.\n  let recoveredEarly: CommitRecovery | null = null;\n  if (existsSync(join(req.docsDir, COMMIT_INTENT))) {\n    let release: () => Promise<void>;\n    try {\n      release = await acquireDocsLockWaiting(req.docsDir, LOCK_WAIT_MS);\n    } catch (err) {\n      if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n      throw err;\n    }\n    try {\n      recoveredEarly = await recoverInterruptedCommit(req.docsDir);\n    } catch (err) {\n      if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n      throw err;\n    } finally {\n      await release();\n    }\n  }\n  const paths = await locateServicePaths(req.docsDir, req.service);\n  if (!existsSync(paths.spec)) {\n    return {\n      ok: false,\n      code: \"unknown-target\",\n      message: noLivingSpecMessage(paths.spec, req.service),\n    };\n  }\n\n  // Verify first, stamp after: spec.md is required (checked above), arch.spec.md\n  // rides when it exists, and one file that cannot be verified refuses the run\n  // before anything is written. The two axes are walked by name rather than\n  // accumulated in a loop, because everything downstream needs to know WHICH\n  // file it is holding — the required one or the optional one — and a loop can\n  // only say that positionally.\n  const [specAxis, archAxis] = SPEC_AXES;\n  const specVerified = await verifySpec(req, paths[specAxis.key], specAxis.file);\n  if (!specVerified.ok) return specVerified;\n  let archVerified: VerifiedSpec | null = null;\n  if (existsSync(paths[archAxis.key])) {\n    const outcome = await verifySpec(req, paths[archAxis.key], archAxis.file);\n    if (!outcome.ok) return outcome;\n    archVerified = outcome;\n  }\n  const verified: VerifiedSpec[] = [specVerified, ...(archVerified === null ? [] : [archVerified])];\n\n  // The READING window's race, which the commit window's byte compare cannot\n  // see. Under `--sample` a person spends minutes on the list before they\n  // answer, and the sample they were shown was chosen from digests taken\n  // before that. If either digest moved — or a second axis file appeared —\n  // the sections they read are not the sections this stamp would claim, and\n  // `vouch_scope` would record a read that did not happen. Nothing is written.\n  const raced = req.sample === undefined ? null : sampleDrift(req.sample, verified, req.service);\n  if (raced !== null) return { ok: false, code: \"vouch-raced\", message: raced };\n\n  const specPlan = planStamp(specVerified, req);\n  const archPlan = archVerified === null ? null : planStamp(archVerified, req);\n  const writes: PlannedWrite[] = [specPlan.write, ...(archPlan === null ? [] : [archPlan.write])];\n\n  // The slow half — reading specs, hashing sources, composing stamps — ran\n  // UNLOCKED above, so vouches for independent services do not serialise\n  // behind one repo-wide mutex. Only the commit window takes the docs lock:\n  // the same one archive, rebase and verify --record hold, in the waiting\n  // form, because two vouches for different services are both supposed to\n  // land. This is the lock the roadmap called missing: without it a vouch\n  // could stage against bytes an archive was mid-swap over, and the byte\n  // compare below would refuse a perfectly sound stamp — or worse, an\n  // interrupted commit's journal would be silently written over.\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(req.docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    // A journal under the lock means the last writer never finished; recover\n    // or refuse before reading the pre-images this commit will compare.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(req.docsDir);\n    } catch (err) {\n      if (err instanceof InterruptedCommitError) return { ok: false, code: \"commit-interrupted\", message: err.message };\n      throw err;\n    }\n    return await commitStamp(req, { writes, specPlan, archPlan, verified }, recovered ?? recoveredEarly);\n  } finally {\n    await releaseLock();\n  }\n}\n\n/**\n * The commit window: stage, compare against what verification read, journal,\n * swap. Split from `vouch` so the lock's extent is visible in the code shape —\n * everything in here holds it, nothing above does.\n */\nasync function commitStamp(\n  req: VouchRequest,\n  plan: {\n    writes: PlannedWrite[];\n    specPlan: { write: PlannedWrite; stamped: StampedSpec };\n    archPlan: { write: PlannedWrite; stamped: StampedSpec } | null;\n    verified: VerifiedSpec[];\n  },\n  recovered: CommitRecovery | null,\n): Promise<VouchOutcome> {\n  const { writes, specPlan, archPlan, verified } = plan;\n  const staged = await stageWrites(writes);\n\n  // One shared docs repo, ten service repos, and nothing stopping two of them\n  // from vouching at once. Between reading a spec and swapping the stamp in\n  // there is a window in which somebody else's vouch (or an editor, or a merge)\n  // can land in the same file — and because the new bytes were computed from\n  // the OLD ones, swapping them in would take that stamp back out without a\n  // word. `stageWrites` has already read what is on disk right now, so the\n  // check is a comparison, not another read: if the file is not what was\n  // verified, this run is describing a document that no longer exists.\n  // Bytes, not text: `stageWrites` reads the file as a Buffer (a string\n  // comparison against it is never equal, which made every vouch report\n  // `vouch-raced` and stamp nothing). A file that is GONE is still a race —\n  // `null` is not \"empty\", it is \"the document this run described is not\n  // there any more\".\n  // Joined by path, not by index: pairing the two lists positionally assumed\n  // `stageWrites` returns one entry per planned write in order — true today,\n  // promised nowhere, and a compare-and-set that silently compares the wrong\n  // pair would stamp over somebody else's vouch. A staged write no verified\n  // file claims has nothing to be compared against, so it counts as raced;\n  // fail-closed is the only safe direction here.\n  const verifiedByPath = new Map(verified.map((v) => [v.path, v] as const));\n  const raced = staged.filter((s) => {\n    const v = verifiedByPath.get(s.write.path);\n    return v === undefined || s.before === null || !s.before.equals(Buffer.from(v.raw, \"utf8\"));\n  });\n  if (raced.length > 0) {\n    // Nothing has swapped yet, so the rollback is only the temp files going\n    // away — the other writer's stamp is left exactly as it landed.\n    await rollbackStaged(staged);\n    return {\n      ok: false,\n      code: \"vouch-raced\",\n      message:\n        `${req.service}: ${raced.map((s) => s.write.path).join(\", \")} changed while this vouch was running — ` +\n        `another vouch or an edit landed first. Nothing was stamped: re-read the document and re-run.`,\n    };\n  }\n\n  // The journaled commit: intent fsynced before the first rename, so a kill\n  // between the pair's two swaps is recoverable instead of invisible — the\n  // exact half-stamped state the all-or-nothing verification exists to rule\n  // out used to be reachable through that one window. The codes are archive's,\n  // reused rather than minted: rolled back → nothing changed, re-running can\n  // work; incomplete → the files listed need a human.\n  const committed = await commitStaged(\n    {\n      root: req.docsDir,\n      command: \"vouch\",\n      // Runnable where vouch runs — the SERVICE repo, with --yes because the\n      // journal's reader may be unattended. Any other journaled docs-repo\n      // writer recovers this journal on its next run too.\n      rerun: `loam vouch --service ${req.service} --yes`,\n      target: req.service,\n    },\n    staged,\n    \"stamped\",\n  );\n  if (!committed.ok) {\n    return committed.raced\n      ? {\n          ok: false,\n          code: \"vouch-raced\",\n          message:\n            `${req.service}: a document changed while this vouch was committing — ` +\n            `another writer landed first. Nothing was stamped: re-read and re-run.`,\n        }\n      : { ok: false, code: committed.code, message: committed.message };\n  }\n  return {\n    ok: true,\n    status: \"verified\",\n    lastVerified: req.today,\n    vouchedBy: req.vouchedBy,\n    recovered,\n    stamped: { spec: specPlan.stamped, archSpec: archPlan === null ? null : archPlan.stamped },\n  };\n}\n\n/**\n * One verified file's share of the commit: the bytes to write, and the record\n * of what was stamped into them. Kept beside each other because they are the\n * same computation — the report must describe the file that was actually\n * written, not a second guess at it.\n */\nexport function planStamp(v: VerifiedSpec, req: VouchRequest): { write: PlannedWrite; stamped: StampedSpec } {\n  // Two passes on purpose: `content_digest` hashes the body BELOW the\n  // frontmatter, and withFrontmatterFields promises that body byte-identical —\n  // so hashing after the first stamp and writing the hash in a second one\n  // yields a digest that is true of the file exactly as written. A re-vouch\n  // takes the same road and refreshes every field, this one included.\n  //\n  // The scope this file's stamp will carry — null both when the run is an\n  // ordinary vouch and when a sampled run's `--sample <n>` covered the whole\n  // file. Joined to the plan by FILENAME rather than taken positionally: the\n  // two axes are stamped by two separate calls, and a scope written onto the\n  // wrong file would claim a person read four sections of a document they\n  // never opened.\n  const planned = req.sample?.axes.find((axis) => axis.file === v.file);\n  // A verified file with no planned axis is unreachable — `sampleDrift`\n  // refuses that run before this line — and null is the safe direction if it\n  // ever were: a full stamp that CLEARS any prior scope, never one claiming a\n  // sample nobody was shown.\n  const scope = planned === undefined ? null : axisScope(planned);\n  const restamped = withFrontmatterFields(\n    v.raw,\n    {\n      status: \"verified\",\n      last_verified: req.today,\n      // WHO, beside when. Without it `status: verified` recorded that the word\n      // had been written and nothing about who wrote it, so a vouch and an\n      // agent's own draft left the same trace in the document — the one\n      // distinction this command exists to make.\n      vouched_by: req.vouchedBy,\n      sources_digest: v.digest,\n      // Beside the digest, what it was taken over. `sources_digest` alone can\n      // only ever say THAT the code moved; the next `loam validate` reads this\n      // back to say which files did.\n      sources_files: encodeSourceIndex(v.index),\n      // Beside `vouched_by`, never inside `status`: the rung string `vouched`\n      // and the status `verified` are a published contract, and a sampled read\n      // is not a fourth status — it is a qualification of this one.\n      ...(scope === null ? {} : { vouch_scope: encodeVouchScope(scope) }),\n    },\n    // A full vouch CLEARS any scope a previous sampled one left, rather than\n    // stranding a claim that would keep a fully-read document reading as\n    // partial forever. Removing a key that was never there is a no-op, so\n    // this rides on every run that is not itself sampling.\n    scope === null ? [\"vouch_scope\"] : [],\n  );\n  const bodyDigest = contentDigest(restamped);\n  return {\n    write: { path: v.path, content: withFrontmatterFields(restamped, { content_digest: bodyDigest }) },\n    stamped: {\n      path: v.path,\n      file: v.file,\n      digest: v.digest,\n      contentDigest: bodyDigest,\n      sources: v.sources,\n      files: v.index.length,\n      skipped: v.skipped,\n      vouchScope: scope,\n    },\n  };\n}\n\n/** A spec-axis file whose sources all check out, carrying what the stamp needs. */\n"]}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/vouch/run.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The stamp itself: verify every spec, then write them all or none.\n *\n * Separate from the command because this half has nothing to say to a terminal.\n * It refuses on any spec it cannot verify and stamps none of them — a vouch is\n * a person's claim that the documents match the code, and a partial one would\n * put that claim on files nobody checked.\n *\n * What lands in each file: `status`, `last_verified`, `vouched_by`,\n * `sources_digest`, the `sources_files` index, `content_digest` — and\n * `vouch_scope` when the person read a sample rather than the document — with\n * every byte below the frontmatter left identical. Nothing is written unless\n * all of it can be stamped truthfully for EVERY file: a half-stamp (verified\n * with no digest behind it, or one file stamped and its sibling not) is\n * exactly the claim this command exists to stop being possible, so every\n * present file is verified before any is written, and the writing itself is\n * staged and swapped in like archive's merge, so a failure between the pair's\n * two writes rolls the first back instead of leaving it. The two digests are\n * the two halves of one promise — `sources_digest` pins the code that was\n * read, `content_digest` pins the words it was read against — so\n * `loam validate` can see either side move. (This paragraph came from a\n * docblock stranded at the foot of `vouch.ts` when the stamp moved down here.)\n */\nimport { contentDigest, withFrontmatterFields } from \"../../core/document/frontmatter.js\";\nimport { encodeVouchScope } from \"../../core/provenance/sample/scope.js\";\nimport { encodeSourceIndex } from \"../../core/provenance/stamp.js\";\nimport { rollbackStaged, stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow, recoverIfJournaled } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { type StampedSpec, type VouchOutcome, type VouchRequest } from \"./contract.js\";\nimport { axisScope, sampleDrift } from \"./sample/plan.js\";\nimport { verifyAxes, type VerifiedSpec } from \"./vet/verify.js\";\n\nexport async function vouch(req: VouchRequest): Promise<VouchOutcome> {\n  // A predecessor's journal is rolled forward BEFORE verification reads a\n  // byte. Recovery under the commit lock alone was tried first and kept as\n  // the backstop, but it changes files verification has already read, so the\n  // run's own raced check then refused a sound stamp and the fix doctor\n  // prints took two runs instead of one. Cheap when there is nothing to do:\n  // one existsSync.\n  const early = await recoverIfJournaled(req.docsDir);\n  if (!early.ok) return early;\n  // Verify first, stamp after: spec.md is required (a missing one is\n  // `unknown-target`), arch.spec.md rides when it exists, and one file that\n  // cannot be verified refuses the run before anything is written. The walk is\n  // `verifyAxes` (vet/verify.ts), shared with the reading list, and it hands\n  // the two files back by name — vet/verify.ts says why not a loop.\n  const axes = await verifyAxes(req);\n  if (!axes.ok) return axes;\n  const { spec: specVerified, arch: archVerified } = axes;\n  const verified: VerifiedSpec[] = [specVerified, ...(archVerified === null ? [] : [archVerified])];\n\n  // The READING window's race, which the commit window's byte compare cannot\n  // see. Under `--sample` a person spends minutes on the list before they\n  // answer, and the sample they were shown was chosen from digests taken\n  // before that. If either digest moved — or a second axis file appeared —\n  // the sections they read are not the sections this stamp would claim, and\n  // `vouch_scope` would record a read that did not happen. Nothing is written.\n  const raced = req.sample === undefined ? null : sampleDrift(req.sample, verified, req.service);\n  if (raced !== null) return { ok: false, code: \"vouch-raced\", message: raced };\n\n  const specPlan = planStamp(specVerified, req);\n  const archPlan = archVerified === null ? null : planStamp(archVerified, req);\n  const writes: PlannedWrite[] = [specPlan.write, ...(archPlan === null ? [] : [archPlan.write])];\n\n  // The slow half — reading specs, hashing sources, composing stamps — ran\n  // UNLOCKED above, so vouches for independent services do not serialise\n  // behind one repo-wide mutex. Only the commit window takes the docs lock:\n  // the same one archive, rebase and verify --record hold, in the waiting\n  // form, because two vouches for different services are both supposed to\n  // land. This is the lock the roadmap called missing: without it a vouch\n  // could stage against bytes an archive was mid-swap over, and the byte\n  // compare below would refuse a perfectly sound stamp — or worse, an\n  // interrupted commit's journal would be silently written over.\n  //\n  // A journal under the lock means the last writer never finished; the window\n  // recovers or refuses before reading the pre-images this commit will compare.\n  const opened = await openCommitWindow(req.docsDir, LOCK_WAIT_MS);\n  if (!opened.ok) return opened;\n  try {\n    return await commitStamp(req, { writes, specPlan, archPlan, verified }, opened.recovered ?? early.recovered);\n  } finally {\n    await opened.release();\n  }\n}\n\n/**\n * The commit window: stage, compare against what verification read, journal,\n * swap. Split from `vouch` so the lock's extent is visible in the code shape —\n * everything in here holds it, nothing above does.\n */\nasync function commitStamp(\n  req: VouchRequest,\n  plan: {\n    writes: PlannedWrite[];\n    specPlan: { write: PlannedWrite; stamped: StampedSpec };\n    archPlan: { write: PlannedWrite; stamped: StampedSpec } | null;\n    verified: VerifiedSpec[];\n  },\n  recovered: CommitRecovery | null,\n): Promise<VouchOutcome> {\n  const { writes, specPlan, archPlan, verified } = plan;\n  const staged = await stageWrites(writes);\n\n  // One shared docs repo, ten service repos, and nothing stopping two of them\n  // from vouching at once. Between reading a spec and swapping the stamp in\n  // there is a window in which somebody else's vouch (or an editor, or a merge)\n  // can land in the same file — and because the new bytes were computed from\n  // the OLD ones, swapping them in would take that stamp back out without a\n  // word. `stageWrites` has already read what is on disk right now, so the\n  // check is a comparison, not another read: if the file is not what was\n  // verified, this run is describing a document that no longer exists.\n  // Bytes, not text: `stageWrites` reads the file as a Buffer (a string\n  // comparison against it is never equal, which made every vouch report\n  // `vouch-raced` and stamp nothing). A file that is GONE is still a race —\n  // `null` is not \"empty\", it is \"the document this run described is not\n  // there any more\".\n  // Joined by path, not by index: pairing the two lists positionally assumed\n  // `stageWrites` returns one entry per planned write in order — true today,\n  // promised nowhere, and a compare-and-set that silently compares the wrong\n  // pair would stamp over somebody else's vouch. A staged write no verified\n  // file claims has nothing to be compared against, so it counts as raced;\n  // fail-closed is the only safe direction here.\n  const verifiedByPath = new Map(verified.map((v) => [v.path, v] as const));\n  const raced = staged.filter((s) => {\n    const v = verifiedByPath.get(s.write.path);\n    return v === undefined || s.before === null || !s.before.equals(Buffer.from(v.raw, \"utf8\"));\n  });\n  if (raced.length > 0) {\n    // Nothing has swapped yet, so the rollback is only the temp files going\n    // away — the other writer's stamp is left exactly as it landed.\n    await rollbackStaged(staged);\n    return {\n      ok: false,\n      code: \"vouch-raced\",\n      message:\n        `${req.service}: ${raced.map((s) => s.write.path).join(\", \")} changed while this vouch was running — ` +\n        `another vouch or an edit landed first. Nothing was stamped: re-read the document and re-run.`,\n    };\n  }\n\n  // The journaled commit: intent fsynced before the first rename, so a kill\n  // between the pair's two swaps is recoverable instead of invisible — the\n  // exact half-stamped state the all-or-nothing verification exists to rule\n  // out used to be reachable through that one window. The codes are archive's,\n  // reused rather than minted: rolled back → nothing changed, re-running can\n  // work; incomplete → the files listed need a human.\n  const committed = await commitStaged(\n    {\n      root: req.docsDir,\n      command: \"vouch\",\n      // Runnable where vouch runs — the SERVICE repo, with --yes because the\n      // journal's reader may be unattended. Any other journaled docs-repo\n      // writer recovers this journal on its next run too.\n      rerun: `loam vouch --service ${req.service} --yes`,\n      target: req.service,\n    },\n    staged,\n    \"stamped\",\n  );\n  if (!committed.ok) {\n    return committed.raced\n      ? {\n          ok: false,\n          code: \"vouch-raced\",\n          message:\n            `${req.service}: a document changed while this vouch was committing — ` +\n            `another writer landed first. Nothing was stamped: re-read and re-run.`,\n        }\n      : { ok: false, code: committed.code, message: committed.message };\n  }\n  return {\n    ok: true,\n    status: \"verified\",\n    lastVerified: req.today,\n    vouchedBy: req.vouchedBy,\n    recovered,\n    stamped: { spec: specPlan.stamped, archSpec: archPlan === null ? null : archPlan.stamped },\n  };\n}\n\n/**\n * One verified file's share of the commit: the bytes to write, and the record\n * of what was stamped into them. Kept beside each other because they are the\n * same computation — the report must describe the file that was actually\n * written, not a second guess at it.\n */\nexport function planStamp(v: VerifiedSpec, req: VouchRequest): { write: PlannedWrite; stamped: StampedSpec } {\n  // Two passes on purpose: `content_digest` hashes the body BELOW the\n  // frontmatter, and withFrontmatterFields promises that body byte-identical —\n  // so hashing after the first stamp and writing the hash in a second one\n  // yields a digest that is true of the file exactly as written. A re-vouch\n  // takes the same road and refreshes every field, this one included.\n  //\n  // The scope this file's stamp will carry — null both when the run is an\n  // ordinary vouch and when a sampled run's `--sample <n>` covered the whole\n  // file. Joined to the plan by FILENAME rather than taken positionally: the\n  // two axes are stamped by two separate calls, and a scope written onto the\n  // wrong file would claim a person read four sections of a document they\n  // never opened.\n  const planned = req.sample?.axes.find((axis) => axis.file === v.file);\n  // A verified file with no planned axis is unreachable — `sampleDrift`\n  // refuses that run before this line — and null is the safe direction if it\n  // ever were: a full stamp that CLEARS any prior scope, never one claiming a\n  // sample nobody was shown.\n  const scope = planned === undefined ? null : axisScope(planned);\n  const restamped = withFrontmatterFields(\n    v.raw,\n    {\n      status: \"verified\",\n      last_verified: req.today,\n      // WHO, beside when. Without it `status: verified` recorded that the word\n      // had been written and nothing about who wrote it, so a vouch and an\n      // agent's own draft left the same trace in the document — the one\n      // distinction this command exists to make.\n      vouched_by: req.vouchedBy,\n      sources_digest: v.digest,\n      // Beside the digest, what it was taken over. `sources_digest` alone can\n      // only ever say THAT the code moved; the next `loam validate` reads this\n      // back to say which files did.\n      sources_files: encodeSourceIndex(v.index),\n      // Beside `vouched_by`, never inside `status`: the rung string `vouched`\n      // and the status `verified` are a published contract, and a sampled read\n      // is not a fourth status — it is a qualification of this one.\n      ...(scope === null ? {} : { vouch_scope: encodeVouchScope(scope) }),\n    },\n    // A full vouch CLEARS any scope a previous sampled one left, rather than\n    // stranding a claim that would keep a fully-read document reading as\n    // partial forever. Removing a key that was never there is a no-op, so\n    // this rides on every run that is not itself sampling.\n    scope === null ? [\"vouch_scope\"] : [],\n  );\n  const bodyDigest = contentDigest(restamped);\n  return {\n    write: { path: v.path, content: withFrontmatterFields(restamped, { content_digest: bodyDigest }) },\n    stamped: {\n      path: v.path,\n      file: v.file,\n      digest: v.digest,\n      contentDigest: bodyDigest,\n      sources: v.sources,\n      files: v.index.length,\n      skipped: v.skipped,\n      vouchScope: scope,\n    },\n  };\n}\n"]}

package/dist/commands/vouch/sample/plan.js

@@ -9,12 +9,13 @@
  * command exists to interrupt. So the reading list is computed first, printed,
  * and only then is the person asked.
  *
- * It runs the vouch's own vetting (`../vet/verify.ts`, the same call
- * `run.ts` and the reading pack make), which means every refusal a vouch can
- * raise about a document — an unreadable header, no `sources`, a glob
- * pattern, a source that is gone, an expansion covering no files — fires HERE,
- * before the prompt, with the same code and the same words. A person should
- * not read four sections and then be told the run was never going to stamp.
+ * It runs the vouch's own vetting (`../vet/verify.ts`: the same axis walk
+ * `run.ts` makes, over the call the reading pack makes), which means every
+ * refusal a vouch can raise about a document — an unreadable header, no
+ * `sources`, a glob pattern, a source that is gone, an expansion covering no
+ * files — fires HERE, before the prompt, with the same code and the same
+ * words. A person should not read four sections and then be told the run was
+ * never going to stamp.
  *
  * The cost is that the sources are walked and hashed twice: once to seed the
  * sample, once at the stamp. That is the honesty price of the seed being
@@ -22,13 +23,9 @@
  * second walk buys is the drift check, which refuses a stamp whose sample was
  * chosen from a document that has since moved.
  */
-import { existsSync } from "node:fs";
-import { rawBody } from "../../../core/document/frontmatter.js";
+import { contentDigest, rawBody } from "../../../core/document/frontmatter.js";
 import { planSample } from "../../../core/provenance/sample/scope.js";
-import { contentDigest } from "../../../core/provenance/stamp.js";
-import { SPEC_AXES } from "../../../core/repo/paths.js";
-import { locateServicePaths } from "../../../core/repo/service-target.js";
-import { noLivingSpecMessage, verifySpec } from "../vet/verify.js";
+import { verifyAxes } from "../vet/verify.js";
 /** The scope a planned axis will stamp, or null for one that was read in full. */
 export function axisScope(axis) {
     return axis.mode === "full" ? null : { sections: axis.picked.length, of: axis.of, seed: axis.seed };
@@ -69,29 +66,18 @@ export function sampleDrift(plan, verified, service) {
         `not the sections a stamp would now cover. Nothing was stamped: re-run for a fresh reading list.`);
 }
 /**
- * Build the reading list. Same axis walk as `run.ts` — spec.md required,
- * arch.spec.md when it exists — and the same all-or-nothing discipline: one
- * file that cannot be verified refuses the run before a person is asked to
- * read anything.
+ * Build the reading list. The axis walk is `run.ts`'s own — `verifyAxes`, which
+ * refuses a missing spec.md in vet/verify.ts's one sentence (the same absence
+ * and the same fix; three spellings would read as three different problems) —
+ * and so is the all-or-nothing discipline: one file that cannot be verified
+ * refuses the run before a person is asked to read anything.
  */
 export async function buildSamplePlan(req) {
-    const paths = await locateServicePaths(req.docsDir, req.service);
-    if (!existsSync(paths.spec)) {
-        // One sentence, from `vet/verify.ts`: the same absence and the same fix,
-        // and three spellings of it would read as three different problems.
-        return { ok: false, code: "unknown-target", message: noLivingSpecMessage(paths.spec, req.service) };
-    }
+    const verified = await verifyAxes(req);
+    if (!verified.ok)
+        return verified;
     const axes = [];
-    for (const axis of SPEC_AXES) {
-        const path = paths[axis.key];
-        if (!existsSync(path))
-            continue;
-        // Sequential, not Promise.all: each iteration hashes a whole source tree
-        // through the batched digest, and two of those in flight at once doubles
-        // the file descriptors that batching exists to bound. Two files.
-        const vetted = await verifySpec({ service: req.service, repoDir: req.repoDir }, path, axis.file);
-        if (!vetted.ok)
-            return vetted;
+    for (const vetted of verified.arch === null ? [verified.spec] : [verified.spec, verified.arch]) {
         const digest = contentDigest(vetted.raw);
         // The BODY, so no frontmatter line can be picked as a section — and the
         // same slice `content_digest` is taken over, which is what makes the
@@ -105,8 +91,8 @@ export async function buildSamplePlan(req) {
             n: req.n,
         });
         const base = {
-            file: axis.file,
-            path,
+            file: vetted.file,
+            path: vetted.path,
             contentDigest: digest,
             sourcesDigest: vetted.digest,
             of: sample.of,

package/dist/commands/vouch/sample/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/commands/vouch/sample/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pre-pass behind `loam vouch --sample <n>`: decide, before anyone is\n * asked anything, which sections of which files this vouch will actually\n * cover.\n *\n * It has to happen before the confirmation because a sampled vouch's question\n * is different in kind — \"have you read THESE four sections\", not \"have you\n * read the code\" — and a question that names nothing is the reflex this\n * command exists to interrupt. So the reading list is computed first, printed,\n * and only then is the person asked.\n *\n * It runs the vouch's own vetting (`../vet/verify.ts`, the same call\n * `run.ts` and the reading pack make), which means every refusal a vouch can\n * raise about a document — an unreadable header, no `sources`, a glob\n * pattern, a source that is gone, an expansion covering no files — fires HERE,\n * before the prompt, with the same code and the same words. A person should\n * not read four sections and then be told the run was never going to stamp.\n *\n * The cost is that the sources are walked and hashed twice: once to seed the\n * sample, once at the stamp. That is the honesty price of the seed being\n * content-derived, and `run.ts` spends the second walk anyway — what the\n * second walk buys is the drift check, which refuses a stamp whose sample was\n * chosen from a document that has since moved.\n */\nimport { existsSync } from \"node:fs\";\nimport { rawBody } from \"../../../core/document/frontmatter.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport type { DocSection } from \"../../../core/provenance/sample/sections.js\";\nimport { planSample, type VouchScope } from \"../../../core/provenance/sample/scope.js\";\nimport { contentDigest } from \"../../../core/provenance/stamp.js\";\nimport { SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport { noLivingSpecMessage, verifySpec, type SpecRefusal, type VerifiedSpec } from \"../vet/verify.js\";\n\n/**\n * One spec-axis file's share of a `--sample <n>` run, as the pre-pass decided\n * it and the stamp must honour it.\n *\n * A variant rather than an optional `picked?:`, because \"read in full\" and\n * \"sampled\" are two different claims and the difference decides whether the\n * file gets a `vouch_scope` at all. The two digests ride on both arms: they\n * are what the seed was derived from, and the stamp re-checks them against a\n * fresh verification, because a person reads for minutes and nothing locks\n * the document while they do.\n */\ninterface PlannedAxisBase {\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". The key the stamp joins on. */\n  file: string;\n  /** Absolute path, for the reading list's own line. */\n  path: string;\n  /** `contentDigest(raw)` when the reading list was built. */\n  contentDigest: string;\n  /** The sources digest when the reading list was built. */\n  sourcesDigest: string;\n  /** Every section the body had. */\n  of: number;\n  /**\n   * How many lines of frontmatter sit above the body. `DocSection.line` is\n   * counted within the BODY — that is what the splitter can promise, since it\n   * is handed a body — and a reading list that printed those numbers as file\n   * lines would send a person to the wrong place in every stamped document.\n   * Added once, at the display edge.\n   */\n  lineOffset: number;\n  /** The `sources` entries as the frontmatter spells them, and how many files they expanded to. */\n  sources: { entries: string[]; files: number };\n}\n\nexport type PlannedAxis =\n  /** `of <= n`: the sample covers the whole file, so this axis is an ordinary full vouch. */\n  | (PlannedAxisBase & { mode: \"full\" })\n  | (PlannedAxisBase & { mode: \"sampled\"; seed: string; picked: readonly DocSection[] });\n\nexport interface SamplePlan {\n  /** `--sample <n>` as the person typed it — carried so the output can say what was asked for. */\n  n: number;\n  /**\n   * Every spec-axis file the pre-pass verified, sampled or not. Complete on\n   * purpose: the stamp compares this roster against what it re-verifies, so an\n   * arch.spec.md that appeared while the person was reading refuses the run\n   * instead of riding along unread.\n   */\n  axes: PlannedAxis[];\n}\n\n/** The scope a planned axis will stamp, or null for one that was read in full. */\nexport function axisScope(axis: PlannedAxis): VouchScope | null {\n  return axis.mode === \"full\" ? null : { sections: axis.picked.length, of: axis.of, seed: axis.seed };\n}\n\n/**\n * What moved between the reading list and the stamp, as a phrase for the\n * refusal — or null when the plan and the fresh verification describe the same\n * documents.\n *\n * Joined by FILENAME both ways, and both directions matter: a plan entry with\n * no verified file means an axis vanished mid-read, a verified file with no\n * plan entry means one appeared and nobody was shown it. Comparing counts, or\n * zipping the two lists, would call the second case fine.\n *\n * The digests, not the bytes: `content_digest` and `sources_digest` are the\n * seed's own inputs, so a change in either is exactly a change in which\n * sections a sample would pick. It lives here rather than in `run.ts` because\n * it is a question about the PLAN — whether the reading list still describes\n * these files — and the answer has to be computed the same way the plan was.\n */\nexport function sampleDrift(\n  plan: SamplePlan,\n  verified: readonly VerifiedSpec[],\n  service: string,\n): string | null {\n  const now = new Map(verified.map((v) => [v.file, v] as const));\n  const moved = plan.axes\n    .filter((axis) => {\n      const v = now.get(axis.file);\n      return v === undefined || contentDigest(v.raw) !== axis.contentDigest || v.digest !== axis.sourcesDigest;\n    })\n    .map((axis) => axis.file);\n  const planned = new Set(plan.axes.map((axis) => axis.file));\n  const appeared = verified.filter((v) => !planned.has(v.file)).map((v) => v.file);\n  const files = [...moved, ...appeared];\n  if (files.length === 0) return null;\n  // The whole sentence, not the file list: `run.ts` returns it verbatim under\n  // `vouch-raced`, and the diagnosis — which is about a READING window nothing\n  // locks — belongs beside the check that can explain it.\n  return (\n    `${service}: ${files.join(\", \")} changed while you were reading the sample — the sections you were shown are ` +\n    `not the sections a stamp would now cover. Nothing was stamped: re-run for a fresh reading list.`\n  );\n}\n\nexport interface SampleRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what `sources` resolve against. */\n  repoDir: string;\n  /** How many sections to read per spec-axis file. A whole number of at least 1; the caller validates. */\n  n: number;\n}\n\nexport type SampleOutcome =\n  | { ok: true; plan: SamplePlan }\n  | { ok: false; code: SpecRefusal[\"code\"] | \"unknown-target\"; message: string };\n\n/**\n * Build the reading list. Same axis walk as `run.ts` — spec.md required,\n * arch.spec.md when it exists — and the same all-or-nothing discipline: one\n * file that cannot be verified refuses the run before a person is asked to\n * read anything.\n */\nexport async function buildSamplePlan(req: SampleRequest): Promise<SampleOutcome> {\n  const paths = await locateServicePaths(req.docsDir, req.service);\n  if (!existsSync(paths.spec)) {\n    // One sentence, from `vet/verify.ts`: the same absence and the same fix,\n    // and three spellings of it would read as three different problems.\n    return { ok: false, code: \"unknown-target\", message: noLivingSpecMessage(paths.spec, req.service) };\n  }\n  const axes: PlannedAxis[] = [];\n  for (const axis of SPEC_AXES) {\n    const path = paths[axis.key];\n    if (!existsSync(path)) continue;\n    // Sequential, not Promise.all: each iteration hashes a whole source tree\n    // through the batched digest, and two of those in flight at once doubles\n    // the file descriptors that batching exists to bound. Two files.\n    const vetted = await verifySpec({ service: req.service, repoDir: req.repoDir }, path, axis.file);\n    if (!vetted.ok) return vetted;\n    const digest = contentDigest(vetted.raw);\n    // The BODY, so no frontmatter line can be picked as a section — and the\n    // same slice `content_digest` is taken over, which is what makes the\n    // seed's inputs and the sampled text describe one document.\n    const body = rawBody(vetted.raw);\n    const sample = planSample({\n      service: req.service,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      body,\n      n: req.n,\n    });\n    const base = {\n      file: axis.file,\n      path,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      of: sample.of,\n      // The header's line count, by subtraction rather than a second parse:\n      // `rawBody` is the one definition of where the body starts, and asking\n      // it twice is how the two answers drift.\n      lineOffset: vetted.raw.slice(0, vetted.raw.length - body.length).split(\"\\n\").length - 1,\n      sources: { entries: vetted.sources, files: vetted.index.length },\n    };\n    axes.push(\n      sample.picked.length >= sample.of\n        ? { ...base, mode: \"full\" }\n        : { ...base, mode: \"sampled\", seed: sample.seed, picked: sample.picked },\n    );\n  }\n  return { ok: true, plan: { n: req.n, axes } };\n}\n"]}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../../src/commands/vouch/sample/plan.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pre-pass behind `loam vouch --sample <n>`: decide, before anyone is\n * asked anything, which sections of which files this vouch will actually\n * cover.\n *\n * It has to happen before the confirmation because a sampled vouch's question\n * is different in kind — \"have you read THESE four sections\", not \"have you\n * read the code\" — and a question that names nothing is the reflex this\n * command exists to interrupt. So the reading list is computed first, printed,\n * and only then is the person asked.\n *\n * It runs the vouch's own vetting (`../vet/verify.ts`: the same axis walk\n * `run.ts` makes, over the call the reading pack makes), which means every\n * refusal a vouch can raise about a document — an unreadable header, no\n * `sources`, a glob pattern, a source that is gone, an expansion covering no\n * files — fires HERE, before the prompt, with the same code and the same\n * words. A person should not read four sections and then be told the run was\n * never going to stamp.\n *\n * The cost is that the sources are walked and hashed twice: once to seed the\n * sample, once at the stamp. That is the honesty price of the seed being\n * content-derived, and `run.ts` spends the second walk anyway — what the\n * second walk buys is the drift check, which refuses a stamp whose sample was\n * chosen from a document that has since moved.\n */\nimport { contentDigest, rawBody } from \"../../../core/document/frontmatter.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport type { DocSection } from \"../../../core/provenance/sample/sections.js\";\nimport { planSample, type VouchScope } from \"../../../core/provenance/sample/scope.js\";\nimport { verifyAxes, type AxesRefusal, type VerifiedSpec } from \"../vet/verify.js\";\n\n/**\n * One spec-axis file's share of a `--sample <n>` run, as the pre-pass decided\n * it and the stamp must honour it.\n *\n * A variant rather than an optional `picked?:`, because \"read in full\" and\n * \"sampled\" are two different claims and the difference decides whether the\n * file gets a `vouch_scope` at all. The two digests ride on both arms: they\n * are what the seed was derived from, and the stamp re-checks them against a\n * fresh verification, because a person reads for minutes and nothing locks\n * the document while they do.\n */\ninterface PlannedAxisBase {\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". The key the stamp joins on. */\n  file: string;\n  /** Absolute path, for the reading list's own line. */\n  path: string;\n  /** `contentDigest(raw)` when the reading list was built. */\n  contentDigest: string;\n  /** The sources digest when the reading list was built. */\n  sourcesDigest: string;\n  /** Every section the body had. */\n  of: number;\n  /**\n   * How many lines of frontmatter sit above the body. `DocSection.line` is\n   * counted within the BODY — that is what the splitter can promise, since it\n   * is handed a body — and a reading list that printed those numbers as file\n   * lines would send a person to the wrong place in every stamped document.\n   * Added once, at the display edge.\n   */\n  lineOffset: number;\n  /** The `sources` entries as the frontmatter spells them, and how many files they expanded to. */\n  sources: { entries: string[]; files: number };\n}\n\nexport type PlannedAxis =\n  /** `of <= n`: the sample covers the whole file, so this axis is an ordinary full vouch. */\n  | (PlannedAxisBase & { mode: \"full\" })\n  | (PlannedAxisBase & { mode: \"sampled\"; seed: string; picked: readonly DocSection[] });\n\nexport interface SamplePlan {\n  /** `--sample <n>` as the person typed it — carried so the output can say what was asked for. */\n  n: number;\n  /**\n   * Every spec-axis file the pre-pass verified, sampled or not. Complete on\n   * purpose: the stamp compares this roster against what it re-verifies, so an\n   * arch.spec.md that appeared while the person was reading refuses the run\n   * instead of riding along unread.\n   */\n  axes: PlannedAxis[];\n}\n\n/** The scope a planned axis will stamp, or null for one that was read in full. */\nexport function axisScope(axis: PlannedAxis): VouchScope | null {\n  return axis.mode === \"full\" ? null : { sections: axis.picked.length, of: axis.of, seed: axis.seed };\n}\n\n/**\n * What moved between the reading list and the stamp, as a phrase for the\n * refusal — or null when the plan and the fresh verification describe the same\n * documents.\n *\n * Joined by FILENAME both ways, and both directions matter: a plan entry with\n * no verified file means an axis vanished mid-read, a verified file with no\n * plan entry means one appeared and nobody was shown it. Comparing counts, or\n * zipping the two lists, would call the second case fine.\n *\n * The digests, not the bytes: `content_digest` and `sources_digest` are the\n * seed's own inputs, so a change in either is exactly a change in which\n * sections a sample would pick. It lives here rather than in `run.ts` because\n * it is a question about the PLAN — whether the reading list still describes\n * these files — and the answer has to be computed the same way the plan was.\n */\nexport function sampleDrift(\n  plan: SamplePlan,\n  verified: readonly VerifiedSpec[],\n  service: string,\n): string | null {\n  const now = new Map(verified.map((v) => [v.file, v] as const));\n  const moved = plan.axes\n    .filter((axis) => {\n      const v = now.get(axis.file);\n      return v === undefined || contentDigest(v.raw) !== axis.contentDigest || v.digest !== axis.sourcesDigest;\n    })\n    .map((axis) => axis.file);\n  const planned = new Set(plan.axes.map((axis) => axis.file));\n  const appeared = verified.filter((v) => !planned.has(v.file)).map((v) => v.file);\n  const files = [...moved, ...appeared];\n  if (files.length === 0) return null;\n  // The whole sentence, not the file list: `run.ts` returns it verbatim under\n  // `vouch-raced`, and the diagnosis — which is about a READING window nothing\n  // locks — belongs beside the check that can explain it.\n  return (\n    `${service}: ${files.join(\", \")} changed while you were reading the sample — the sections you were shown are ` +\n    `not the sections a stamp would now cover. Nothing was stamped: re-run for a fresh reading list.`\n  );\n}\n\nexport interface SampleRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what `sources` resolve against. */\n  repoDir: string;\n  /** How many sections to read per spec-axis file. A whole number of at least 1; the caller validates. */\n  n: number;\n}\n\nexport type SampleOutcome = { ok: true; plan: SamplePlan } | AxesRefusal;\n\n/**\n * Build the reading list. The axis walk is `run.ts`'s own — `verifyAxes`, which\n * refuses a missing spec.md in vet/verify.ts's one sentence (the same absence\n * and the same fix; three spellings would read as three different problems) —\n * and so is the all-or-nothing discipline: one file that cannot be verified\n * refuses the run before a person is asked to read anything.\n */\nexport async function buildSamplePlan(req: SampleRequest): Promise<SampleOutcome> {\n  const verified = await verifyAxes(req);\n  if (!verified.ok) return verified;\n  const axes: PlannedAxis[] = [];\n  for (const vetted of verified.arch === null ? [verified.spec] : [verified.spec, verified.arch]) {\n    const digest = contentDigest(vetted.raw);\n    // The BODY, so no frontmatter line can be picked as a section — and the\n    // same slice `content_digest` is taken over, which is what makes the\n    // seed's inputs and the sampled text describe one document.\n    const body = rawBody(vetted.raw);\n    const sample = planSample({\n      service: req.service,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      body,\n      n: req.n,\n    });\n    const base = {\n      file: vetted.file,\n      path: vetted.path,\n      contentDigest: digest,\n      sourcesDigest: vetted.digest,\n      of: sample.of,\n      // The header's line count, by subtraction rather than a second parse:\n      // `rawBody` is the one definition of where the body starts, and asking\n      // it twice is how the two answers drift.\n      lineOffset: vetted.raw.slice(0, vetted.raw.length - body.length).split(\"\\n\").length - 1,\n      sources: { entries: vetted.sources, files: vetted.index.length },\n    };\n    axes.push(\n      sample.picked.length >= sample.of\n        ? { ...base, mode: \"full\" }\n        : { ...base, mode: \"sampled\", seed: sample.seed, picked: sample.picked },\n    );\n  }\n  return { ok: true, plan: { n: req.n, axes } };\n}\n"]}

package/dist/commands/vouch/vet/verify.js

@@ -5,25 +5,57 @@
  * could check, and says which sources it skipped — a vouch over a spec whose
  * sources could not be read would be the claim this command exists to prevent.
  */
+import { existsSync } from "node:fs";
 import { listField, parseFrontmatter } from "../../../core/document/frontmatter.js";
 import { missingSources, patternSources, unsafeSources } from "../../../core/provenance/sources.js";
 import { emptySourcesMessage, sourcesDigest } from "../../../core/provenance/stamp.js";
+import { SPEC_AXES } from "../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
 import { NotUtf8Error, readUtf8 } from "../../../core/staging/writes.js";
 /**
  * "There is no living spec here", in one sentence.
  *
  * Three callers reach this state independently — the stamp (`../run.ts`), the
- * reading list (`../sample/plan.ts`) and the reading pack (`../pack/pack.ts`)
- * — and two of them carried a comment promising to keep the wording identical
- * to the third, which is a promise nothing could enforce. It lives in the leaf
- * all three already import, because the failure this repo has actually shipped
- * is four copies of an enumeration `catch` that looked identical for years
- * while a fix landed in one of them: a `--sample` run refusing a missing spec
- * with older advice than a bare run gives is the same defect, one flag wide.
+ * reading list (`../sample/plan.ts`), both now through `verifyAxes` below, and
+ * the reading pack (`../pack/pack.ts`) — and two of them carried a comment
+ * promising to keep the wording identical to the third, which is a promise
+ * nothing could enforce. It lives in the leaf all three already import,
+ * because the failure this repo has actually shipped is four copies of an
+ * enumeration `catch` that looked identical for years while a fix landed in
+ * one of them: a `--sample` run refusing a missing spec with older advice than
+ * a bare run gives is the same defect, one flag wide.
  */
 export function noLivingSpecMessage(specPath, service) {
     return `No living spec at ${specPath}. Run \`loam adopt\` for '${service}' first.`;
 }
+/**
+ * The axis walk the stamp (`../run.ts`) and the reading list
+ * (`../sample/plan.ts`) both make, spelled once: spec.md is required,
+ * arch.spec.md rides when it exists, and one file that cannot be verified
+ * refuses the walk before the next is read — so a stamp writes nothing and a
+ * person is asked to read nothing.
+ *
+ * Walked by name rather than accumulated in a loop, because every caller
+ * needs to know WHICH file it is holding — the required one or the optional
+ * one — and a loop can only say that positionally. Sequential, not
+ * Promise.all: each verification hashes a whole source tree through the
+ * batched digest, and two of those in flight at once doubles the file
+ * descriptors that batching exists to bound. Two files.
+ */
+export async function verifyAxes(req) {
+    const paths = await locateServicePaths(req.docsDir, req.service);
+    if (!existsSync(paths.spec)) {
+        return { ok: false, code: "unknown-target", message: noLivingSpecMessage(paths.spec, req.service) };
+    }
+    const [specAxis, archAxis] = SPEC_AXES;
+    const spec = await verifySpec(req, paths[specAxis.key], specAxis.file);
+    if (!spec.ok)
+        return spec;
+    if (!existsSync(paths[archAxis.key]))
+        return { ok: true, spec, arch: null };
+    const arch = await verifySpec(req, paths[archAxis.key], archAxis.file);
+    return arch.ok ? { ok: true, spec, arch } : arch;
+}
 /**
  * The per-file half of the refusal discipline: everything vouch cannot verify
  * about ONE spec file, checked the same way for spec.md and arch.spec.md.

package/dist/commands/vouch/vet/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../../src/commands/vouch/vet/verify.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Does this spec still describe the code it points at?\n *\n * One spec, read against the sources it declares. It answers only about what it\n * could check, and says which sources it skipped — a vouch over a spec whose\n * sources could not be read would be the claim this command exists to prevent.\n */\nimport { listField, parseFrontmatter } from \"../../../core/document/frontmatter.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { missingSources, patternSources, unsafeSources } from \"../../../core/provenance/sources.js\";\nimport { emptySourcesMessage, sourcesDigest, type SourceIndexEntry } from \"../../../core/provenance/stamp.js\";\nimport type { SkippedSource } from \"../../../core/provenance/walk.js\";\nimport { NotUtf8Error, readUtf8 } from \"../../../core/staging/writes.js\";\n\nexport interface VerifiedSpec {\n  ok: true;\n  path: string;\n  file: string;\n  /** The file exactly as read — what the stamp is applied to. */\n  raw: string;\n  sources: string[];\n  digest: string;\n  /** Per-file shas, in digest order — what `sources_files` is stamped from. */\n  index: SourceIndexEntry[];\n  skipped: SkippedSource[];\n}\n\n/**\n * The two facts the vetting reads — not the whole VouchRequest, because the\n * reading pack (`../pack/pack.ts`) asks the same questions with no date or\n * identity to offer: a pack stamps nothing.\n */\nexport interface SpecVetting {\n  service: PathableService;\n  repoDir: string;\n}\n\n/**\n * The refusal half, spelled here rather than imported from `../contract.ts`:\n * this module is a LEAF two sibling consumers share — `run.ts` (the stamp) and\n * `pack/pack.ts` (the worklist) — which is why it lives in its own package,\n * and an import from the vouch package above it would close the exact\n * package-graph cycle the move exists to avoid. The codes are a subset of\n * VouchOutcome's refusal codes, so run.ts returns one of these unchanged.\n */\nexport interface SpecRefusal {\n  ok: false;\n  code: \"sources-absent\" | \"sources-path-missing\" | \"repository-unavailable\";\n  message: string;\n}\n\n/**\n * \"There is no living spec here\", in one sentence.\n *\n * Three callers reach this state independently — the stamp (`../run.ts`), the\n * reading list (`../sample/plan.ts`) and the reading pack (`../pack/pack.ts`)\n * — and two of them carried a comment promising to keep the wording identical\n * to the third, which is a promise nothing could enforce. It lives in the leaf\n * all three already import, because the failure this repo has actually shipped\n * is four copies of an enumeration `catch` that looked identical for years\n * while a fix landed in one of them: a `--sample` run refusing a missing spec\n * with older advice than a bare run gives is the same defect, one flag wide.\n */\nexport function noLivingSpecMessage(specPath: string, service: string): string {\n  return `No living spec at ${specPath}. Run \\`loam adopt\\` for '${service}' first.`;\n}\n\n/**\n * The per-file half of the refusal discipline: everything vouch cannot verify\n * about ONE spec file, checked the same way for spec.md and arch.spec.md.\n */\nexport async function verifySpec(\n  req: SpecVetting,\n  path: string,\n  file: string,\n): Promise<VerifiedSpec | SpecRefusal> {\n  // Through readUtf8, so the round trip below is exact: the stamp is computed\n  // from `raw` and the race check compares `Buffer.from(raw)` against the bytes\n  // on disk, which only agree if the file decoded without substitutions. A\n  // non-UTF-8 spec is refused by name rather than stamped as verified with\n  // every undecodable byte replaced. Refused HERE rather than left to the CLI's\n  // top-level handler, which would report a diagnosable state as `internal`.\n  // What it replaces is a diagnosis that was worse than none: a UTF-16 spec\n  // decoded to a document with no frontmatter loam could find, so vouch refused\n  // it as `sources-absent` — \"names no sources\" — over a file whose `sources:`\n  // line is right there.\n  let raw: string;\n  try {\n    raw = await readUtf8(path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8Error)) throw err;\n    return {\n      ok: false,\n      code: \"repository-unavailable\",\n      message: `${req.service}: ${file} cannot be vouched for — ${err.message}`,\n    };\n  }\n  const fm = parseFrontmatter(raw);\n  // Before any sources reasoning: a header that does not parse hides whatever\n  // fields the author wrote, so \"names no sources\" would be a false diagnosis —\n  // and if the file ever reached the stamp, withFrontmatterFields' rule for\n  // unreadable headers is replace-don't-merge, which would silently discard the\n  // author's owner/service/sources lines. Refuse before the write path can see\n  // the file. The code stays `sources-absent` — for vouch's purposes the\n  // sources ARE unreadable-hence-absent, and the message carries the real\n  // diagnosis — rather than minting a new ErrorCode for one refusal.\n  if (fm.malformed) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message:\n        `${req.service}: ${file} has a frontmatter block that cannot be read as YAML — ` +\n        `its fields (\\`sources\\` included) are unreadable, and stamping would rewrite the header wholesale, ` +\n        `losing what the author wrote. Fix the YAML between the \\`---\\` fences ` +\n        `(\\`loam validate\\` reports it as \\`frontmatter.malformed\\`), then re-run.`,\n    };\n  }\n  const sources = listField(fm, \"sources\");\n  if (sources.length === 0) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message: `${req.service}: ${file} names no sources — there is nothing to vouch it against. Add \\`sources:\\` naming the code it was written from.`,\n    };\n  }\n\n  // spec.md's refusals predate the second axis and keep their exact wording;\n  // where they did not name the file, only the newer axis adds it.\n  const label = file === \"spec.md\" ? req.service : `${req.service}: ${file}`;\n\n  // Before the existence check: a pattern is not a path that \"does not exist\",\n  // it is an entry loam no longer reads at all, and the refusal has to say so.\n  const patterns = patternSources(sources);\n  if (patterns.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(\", \")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it). A stamp over a pattern would vouch for a file set nobody can be sure of.`,\n    };\n  }\n\n  const unsafe = unsafeSources(req.repoDir, sources);\n  if (unsafe.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(\", \")}. Sources must be relative paths contained by this repository, including through symlinks; vouch will not hash files outside it.`,\n    };\n  }\n\n  const missing = missingSources(req.repoDir, sources);\n  if (missing.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(\", \")}. Vouching now would stamp a claim about code that is not there.`,\n    };\n  }\n\n  const { digest, index, skipped } = await sourcesDigest(req.repoDir, sources);\n  if (index.length === 0) {\n    // A directory that exists but holds no files — or only ones the walk leaves\n    // out: dot-entries, `node_modules`, anything the repository itself ignores.\n    // The paths \"resolve\", but a digest over nothing never changes, so the stamp\n    // would read as current forever. The sentence comes from provenance/stamp.ts so\n    // that `loam validate` can grade the same state in the same words instead of\n    // going green on a document this command refuses.\n    return { ok: false, code: \"sources-absent\", message: emptySourcesMessage(label, sources) };\n  }\n  return { ok: true, path, file, raw, sources, digest, index, skipped };\n}\n"]}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../../src/commands/vouch/vet/verify.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Does this spec still describe the code it points at?\n *\n * One spec, read against the sources it declares. It answers only about what it\n * could check, and says which sources it skipped — a vouch over a spec whose\n * sources could not be read would be the claim this command exists to prevent.\n */\nimport { existsSync } from \"node:fs\";\nimport { listField, parseFrontmatter } from \"../../../core/document/frontmatter.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { missingSources, patternSources, unsafeSources } from \"../../../core/provenance/sources.js\";\nimport { emptySourcesMessage, sourcesDigest, type SourceIndexEntry } from \"../../../core/provenance/stamp.js\";\nimport type { SkippedSource } from \"../../../core/provenance/walk.js\";\nimport { SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport { NotUtf8Error, readUtf8 } from \"../../../core/staging/writes.js\";\n\n/** A spec-axis file whose sources all check out, carrying what the stamp needs. */\nexport interface VerifiedSpec {\n  ok: true;\n  path: string;\n  file: string;\n  /** The file exactly as read — what the stamp is applied to. */\n  raw: string;\n  sources: string[];\n  digest: string;\n  /** Per-file shas, in digest order — what `sources_files` is stamped from. */\n  index: SourceIndexEntry[];\n  skipped: SkippedSource[];\n}\n\n/**\n * The two facts the vetting reads — not the whole VouchRequest, because the\n * reading pack (`../pack/pack.ts`) asks the same questions with no date or\n * identity to offer: a pack stamps nothing.\n */\nexport interface SpecVetting {\n  service: PathableService;\n  repoDir: string;\n}\n\n/**\n * The refusal half, spelled here rather than imported from `../contract.ts`:\n * this module is a LEAF two sibling consumers share — `run.ts` (the stamp) and\n * `pack/pack.ts` (the worklist) — which is why it lives in its own package,\n * and an import from the vouch package above it would close the exact\n * package-graph cycle the move exists to avoid. The codes are a subset of\n * VouchOutcome's refusal codes, so run.ts returns one of these unchanged.\n */\nexport interface SpecRefusal {\n  ok: false;\n  code: \"sources-absent\" | \"sources-path-missing\" | \"repository-unavailable\";\n  message: string;\n}\n\n/**\n * \"There is no living spec here\", in one sentence.\n *\n * Three callers reach this state independently — the stamp (`../run.ts`), the\n * reading list (`../sample/plan.ts`), both now through `verifyAxes` below, and\n * the reading pack (`../pack/pack.ts`) — and two of them carried a comment\n * promising to keep the wording identical to the third, which is a promise\n * nothing could enforce. It lives in the leaf all three already import,\n * because the failure this repo has actually shipped is four copies of an\n * enumeration `catch` that looked identical for years while a fix landed in\n * one of them: a `--sample` run refusing a missing spec with older advice than\n * a bare run gives is the same defect, one flag wide.\n */\nexport function noLivingSpecMessage(specPath: string, service: string): string {\n  return `No living spec at ${specPath}. Run \\`loam adopt\\` for '${service}' first.`;\n}\n\n/** Every spec-axis file of one service, verified: spec.md always, arch.spec.md when it exists. */\nexport interface VerifiedAxes {\n  ok: true;\n  spec: VerifiedSpec;\n  arch: VerifiedSpec | null;\n}\n\n/** The walk's refusals: one file's vetting, or no spec.md to vet at all. */\nexport type AxesRefusal = SpecRefusal | { ok: false; code: \"unknown-target\"; message: string };\n\n/**\n * The axis walk the stamp (`../run.ts`) and the reading list\n * (`../sample/plan.ts`) both make, spelled once: spec.md is required,\n * arch.spec.md rides when it exists, and one file that cannot be verified\n * refuses the walk before the next is read — so a stamp writes nothing and a\n * person is asked to read nothing.\n *\n * Walked by name rather than accumulated in a loop, because every caller\n * needs to know WHICH file it is holding — the required one or the optional\n * one — and a loop can only say that positionally. Sequential, not\n * Promise.all: each verification hashes a whole source tree through the\n * batched digest, and two of those in flight at once doubles the file\n * descriptors that batching exists to bound. Two files.\n */\nexport async function verifyAxes(req: SpecVetting & { docsDir: DocsDir }): Promise<VerifiedAxes | AxesRefusal> {\n  const paths = await locateServicePaths(req.docsDir, req.service);\n  if (!existsSync(paths.spec)) {\n    return { ok: false, code: \"unknown-target\", message: noLivingSpecMessage(paths.spec, req.service) };\n  }\n  const [specAxis, archAxis] = SPEC_AXES;\n  const spec = await verifySpec(req, paths[specAxis.key], specAxis.file);\n  if (!spec.ok) return spec;\n  if (!existsSync(paths[archAxis.key])) return { ok: true, spec, arch: null };\n  const arch = await verifySpec(req, paths[archAxis.key], archAxis.file);\n  return arch.ok ? { ok: true, spec, arch } : arch;\n}\n\n/**\n * The per-file half of the refusal discipline: everything vouch cannot verify\n * about ONE spec file, checked the same way for spec.md and arch.spec.md.\n */\nexport async function verifySpec(\n  req: SpecVetting,\n  path: string,\n  file: string,\n): Promise<VerifiedSpec | SpecRefusal> {\n  // Through readUtf8, so the round trip below is exact: the stamp is computed\n  // from `raw` and the race check compares `Buffer.from(raw)` against the bytes\n  // on disk, which only agree if the file decoded without substitutions. A\n  // non-UTF-8 spec is refused by name rather than stamped as verified with\n  // every undecodable byte replaced. Refused HERE rather than left to the CLI's\n  // top-level handler, which would report a diagnosable state as `internal`.\n  // What it replaces is a diagnosis that was worse than none: a UTF-16 spec\n  // decoded to a document with no frontmatter loam could find, so vouch refused\n  // it as `sources-absent` — \"names no sources\" — over a file whose `sources:`\n  // line is right there.\n  let raw: string;\n  try {\n    raw = await readUtf8(path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8Error)) throw err;\n    return {\n      ok: false,\n      code: \"repository-unavailable\",\n      message: `${req.service}: ${file} cannot be vouched for — ${err.message}`,\n    };\n  }\n  const fm = parseFrontmatter(raw);\n  // Before any sources reasoning: a header that does not parse hides whatever\n  // fields the author wrote, so \"names no sources\" would be a false diagnosis —\n  // and if the file ever reached the stamp, withFrontmatterFields' rule for\n  // unreadable headers is replace-don't-merge, which would silently discard the\n  // author's owner/service/sources lines. Refuse before the write path can see\n  // the file. The code stays `sources-absent` — for vouch's purposes the\n  // sources ARE unreadable-hence-absent, and the message carries the real\n  // diagnosis — rather than minting a new ErrorCode for one refusal.\n  if (fm.malformed) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message:\n        `${req.service}: ${file} has a frontmatter block that cannot be read as YAML — ` +\n        `its fields (\\`sources\\` included) are unreadable, and stamping would rewrite the header wholesale, ` +\n        `losing what the author wrote. Fix the YAML between the \\`---\\` fences ` +\n        `(\\`loam validate\\` reports it as \\`frontmatter.malformed\\`), then re-run.`,\n    };\n  }\n  const sources = listField(fm, \"sources\");\n  if (sources.length === 0) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message: `${req.service}: ${file} names no sources — there is nothing to vouch it against. Add \\`sources:\\` naming the code it was written from.`,\n    };\n  }\n\n  // spec.md's refusals predate the second axis and keep their exact wording;\n  // where they did not name the file, only the newer axis adds it.\n  const label = file === \"spec.md\" ? req.service : `${req.service}: ${file}`;\n\n  // Before the existence check: a pattern is not a path that \"does not exist\",\n  // it is an entry loam no longer reads at all, and the refusal has to say so.\n  const patterns = patternSources(sources);\n  if (patterns.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(\", \")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it). A stamp over a pattern would vouch for a file set nobody can be sure of.`,\n    };\n  }\n\n  const unsafe = unsafeSources(req.repoDir, sources);\n  if (unsafe.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(\", \")}. Sources must be relative paths contained by this repository, including through symlinks; vouch will not hash files outside it.`,\n    };\n  }\n\n  const missing = missingSources(req.repoDir, sources);\n  if (missing.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(\", \")}. Vouching now would stamp a claim about code that is not there.`,\n    };\n  }\n\n  const { digest, index, skipped } = await sourcesDigest(req.repoDir, sources);\n  if (index.length === 0) {\n    // A directory that exists but holds no files — or only ones the walk leaves\n    // out: dot-entries, `node_modules`, anything the repository itself ignores.\n    // The paths \"resolve\", but a digest over nothing never changes, so the stamp\n    // would read as current forever. The sentence comes from provenance/stamp.ts so\n    // that `loam validate` can grade the same state in the same words instead of\n    // going green on a document this command refuses.\n    return { ok: false, code: \"sources-absent\", message: emptySourcesMessage(label, sources) };\n  }\n  return { ok: true, path, file, raw, sources, digest, index, skipped };\n}\n"]}