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

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

@@ -0,0 +1,109 @@
+/**
+ * What a person is shown before they answer a sampled vouch's question, and
+ * the additive `--json` shape of what it stamped.
+ *
+ * The reading list is the whole interface of `--sample <n>`: the sections
+ * picked, where they start, the preamble that is always read, and — said
+ * plainly, before the prompt rather than after the stamp — that the sections
+ * NOT listed will have been read by nobody, and what every later surface will
+ * say about that. A flag that quietly reduces assurance would be a bad trade;
+ * one that states the reduction to the person making it is the trade this
+ * feature is.
+ *
+ * Kept out of `vouch.ts` because that file is the flag boundary and is at its
+ * line limit, and out of `plan.ts` because a derivation that prints cannot be
+ * called by the reading pack, which renders the same sample its own way.
+ */
+import { plural } from "../../policy/format.js";
+/** `spec.md:42` — a body-relative section line put back on the file it came from. */
+function sectionAt(axis, line) {
+    return `${axis.file}:${line + axis.lineOffset}`;
+}
+/**
+ * The sampled claim in one sentence, for the reading list and the prompt: what
+ * will be stamped, and what every later reader will therefore say.
+ */
+function claim(axis, service) {
+    return (`${axis.file} will be stamped \`vouch_scope: sampled ${axis.picked.length}/${axis.of} seed=${axis.seed}\` — ` +
+        `the other ${plural(axis.of - axis.picked.length, "section")} will have been read by nobody. \`loam list\` shows ` +
+        `it as \`vouched (sampled)\` and \`loam validate\` reports \`sources.sampled-vouch\` until a person runs a full ` +
+        `\`loam vouch --service ${service}\`.`);
+}
+/**
+ * The reading list, printed before the confirmation. Text mode only — a
+ * `--json` run cannot be asked a question at all (`vouch-unattended`), so
+ * there is nobody on the other end of this list.
+ */
+export function printReadingList(plan, service) {
+    console.log(`\n${service} — sampled vouch: ${plural(plan.n, "section")} per spec file. Read what is listed here.\n`);
+    for (const axis of plan.axes) {
+        if (axis.mode === "full") {
+            // Said, not skipped: somebody who asked for a sample of four and got the
+            // whole document needs to know which of the two they are vouching for.
+            console.log(`  ${axis.file} — ${plural(axis.of, "section")}, at or under the sample: the whole file is the read, ` +
+                `and it is stamped as an ordinary vouch with no scope.\n`);
+            continue;
+        }
+        console.log(`  ${axis.file} — ${axis.picked.length} of ${plural(axis.of, "section")}, seed=${axis.seed}`);
+        console.log(`      the preamble above the first heading — always read, never part of the count`);
+        for (const section of axis.picked)
+            console.log(`      ${sectionAt(axis, section.line)}  ${section.heading}`);
+        // The FULL declared sources, deliberately not a sample of them: nothing in
+        // loam maps a source file to a doc section, and inventing that mapping
+        // ("these files back those sections") is exactly the meaning-derivation
+        // this tool refuses to do. The sample is of sections; the digest still
+        // covers every source, and so does the claim.
+        console.log(`      sources — ${axis.sources.entries.length} entr${axis.sources.entries.length === 1 ? "y" : "ies"}, ${plural(axis.sources.files, "file")}, all of them under the stamp:`);
+        for (const entry of axis.sources.entries)
+            console.log(`          ${entry}`);
+        console.log("");
+    }
+    for (const axis of plan.axes)
+        if (axis.mode === "sampled")
+            console.log(`  ${claim(axis, service)}\n`);
+}
+/**
+ * The sampled half of the confirmation's own text, so the question a person
+ * answers names the same sections the list above it did.
+ */
+export function promptClaim(plan, service) {
+    // A type predicate, not a bare `.filter`: TypeScript does not narrow a union
+    // through `filter`, and the alternative at the two use sites below is a cast
+    // or a second impossible branch — both of which are a way to be wrong about
+    // which arm this is.
+    const sampled = plan.axes.filter((axis) => axis.mode === "sampled");
+    if (sampled.length === 0) {
+        return ("You asked for a sample, and it covers every section of every file — so this is an ordinary full vouch " +
+            "and nothing will record a partial read.");
+    }
+    return [
+        `You are vouching for a SAMPLE: ${sampled
+            .map((axis) => `${axis.file} ${axis.picked.length}/${axis.of}`)
+            .join(", ")}. Everything else stays unread, and the document will say so.`,
+        ...sampled.map((axis) => claim(axis, service)),
+    ].join("\n");
+}
+/**
+ * The additive `vouchScope` payload — the stamped scope plus the headings it
+ * chose, so a consumer never has to re-derive the sample to find out what was
+ * read. Null for a file vouched in full, because that IS the whole answer for
+ * one, and a consumer that omitted the key could not tell it from an older
+ * loam that never wrote one.
+ */
+export function scopeJson(scope, axis) {
+    if (scope === null)
+        return null;
+    return {
+        mode: "sampled",
+        sections: scope.sections,
+        of: scope.of,
+        seed: scope.seed,
+        // Joined by file at the call site; an axis that does not answer leaves the
+        // headings out rather than inventing them — the seed and the counts are
+        // still enough to recompute the list.
+        ...(axis === undefined || axis.mode !== "sampled"
+            ? {}
+            : { headings: axis.picked.map((section) => section.heading) }),
+    };
+}
+//# sourceMappingURL=print.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../../src/commands/vouch/sample/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a person is shown before they answer a sampled vouch's question, and\n * the additive `--json` shape of what it stamped.\n *\n * The reading list is the whole interface of `--sample <n>`: the sections\n * picked, where they start, the preamble that is always read, and — said\n * plainly, before the prompt rather than after the stamp — that the sections\n * NOT listed will have been read by nobody, and what every later surface will\n * say about that. A flag that quietly reduces assurance would be a bad trade;\n * one that states the reduction to the person making it is the trade this\n * feature is.\n *\n * Kept out of `vouch.ts` because that file is the flag boundary and is at its\n * line limit, and out of `plan.ts` because a derivation that prints cannot be\n * called by the reading pack, which renders the same sample its own way.\n */\nimport { plural } from \"../../policy/format.js\";\nimport type { VouchScope } from \"../../../core/provenance/sample/scope.js\";\nimport type { PlannedAxis, SamplePlan } from \"./plan.js\";\n\n/** `spec.md:42` — a body-relative section line put back on the file it came from. */\nfunction sectionAt(axis: PlannedAxis, line: number): string {\n  return `${axis.file}:${line + axis.lineOffset}`;\n}\n\n/**\n * The sampled claim in one sentence, for the reading list and the prompt: what\n * will be stamped, and what every later reader will therefore say.\n */\nfunction claim(axis: PlannedAxis & { mode: \"sampled\" }, service: string): string {\n  return (\n    `${axis.file} will be stamped \\`vouch_scope: sampled ${axis.picked.length}/${axis.of} seed=${axis.seed}\\` — ` +\n    `the other ${plural(axis.of - axis.picked.length, \"section\")} will have been read by nobody. \\`loam list\\` shows ` +\n    `it as \\`vouched (sampled)\\` and \\`loam validate\\` reports \\`sources.sampled-vouch\\` until a person runs a full ` +\n    `\\`loam vouch --service ${service}\\`.`\n  );\n}\n\n/**\n * The reading list, printed before the confirmation. Text mode only — a\n * `--json` run cannot be asked a question at all (`vouch-unattended`), so\n * there is nobody on the other end of this list.\n */\nexport function printReadingList(plan: SamplePlan, service: string): void {\n  console.log(`\\n${service} — sampled vouch: ${plural(plan.n, \"section\")} per spec file. Read what is listed here.\\n`);\n  for (const axis of plan.axes) {\n    if (axis.mode === \"full\") {\n      // Said, not skipped: somebody who asked for a sample of four and got the\n      // whole document needs to know which of the two they are vouching for.\n      console.log(\n        `  ${axis.file} — ${plural(axis.of, \"section\")}, at or under the sample: the whole file is the read, ` +\n          `and it is stamped as an ordinary vouch with no scope.\\n`,\n      );\n      continue;\n    }\n    console.log(`  ${axis.file} — ${axis.picked.length} of ${plural(axis.of, \"section\")}, seed=${axis.seed}`);\n    console.log(`      the preamble above the first heading — always read, never part of the count`);\n    for (const section of axis.picked) console.log(`      ${sectionAt(axis, section.line)}  ${section.heading}`);\n    // The FULL declared sources, deliberately not a sample of them: nothing in\n    // loam maps a source file to a doc section, and inventing that mapping\n    // (\"these files back those sections\") is exactly the meaning-derivation\n    // this tool refuses to do. The sample is of sections; the digest still\n    // covers every source, and so does the claim.\n    console.log(\n      `      sources — ${axis.sources.entries.length} entr${axis.sources.entries.length === 1 ? \"y\" : \"ies\"}, ${plural(axis.sources.files, \"file\")}, all of them under the stamp:`,\n    );\n    for (const entry of axis.sources.entries) console.log(`          ${entry}`);\n    console.log(\"\");\n  }\n  for (const axis of plan.axes) if (axis.mode === \"sampled\") console.log(`  ${claim(axis, service)}\\n`);\n}\n\n/**\n * The sampled half of the confirmation's own text, so the question a person\n * answers names the same sections the list above it did.\n */\nexport function promptClaim(plan: SamplePlan, service: string): string {\n  // A type predicate, not a bare `.filter`: TypeScript does not narrow a union\n  // through `filter`, and the alternative at the two use sites below is a cast\n  // or a second impossible branch — both of which are a way to be wrong about\n  // which arm this is.\n  const sampled = plan.axes.filter((axis): axis is PlannedAxis & { mode: \"sampled\" } => axis.mode === \"sampled\");\n  if (sampled.length === 0) {\n    return (\n      \"You asked for a sample, and it covers every section of every file — so this is an ordinary full vouch \" +\n      \"and nothing will record a partial read.\"\n    );\n  }\n  return [\n    `You are vouching for a SAMPLE: ${sampled\n      .map((axis) => `${axis.file} ${axis.picked.length}/${axis.of}`)\n      .join(\", \")}. Everything else stays unread, and the document will say so.`,\n    ...sampled.map((axis) => claim(axis, service)),\n  ].join(\"\\n\");\n}\n\n/**\n * The additive `vouchScope` payload — the stamped scope plus the headings it\n * chose, so a consumer never has to re-derive the sample to find out what was\n * read. Null for a file vouched in full, because that IS the whole answer for\n * one, and a consumer that omitted the key could not tell it from an older\n * loam that never wrote one.\n */\nexport function scopeJson(scope: VouchScope | null, axis: PlannedAxis | undefined): Record<string, unknown> | null {\n  if (scope === null) return null;\n  return {\n    mode: \"sampled\",\n    sections: scope.sections,\n    of: scope.of,\n    seed: scope.seed,\n    // Joined by file at the call site; an axis that does not answer leaves the\n    // headings out rather than inventing them — the seed and the counts are\n    // still enough to recompute the list.\n    ...(axis === undefined || axis.mode !== \"sampled\"\n      ? {}\n      : { headings: axis.picked.map((section) => section.heading) }),\n  };\n}\n"]}

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

@@ -0,0 +1,155 @@
+/**
+ * Does this spec still describe the code it points at?
+ *
+ * One spec, read against the sources it declares. It answers only about what it
+ * 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`), 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.
+ */
+export async function verifySpec(req, path, file) {
+    // Through readUtf8, so the round trip below is exact: the stamp is computed
+    // from `raw` and the race check compares `Buffer.from(raw)` against the bytes
+    // on disk, which only agree if the file decoded without substitutions. A
+    // non-UTF-8 spec is refused by name rather than stamped as verified with
+    // every undecodable byte replaced. Refused HERE rather than left to the CLI's
+    // top-level handler, which would report a diagnosable state as `internal`.
+    // What it replaces is a diagnosis that was worse than none: a UTF-16 spec
+    // decoded to a document with no frontmatter loam could find, so vouch refused
+    // it as `sources-absent` — "names no sources" — over a file whose `sources:`
+    // line is right there.
+    let raw;
+    try {
+        raw = await readUtf8(path);
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8Error))
+            throw err;
+        return {
+            ok: false,
+            code: "repository-unavailable",
+            message: `${req.service}: ${file} cannot be vouched for — ${err.message}`,
+        };
+    }
+    const fm = parseFrontmatter(raw);
+    // Before any sources reasoning: a header that does not parse hides whatever
+    // fields the author wrote, so "names no sources" would be a false diagnosis —
+    // and if the file ever reached the stamp, withFrontmatterFields' rule for
+    // unreadable headers is replace-don't-merge, which would silently discard the
+    // author's owner/service/sources lines. Refuse before the write path can see
+    // the file. The code stays `sources-absent` — for vouch's purposes the
+    // sources ARE unreadable-hence-absent, and the message carries the real
+    // diagnosis — rather than minting a new ErrorCode for one refusal.
+    if (fm.malformed) {
+        return {
+            ok: false,
+            code: "sources-absent",
+            message: `${req.service}: ${file} has a frontmatter block that cannot be read as YAML — ` +
+                `its fields (\`sources\` included) are unreadable, and stamping would rewrite the header wholesale, ` +
+                `losing what the author wrote. Fix the YAML between the \`---\` fences ` +
+                `(\`loam validate\` reports it as \`frontmatter.malformed\`), then re-run.`,
+        };
+    }
+    const sources = listField(fm, "sources");
+    if (sources.length === 0) {
+        return {
+            ok: false,
+            code: "sources-absent",
+            message: `${req.service}: ${file} names no sources — there is nothing to vouch it against. Add \`sources:\` naming the code it was written from.`,
+        };
+    }
+    // spec.md's refusals predate the second axis and keep their exact wording;
+    // where they did not name the file, only the newer axis adds it.
+    const label = file === "spec.md" ? req.service : `${req.service}: ${file}`;
+    // Before the existence check: a pattern is not a path that "does not exist",
+    // it is an entry loam no longer reads at all, and the refusal has to say so.
+    const patterns = patternSources(sources);
+    if (patterns.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            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.`,
+        };
+    }
+    const unsafe = unsafeSources(req.repoDir, sources);
+    if (unsafe.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            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.`,
+        };
+    }
+    const missing = missingSources(req.repoDir, sources);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(", ")}. Vouching now would stamp a claim about code that is not there.`,
+        };
+    }
+    const { digest, index, skipped } = await sourcesDigest(req.repoDir, sources);
+    if (index.length === 0) {
+        // A directory that exists but holds no files — or only ones the walk leaves
+        // out: dot-entries, `node_modules`, anything the repository itself ignores.
+        // The paths "resolve", but a digest over nothing never changes, so the stamp
+        // would read as current forever. The sentence comes from provenance/stamp.ts so
+        // that `loam validate` can grade the same state in the same words instead of
+        // going green on a document this command refuses.
+        return { ok: false, code: "sources-absent", message: emptySourcesMessage(label, sources) };
+    }
+    return { ok: true, path, file, raw, sources, digest, index, skipped };
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +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 { 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"]}

package/dist/commands/vouch/vouch.js

@@ -0,0 +1,169 @@
+import { configOrRefuse, fail, NO_SERVICE_MESSAGE } from "../../core/envelope/json.js";
+import { gitIdentity } from "../../core/provenance/git.js";
+import { today } from "../../core/provenance/stamp.js";
+import { serviceTreePathOf } from "../../core/repo/service-target.js";
+import { runPack } from "./pack/print.js";
+import { confirmVouch } from "./prompt/confirm.js";
+import { emitStampJson, printStamp } from "./report.js";
+import { vouch } from "./run.js";
+import { buildSamplePlan } from "./sample/plan.js";
+import { printReadingList } from "./sample/print.js";
+export function registerVouch(program) {
+    program
+        .command("vouch")
+        .description("Vouch for a service's living specs: stamp spec.md, and arch.spec.md when present, verified against the code they describe")
+        .option("--service <id>", "service to vouch for (defaults to the configured service)")
+        .option("--yes", "skip the confirmation — required when stdin is not a terminal, and still records `vouched_by`")
+        .option("--pack", "print the re-vouch reading pack — the doc-body diff since the last vouch, the source files that moved, and the sections already covered — then exit without vouching; read-only, nothing is stamped")
+        .option("--sample <n>", "vouch after reading a deterministic sample of <n> sections per spec file — the stamp records `vouch_scope: sampled`, `loam list` shows `vouched (sampled)`, and `loam validate` reports `sources.sampled-vouch` until a full vouch clears it")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts) => {
+        const json = opts.json === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+        }
+        // Vouching hashes the code the doc was written from, so it can only run
+        // where that code is. From anywhere else the paths are someone else's.
+        //
+        // TWO conditions, two codes, and the split is the whole point. Both used
+        // to answer `invalid-option`, whose `loam explain` row says the
+        // invocation itself is wrong — contradictory flags, a mistyped one, a
+        // value that cannot be right. Here the invocation is perfectly correct
+        // and the REPOSITORY is the wrong one, so that code sent a user whose
+        // flags were fine off to re-read their flags, and left CI and agents
+        // unable to tell "run this in the service repo" from "you typed the flag
+        // wrong". `loam verify --record --service` already draws exactly this
+        // line for exactly this reason (see commands/verify/verify.ts); vouch
+        // and gherkin now answer the same pair, so a caller branching on
+        // `error.code` gets one answer from all three. The messages are
+        // unchanged — only the code moved.
+        if (config.service === undefined) {
+            return fail(json, "repository-unavailable", `Cannot vouch for '${service}' from here: this is not a service repo. \`sources\` resolve against the service's own repo — run it there.`);
+        }
+        if (config.service !== service) {
+            return fail(json, "service-mismatch", `Cannot vouch for '${service}' from here: this repo is '${config.service}'. \`sources\` resolve against the service's own repo — run it there.`);
+        }
+        // The repo root, not the cwd — see the comment on `repoDir` below; the
+        // identity has to be asked of the same directory the sources resolve in,
+        // or a subdirectory with its own git config would answer for it.
+        const repoDir = config.root ?? process.cwd();
+        // The flag's own grammar, before anything is read or hashed: `--sample`
+        // decides what the run CLAIMS, so a value nobody can read must not reach
+        // a stamp. Whole numbers only, and at least one — `0` is a vouch that
+        // read nothing, and there is already a way to record that (do not
+        // vouch). Checked before `--pack` below so a typo is refused the same
+        // way in both modes.
+        let sampleSize;
+        if (opts.sample !== undefined) {
+            if (!/^\d+$/.test(opts.sample.trim()) || Number(opts.sample) < 1) {
+                return fail(json, "invalid-option", `--sample expects a positive whole number of sections; got '${opts.sample}'. ` +
+                    "Nothing was read and nothing was stamped.");
+            }
+            sampleSize = Number(opts.sample);
+        }
+        // The reading pack: read-only, so it runs BEFORE — and instead of —
+        // every write-path gate below (identity, TTY, `--yes`, lock, journal),
+        // which all defend the stamp; pack/pack.ts's banner carries the full
+        // reasoning. It runs AFTER the wrong-repo gate above on purpose: the
+        // source delta resolves `sources` here. `--yes` does not compose — it
+        // is the unattended stamp, and a pack that stamped would defeat the
+        // read it just prescribed.
+        if (opts.pack === true) {
+            if (opts.yes === true) {
+                return fail(json, "invalid-option", "--pack is the reading list and --yes is the unattended stamp; a pack that immediately " +
+                    `stamped would defeat the read it just prescribed. Run --pack, read it, then \`loam vouch --service ${service}\`.`);
+            }
+            // `--sample` composes with the pack instead of conflicting with it:
+            // the pack is the reading list, and a sampled vouch's reading list is
+            // the sample. Passing it here makes the pack print the sections the
+            // subsequent `loam vouch --sample <n>` will stamp for — the same
+            // derivation from the same seed, so the two cannot prescribe
+            // different documents.
+            return runPack({ docsDir: config.docsDir, service: config.service, repoDir, json, sample: sampleSize });
+        }
+        // Who. Before any reading, because a run that cannot name a person has
+        // nothing to offer at the end of it and should not spend a digest finding
+        // that out.
+        const vouchedBy = await gitIdentity(repoDir);
+        if (vouchedBy === null) {
+            return fail(json, "vouch-unattributable", `Cannot vouch for '${service}': git names no \`user.email\` in ${repoDir}, so the stamp would ` +
+                "record a claim with nobody behind it — which is the one thing `status: verified` must not mean. " +
+                "Set it (`git config user.email you@example.com`) and re-run.");
+        }
+        // Whether a person is actually here — the gate the banner's "records a
+        // person" paragraph tells the history of. `vouch` is the only command in
+        // loam whose output is a claim about a HUMAN act — every other check is
+        // internal consistency, which fluent prose satisfies — and why an agent
+        // must not be able to make that claim for itself is recorded on the
+        // allowlist that no longer covers this command
+        // (core/agent/tools/dialects.ts). Nothing but a terminal or an explicit
+        // `--yes` gets past here.
+        const attended = opts.yes === true;
+        if (!attended) {
+            if (process.stdin.isTTY !== true) {
+                return fail(json, "vouch-unattended", `Cannot vouch for '${service}' with nothing on the other end of stdin: this command records that ` +
+                    "a PERSON read the code and says the document matches it, and nobody was asked. Run it from a " +
+                    "terminal, or pass --yes to state that you are standing behind it anyway — `vouched_by` records " +
+                    `${vouchedBy} either way.`);
+            }
+            // `--json` and a prompt do not compose: the envelope is one JSON
+            // document on stdout, and a question printed beside it is not parseable
+            // by the consumer that asked for it. A JSON caller is a program, so it
+            // gets the same answer a pipe does — say so with --yes.
+            if (json) {
+                return fail(json, "vouch-unattended", `Cannot vouch for '${service}' in --json mode without --yes: the confirmation is a question for a ` +
+                    "person, and it cannot be asked on a stream whose whole contract is one JSON document.");
+            }
+        }
+        // The reading list is built BEFORE the question and AFTER the attendance
+        // gates: a run that cannot ask anybody anything must not spend two
+        // source-tree digests finding that out, and a person must not be asked
+        // to confirm a sample nobody has shown them. Every refusal a vouch can
+        // raise about these documents fires in here, so it lands before the read
+        // rather than after it.
+        let sample;
+        if (sampleSize !== undefined) {
+            const built = await buildSamplePlan({ docsDir: config.docsDir, service: config.service, repoDir, n: sampleSize });
+            if (!built.ok)
+                return fail(json, built.code, built.message);
+            sample = built.plan;
+            if (!json)
+                printReadingList(sample, service);
+        }
+        const servicePath = await serviceTreePathOf(config.docsDir, service);
+        if (!attended && !(await confirmVouch({ service, vouchedBy, docsDir: config.docsDir, servicePath, sample }))) {
+            return fail(json, "vouch-declined", `Nothing was stamped for '${service}'.`);
+        }
+        const outcome = await vouch({
+            docsDir: config.docsDir,
+            // The guard above proved `service` IS `config.service`, and only the
+            // latter carries the parse (`loam.json`'s `service` field is validated
+            // at load). Same string, but only one spelling is pathable.
+            service: config.service,
+            vouchedBy,
+            // The repo root, not the cwd. `sources:` are spelled relative to the
+            // repository — that is what they mean in the frontmatter and what
+            // `loam validate` resolves them against — so vouching from a
+            // subdirectory used to report every real source as missing
+            // (`sources-path-missing`) and refuse the stamp. `config.root` is the
+            // directory loam.json was found in, which is the only definition of
+            // "this repo" that does not move with the caller.
+            repoDir,
+            today: today(new Date()),
+            // Absent for an ordinary vouch, which is what makes an ordinary vouch
+            // CLEAR a prior sample's scope rather than leave it standing.
+            ...(sample === undefined ? {} : { sample }),
+        });
+        if (!outcome.ok)
+            return fail(json, outcome.code, outcome.message);
+        const report = { service, docsDir: config.docsDir, outcome, ...(sample === undefined ? {} : { sample }) };
+        if (json)
+            return emitStampJson(report);
+        printStamp(report);
+    });
+}
+//# sourceMappingURL=vouch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vouch.js","sourceRoot":"","sources":["../../../src/commands/vouch/vouch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { configOrRefuse, fail, NO_SERVICE_MESSAGE } from \"../../core/envelope/json.js\";\nimport { gitIdentity } from \"../../core/provenance/git.js\";\nimport { today } from \"../../core/provenance/stamp.js\";\nimport { serviceTreePathOf } from \"../../core/repo/service-target.js\";\nimport { runPack } from \"./pack/print.js\";\nimport { confirmVouch } from \"./prompt/confirm.js\";\nimport { emitStampJson, printStamp } from \"./report.js\";\nimport { vouch } from \"./run.js\";\nimport { buildSamplePlan, type SamplePlan } from \"./sample/plan.js\";\nimport { printReadingList } from \"./sample/print.js\";\n\n/**\n * `loam vouch` — the human act SCHEMA.md has always described as \"promote draft\n * -> verified\".\n *\n * Everything else loam checks is internal consistency, and an agent writing\n * fluent prose satisfies all of it. This is the one command that records a\n * person: they read the code, they say the document matches it, and loam stamps\n * a digest of what they read — and a digest of the document they read it\n * against, so neither side can move quietly. From then on `loam validate` can\n * tell the difference between a document nobody has checked, one that still\n * matches the code, one the code has moved out from under, and one whose own\n * prose changed after the stamp.\n *\n * \"Records a person\" was, for two releases, a thing this file said and did not\n * do. There was no `vouched_by`, no identity of any kind and no interactive\n * gate, so an agent could run it twice unattended and stamp `verified` both\n * times — while the skill files loam generates pre-approved `Bash(loam:*)`,\n * which meant the agent that wrote the draft was permitted to promote it. Three\n * things close that, and none of them is a signature: the stamp carries git's\n * `user.email` (`vouched_by`), the run refuses without a terminal or an explicit\n * `--yes`, and the generated allowlist names loam's read-only and authoring\n * verbs one by one instead of all of them (core/agent/tools/dialects.ts). What that buys is\n * attribution and a deliberate act, not proof — git config is a text file. A\n * reviewer can now ask a named person what they read, which is the question\n * `status: verified` was silently answering with nobody.\n *\n * The stamp is only worth what it claims, so vouch refuses everything it cannot\n * actually verify — a frontmatter block that will not parse (whose fields\n * nobody can read, and whose rewrite would lose the author's lines), a spec\n * with no sources, a glob pattern (no longer supported), a source that is\n * gone, a directory holding no files, or a repo that is not this service's —\n * and refuses without writing anything.\n *\n * \"The document\" is every spec-axis file the service has: spec.md always, and\n * arch.spec.md beside it when present — same frontmatter conventions, same\n * stamp, one vouch. The refusal discipline is per file but the vouch is\n * all-or-nothing per service: one unverifiable file refuses the whole run, so\n * a `verified` service never means \"half-stamped\".\n */\n\ninterface VouchOptions {\n  service?: string;\n  yes?: boolean;\n  pack?: boolean;\n  /** `--sample <n>` as typed — a string until it is proved to be a whole number. */\n  sample?: string;\n  json?: boolean;\n}\n\nexport function registerVouch(program: Command): void {\n  program\n    .command(\"vouch\")\n    .description(\n      \"Vouch for a service's living specs: stamp spec.md, and arch.spec.md when present, verified against the code they describe\",\n    )\n    .option(\"--service <id>\", \"service to vouch for (defaults to the configured service)\")\n    .option(\n      \"--yes\",\n      \"skip the confirmation — required when stdin is not a terminal, and still records `vouched_by`\",\n    )\n    .option(\n      \"--pack\",\n      \"print the re-vouch reading pack — the doc-body diff since the last vouch, the source files that moved, and the sections already covered — then exit without vouching; read-only, nothing is stamped\",\n    )\n    .option(\n      \"--sample <n>\",\n      \"vouch after reading a deterministic sample of <n> sections per spec file — the stamp records `vouch_scope: sampled`, `loam list` shows `vouched (sampled)`, and `loam validate` reports `sources.sampled-vouch` until a full vouch clears it\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: VouchOptions) => {\n      const json = opts.json === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // Vouching hashes the code the doc was written from, so it can only run\n      // where that code is. From anywhere else the paths are someone else's.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); vouch\n      // and gherkin now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot vouch for '${service}' from here: this is not a service repo. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot vouch for '${service}' from here: this repo is '${config.service}'. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd — see the comment on `repoDir` below; the\n      // identity has to be asked of the same directory the sources resolve in,\n      // or a subdirectory with its own git config would answer for it.\n      const repoDir = config.root ?? process.cwd();\n\n      // The flag's own grammar, before anything is read or hashed: `--sample`\n      // decides what the run CLAIMS, so a value nobody can read must not reach\n      // a stamp. Whole numbers only, and at least one — `0` is a vouch that\n      // read nothing, and there is already a way to record that (do not\n      // vouch). Checked before `--pack` below so a typo is refused the same\n      // way in both modes.\n      let sampleSize: number | undefined;\n      if (opts.sample !== undefined) {\n        if (!/^\\d+$/.test(opts.sample.trim()) || Number(opts.sample) < 1) {\n          return fail(\n            json,\n            \"invalid-option\",\n            `--sample expects a positive whole number of sections; got '${opts.sample}'. ` +\n              \"Nothing was read and nothing was stamped.\",\n          );\n        }\n        sampleSize = Number(opts.sample);\n      }\n\n      // The reading pack: read-only, so it runs BEFORE — and instead of —\n      // every write-path gate below (identity, TTY, `--yes`, lock, journal),\n      // which all defend the stamp; pack/pack.ts's banner carries the full\n      // reasoning. It runs AFTER the wrong-repo gate above on purpose: the\n      // source delta resolves `sources` here. `--yes` does not compose — it\n      // is the unattended stamp, and a pack that stamped would defeat the\n      // read it just prescribed.\n      if (opts.pack === true) {\n        if (opts.yes === true) {\n          return fail(\n            json,\n            \"invalid-option\",\n            \"--pack is the reading list and --yes is the unattended stamp; a pack that immediately \" +\n              `stamped would defeat the read it just prescribed. Run --pack, read it, then \\`loam vouch --service ${service}\\`.`,\n          );\n        }\n        // `--sample` composes with the pack instead of conflicting with it:\n        // the pack is the reading list, and a sampled vouch's reading list is\n        // the sample. Passing it here makes the pack print the sections the\n        // subsequent `loam vouch --sample <n>` will stamp for — the same\n        // derivation from the same seed, so the two cannot prescribe\n        // different documents.\n        return runPack({ docsDir: config.docsDir, service: config.service, repoDir, json, sample: sampleSize });\n      }\n\n      // Who. Before any reading, because a run that cannot name a person has\n      // nothing to offer at the end of it and should not spend a digest finding\n      // that out.\n      const vouchedBy = await gitIdentity(repoDir);\n      if (vouchedBy === null) {\n        return fail(\n          json,\n          \"vouch-unattributable\",\n          `Cannot vouch for '${service}': git names no \\`user.email\\` in ${repoDir}, so the stamp would ` +\n            \"record a claim with nobody behind it — which is the one thing `status: verified` must not mean. \" +\n            \"Set it (`git config user.email you@example.com`) and re-run.\",\n        );\n      }\n\n      // Whether a person is actually here — the gate the banner's \"records a\n      // person\" paragraph tells the history of. `vouch` is the only command in\n      // loam whose output is a claim about a HUMAN act — every other check is\n      // internal consistency, which fluent prose satisfies — and why an agent\n      // must not be able to make that claim for itself is recorded on the\n      // allowlist that no longer covers this command\n      // (core/agent/tools/dialects.ts). Nothing but a terminal or an explicit\n      // `--yes` gets past here.\n      const attended = opts.yes === true;\n      if (!attended) {\n        if (process.stdin.isTTY !== true) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' with nothing on the other end of stdin: this command records that ` +\n              \"a PERSON read the code and says the document matches it, and nobody was asked. Run it from a \" +\n              \"terminal, or pass --yes to state that you are standing behind it anyway — `vouched_by` records \" +\n              `${vouchedBy} either way.`,\n          );\n        }\n        // `--json` and a prompt do not compose: the envelope is one JSON\n        // document on stdout, and a question printed beside it is not parseable\n        // by the consumer that asked for it. A JSON caller is a program, so it\n        // gets the same answer a pipe does — say so with --yes.\n        if (json) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' in --json mode without --yes: the confirmation is a question for a ` +\n              \"person, and it cannot be asked on a stream whose whole contract is one JSON document.\",\n          );\n        }\n      }\n\n      // The reading list is built BEFORE the question and AFTER the attendance\n      // gates: a run that cannot ask anybody anything must not spend two\n      // source-tree digests finding that out, and a person must not be asked\n      // to confirm a sample nobody has shown them. Every refusal a vouch can\n      // raise about these documents fires in here, so it lands before the read\n      // rather than after it.\n      let sample: SamplePlan | undefined;\n      if (sampleSize !== undefined) {\n        const built = await buildSamplePlan({ docsDir: config.docsDir, service: config.service, repoDir, n: sampleSize });\n        if (!built.ok) return fail(json, built.code, built.message);\n        sample = built.plan;\n        if (!json) printReadingList(sample, service);\n      }\n      const servicePath = await serviceTreePathOf(config.docsDir, service);\n      if (!attended && !(await confirmVouch({ service, vouchedBy, docsDir: config.docsDir, servicePath, sample }))) {\n        return fail(json, \"vouch-declined\", `Nothing was stamped for '${service}'.`);\n      }\n\n      const outcome = await vouch({\n        docsDir: config.docsDir,\n        // The guard above proved `service` IS `config.service`, and only the\n        // latter carries the parse (`loam.json`'s `service` field is validated\n        // at load). Same string, but only one spelling is pathable.\n        service: config.service,\n        vouchedBy,\n        // The repo root, not the cwd. `sources:` are spelled relative to the\n        // repository — that is what they mean in the frontmatter and what\n        // `loam validate` resolves them against — so vouching from a\n        // subdirectory used to report every real source as missing\n        // (`sources-path-missing`) and refuse the stamp. `config.root` is the\n        // directory loam.json was found in, which is the only definition of\n        // \"this repo\" that does not move with the caller.\n        repoDir,\n        today: today(new Date()),\n        // Absent for an ordinary vouch, which is what makes an ordinary vouch\n        // CLEAR a prior sample's scope rather than leave it standing.\n        ...(sample === undefined ? {} : { sample }),\n      });\n      if (!outcome.ok) return fail(json, outcome.code, outcome.message);\n\n      const report = { service, docsDir: config.docsDir, outcome, ...(sample === undefined ? {} : { sample }) };\n      if (json) return emitStampJson(report);\n      printStamp(report);\n    });\n}\n"]}