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

package/dist/commands/vouch/run.js

@@ -0,0 +1,285 @@
+/**
+ * The stamp itself: verify every spec, then write them all or none.
+ *
+ * Separate from the command because this half has nothing to say to a terminal.
+ * It refuses on any spec it cannot verify and stamps none of them — a vouch is
+ * a person's claim that the documents match the code, and a partial one would
+ * put that claim on files nobody checked.
+ *
+ * What lands in each file: `status`, `last_verified`, `vouched_by`,
+ * `sources_digest`, the `sources_files` index, `content_digest` — and
+ * `vouch_scope` when the person read a sample rather than the document — with
+ * every byte below the frontmatter left identical. Nothing is written unless
+ * all of it can be stamped truthfully for EVERY file: a half-stamp (verified
+ * with no digest behind it, or one file stamped and its sibling not) is
+ * exactly the claim this command exists to stop being possible, so every
+ * present file is verified before any is written, and the writing itself is
+ * staged and swapped in like archive's merge, so a failure between the pair's
+ * two writes rolls the first back instead of leaving it. The two digests are
+ * the two halves of one promise — `sources_digest` pins the code that was
+ * read, `content_digest` pins the words it was read against — so
+ * `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 { 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 { 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 { 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";
+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
+    // the backstop, but it changes files verification has already read, so the
+    // 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 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
+    // answer, and the sample they were shown was chosen from digests taken
+    // before that. If either digest moved — or a second axis file appeared —
+    // the sections they read are not the sections this stamp would claim, and
+    // `vouch_scope` would record a read that did not happen. Nothing is written.
+    const raced = req.sample === undefined ? null : sampleDrift(req.sample, verified, req.service);
+    if (raced !== null)
+        return { ok: false, code: "vouch-raced", message: raced };
+    const specPlan = planStamp(specVerified, req);
+    const archPlan = archVerified === null ? null : planStamp(archVerified, req);
+    const writes = [specPlan.write, ...(archPlan === null ? [] : [archPlan.write])];
+    // The slow half — reading specs, hashing sources, composing stamps — ran
+    // UNLOCKED above, so vouches for independent services do not serialise
+    // behind one repo-wide mutex. Only the commit window takes the docs lock:
+    // the same one archive, rebase and verify --record hold, in the waiting
+    // form, because two vouches for different services are both supposed to
+    // land. This is the lock the roadmap called missing: without it a vouch
+    // 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;
+    }
+    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);
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * The commit window: stage, compare against what verification read, journal,
+ * swap. Split from `vouch` so the lock's extent is visible in the code shape —
+ * everything in here holds it, nothing above does.
+ */
+async function commitStamp(req, plan, recovered) {
+    const { writes, specPlan, archPlan, verified } = plan;
+    const staged = await stageWrites(writes);
+    // One shared docs repo, ten service repos, and nothing stopping two of them
+    // from vouching at once. Between reading a spec and swapping the stamp in
+    // there is a window in which somebody else's vouch (or an editor, or a merge)
+    // can land in the same file — and because the new bytes were computed from
+    // the OLD ones, swapping them in would take that stamp back out without a
+    // word. `stageWrites` has already read what is on disk right now, so the
+    // check is a comparison, not another read: if the file is not what was
+    // verified, this run is describing a document that no longer exists.
+    // Bytes, not text: `stageWrites` reads the file as a Buffer (a string
+    // comparison against it is never equal, which made every vouch report
+    // `vouch-raced` and stamp nothing). A file that is GONE is still a race —
+    // `null` is not "empty", it is "the document this run described is not
+    // there any more".
+    // Joined by path, not by index: pairing the two lists positionally assumed
+    // `stageWrites` returns one entry per planned write in order — true today,
+    // promised nowhere, and a compare-and-set that silently compares the wrong
+    // pair would stamp over somebody else's vouch. A staged write no verified
+    // file claims has nothing to be compared against, so it counts as raced;
+    // fail-closed is the only safe direction here.
+    const verifiedByPath = new Map(verified.map((v) => [v.path, v]));
+    const raced = staged.filter((s) => {
+        const v = verifiedByPath.get(s.write.path);
+        return v === undefined || s.before === null || !s.before.equals(Buffer.from(v.raw, "utf8"));
+    });
+    if (raced.length > 0) {
+        // Nothing has swapped yet, so the rollback is only the temp files going
+        // away — the other writer's stamp is left exactly as it landed.
+        await rollbackStaged(staged);
+        return {
+            ok: false,
+            code: "vouch-raced",
+            message: `${req.service}: ${raced.map((s) => s.write.path).join(", ")} changed while this vouch was running — ` +
+                `another vouch or an edit landed first. Nothing was stamped: re-read the document and re-run.`,
+        };
+    }
+    // The journaled commit: intent fsynced before the first rename, so a kill
+    // between the pair's two swaps is recoverable instead of invisible — the
+    // exact half-stamped state the all-or-nothing verification exists to rule
+    // out used to be reachable through that one window. The codes are archive's,
+    // reused rather than minted: rolled back → nothing changed, re-running can
+    // work; incomplete → the files listed need a human.
+    const committed = await commitStaged({
+        root: req.docsDir,
+        command: "vouch",
+        // Runnable where vouch runs — the SERVICE repo, with --yes because the
+        // journal's reader may be unattended. Any other journaled docs-repo
+        // writer recovers this journal on its next run too.
+        rerun: `loam vouch --service ${req.service} --yes`,
+        target: req.service,
+    }, staged, "stamped");
+    if (!committed.ok) {
+        return committed.raced
+            ? {
+                ok: false,
+                code: "vouch-raced",
+                message: `${req.service}: a document changed while this vouch was committing — ` +
+                    `another writer landed first. Nothing was stamped: re-read and re-run.`,
+            }
+            : { ok: false, code: committed.code, message: committed.message };
+    }
+    return {
+        ok: true,
+        status: "verified",
+        lastVerified: req.today,
+        vouchedBy: req.vouchedBy,
+        recovered,
+        stamped: { spec: specPlan.stamped, archSpec: archPlan === null ? null : archPlan.stamped },
+    };
+}
+/**
+ * One verified file's share of the commit: the bytes to write, and the record
+ * of what was stamped into them. Kept beside each other because they are the
+ * same computation — the report must describe the file that was actually
+ * written, not a second guess at it.
+ */
+export function planStamp(v, req) {
+    // Two passes on purpose: `content_digest` hashes the body BELOW the
+    // frontmatter, and withFrontmatterFields promises that body byte-identical —
+    // so hashing after the first stamp and writing the hash in a second one
+    // yields a digest that is true of the file exactly as written. A re-vouch
+    // takes the same road and refreshes every field, this one included.
+    //
+    // The scope this file's stamp will carry — null both when the run is an
+    // ordinary vouch and when a sampled run's `--sample <n>` covered the whole
+    // file. Joined to the plan by FILENAME rather than taken positionally: the
+    // two axes are stamped by two separate calls, and a scope written onto the
+    // wrong file would claim a person read four sections of a document they
+    // never opened.
+    const planned = req.sample?.axes.find((axis) => axis.file === v.file);
+    // A verified file with no planned axis is unreachable — `sampleDrift`
+    // refuses that run before this line — and null is the safe direction if it
+    // ever were: a full stamp that CLEARS any prior scope, never one claiming a
+    // sample nobody was shown.
+    const scope = planned === undefined ? null : axisScope(planned);
+    const restamped = withFrontmatterFields(v.raw, {
+        status: "verified",
+        last_verified: req.today,
+        // WHO, beside when. Without it `status: verified` recorded that the word
+        // had been written and nothing about who wrote it, so a vouch and an
+        // agent's own draft left the same trace in the document — the one
+        // distinction this command exists to make.
+        vouched_by: req.vouchedBy,
+        sources_digest: v.digest,
+        // Beside the digest, what it was taken over. `sources_digest` alone can
+        // only ever say THAT the code moved; the next `loam validate` reads this
+        // back to say which files did.
+        sources_files: encodeSourceIndex(v.index),
+        // Beside `vouched_by`, never inside `status`: the rung string `vouched`
+        // and the status `verified` are a published contract, and a sampled read
+        // is not a fourth status — it is a qualification of this one.
+        ...(scope === null ? {} : { vouch_scope: encodeVouchScope(scope) }),
+    }, 
+    // A full vouch CLEARS any scope a previous sampled one left, rather than
+    // stranding a claim that would keep a fully-read document reading as
+    // partial forever. Removing a key that was never there is a no-op, so
+    // this rides on every run that is not itself sampling.
+    scope === null ? ["vouch_scope"] : []);
+    const bodyDigest = contentDigest(restamped);
+    return {
+        write: { path: v.path, content: withFrontmatterFields(restamped, { content_digest: bodyDigest }) },
+        stamped: {
+            path: v.path,
+            file: v.file,
+            digest: v.digest,
+            contentDigest: bodyDigest,
+            sources: v.sources,
+            files: v.index.length,
+            skipped: v.skipped,
+            vouchScope: scope,
+        },
+    };
+}
+/** 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

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

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

@@ -0,0 +1,125 @@
+/**
+ * The pre-pass behind `loam vouch --sample <n>`: decide, before anyone is
+ * asked anything, which sections of which files this vouch will actually
+ * cover.
+ *
+ * It has to happen before the confirmation because a sampled vouch's question
+ * is different in kind — "have you read THESE four sections", not "have you
+ * read the code" — and a question that names nothing is the reflex this
+ * 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.
+ *
+ * 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
+ * content-derived, and `run.ts` spends the second walk anyway — what the
+ * 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 { 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";
+/** 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 };
+}
+/**
+ * What moved between the reading list and the stamp, as a phrase for the
+ * refusal — or null when the plan and the fresh verification describe the same
+ * documents.
+ *
+ * Joined by FILENAME both ways, and both directions matter: a plan entry with
+ * no verified file means an axis vanished mid-read, a verified file with no
+ * plan entry means one appeared and nobody was shown it. Comparing counts, or
+ * zipping the two lists, would call the second case fine.
+ *
+ * The digests, not the bytes: `content_digest` and `sources_digest` are the
+ * seed's own inputs, so a change in either is exactly a change in which
+ * sections a sample would pick. It lives here rather than in `run.ts` because
+ * it is a question about the PLAN — whether the reading list still describes
+ * these files — and the answer has to be computed the same way the plan was.
+ */
+export function sampleDrift(plan, verified, service) {
+    const now = new Map(verified.map((v) => [v.file, v]));
+    const moved = plan.axes
+        .filter((axis) => {
+        const v = now.get(axis.file);
+        return v === undefined || contentDigest(v.raw) !== axis.contentDigest || v.digest !== axis.sourcesDigest;
+    })
+        .map((axis) => axis.file);
+    const planned = new Set(plan.axes.map((axis) => axis.file));
+    const appeared = verified.filter((v) => !planned.has(v.file)).map((v) => v.file);
+    const files = [...moved, ...appeared];
+    if (files.length === 0)
+        return null;
+    // The whole sentence, not the file list: `run.ts` returns it verbatim under
+    // `vouch-raced`, and the diagnosis — which is about a READING window nothing
+    // locks — belongs beside the check that can explain it.
+    return (`${service}: ${files.join(", ")} changed while you were reading the sample — the sections you were shown are ` +
+        `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.
+ */
+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 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;
+        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
+        // seed's inputs and the sampled text describe one document.
+        const body = rawBody(vetted.raw);
+        const sample = planSample({
+            service: req.service,
+            contentDigest: digest,
+            sourcesDigest: vetted.digest,
+            body,
+            n: req.n,
+        });
+        const base = {
+            file: axis.file,
+            path,
+            contentDigest: digest,
+            sourcesDigest: vetted.digest,
+            of: sample.of,
+            // The header's line count, by subtraction rather than a second parse:
+            // `rawBody` is the one definition of where the body starts, and asking
+            // it twice is how the two answers drift.
+            lineOffset: vetted.raw.slice(0, vetted.raw.length - body.length).split("\n").length - 1,
+            sources: { entries: vetted.sources, files: vetted.index.length },
+        };
+        axes.push(sample.picked.length >= sample.of
+            ? { ...base, mode: "full" }
+            : { ...base, mode: "sampled", seed: sample.seed, picked: sample.picked });
+    }
+    return { ok: true, plan: { n: req.n, axes } };
+}
+//# sourceMappingURL=plan.js.map

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

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

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"]}