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

package/dist/core/provenance/gitq/vouched-ancestor.js

@@ -0,0 +1,179 @@
+/**
+ * Doc-body ancestry in the DOCS repo — the two git questions behind
+ * `loam vouch --pack`'s body delta: which commit last held the body a person
+ * vouched for (`findVouchedAncestor`), and what the file's diff from that
+ * commit to the working tree says (`bodyDiffText`). Read-only throughout:
+ * `rev-parse`/`log`/`show`/`diff`, no checkout, no temp writes.
+ *
+ * The mechanics are `core/diff/base-git.ts`'s to the letter — literally so:
+ * both import the one `gitText`/`GitAnswer`/`declineDetail` set from
+ * `../git.js`, so a hardening lands in both or in neither — but the doctrine
+ * is deliberately the OPPOSITE consequence. `loam diff` REFUSES when git
+ * cannot answer, because a silently empty base would report the whole fleet
+ * as added — a lie with a green exit code. The pack DEGRADES to "full read"
+ * instead: its output is a reading list, and for a reading list the
+ * conservative direction — read more, never less — is always honest, the same
+ * direction as provenance's existing hash-everything fallback. The shared
+ * helpers carry no verdict, so neither module can borrow the other's
+ * consequence by accident; each spells its own at its own call sites.
+ *
+ * The walk is BOUNDED at `ANCESTOR_WALK_CAP` commits. A vouched commit pushed
+ * past the cap by a very active docs repo degrades a legitimate incremental
+ * read to a full read — safe direction, and the `none` reason names the cap
+ * so the human understands why. Within the walk, one commit whose version of
+ * the file is absent (git answering "not here") is skipped; a git that stops
+ * answering mid-walk (spawn error, kill, timeout, output cap) aborts the whole
+ * search as `no-git` rather than letting 200 futile spawns each wait out the
+ * timeout.
+ */
+import { declineDetail, gitText } from "../git.js";
+import { contentDigest } from "../stamp.js";
+/**
+ * How many commits touching the file the ancestor search will read before
+ * declaring the vouched state unreachable. Past it the answer is `none` — a
+ * full read — with a reason that names the cap.
+ */
+const ANCESTOR_WALK_CAP = 200;
+/**
+ * How much diff text the pack will print. A body diff past this is not a
+ * reading list any more — the honest answer is "read the file", as `failed`.
+ */
+const MAX_DIFF_TEXT_CHARS = 1024 * 1024;
+/**
+ * The shared `gitText` (`../git.js`) with colour forced off. base-git's three
+ * questions (`rev-parse`/`ls-tree`/`show`) never colour, but this module runs
+ * `log` and `diff`, and a user's `color.ui = always` forces SGR escape
+ * sequences into their output even on a pipe — which would put terminal codes
+ * inside the `--json` payload's diff text and make the 40-hex-anchored log
+ * walk silently match nothing on exactly that machine. The flag lives here,
+ * not in the shared helper, because it is this module's need, not a property
+ * of asking git a question.
+ */
+async function gitPlain(docsDir, args) {
+    return gitText(docsDir, ["-c", "color.ui=false", ...args]);
+}
+/**
+ * The bytes this commit's blob would carry on a CRLF checkout. The stamped
+ * `content_digest` is byte-exact over the WORKING-TREE file (stamp.ts), while
+ * `git show` hands back the BLOB — and on a Windows checkout with
+ * `core.autocrlf=true` the blob is LF where every working-tree byte is CRLF,
+ * so the exact digest of the blob would never equal a stamp taken over the
+ * same content and every vouched ancestor would be invisible on exactly those
+ * machines. Same hazard, same direction as `core/verify/pins/pin.ts`'s
+ * `pinnedDigest`, resolved the inverse way because the stamp's recipe is
+ * published and cannot be re-normalized after the fact: instead of
+ * normalizing both sides, the search hashes each candidate twice — as the
+ * blob is, and as its CRLF checkout rendering — and a match on either is a
+ * match. Only lone LFs are rewritten, so a blob that already carries CRLFs
+ * (committed without the clean filter, hence byte-identical on disk) is
+ * covered by the exact hash.
+ */
+function checkoutRendering(text) {
+    return text.replace(/(?<!\r)\n/g, "\r\n");
+}
+/**
+ * The last commit in the docs repo's history whose version of `rel` (a
+ * docs-relative, `/`-separated path) has a body hashing to the stamped
+ * `content_digest` — newest first, because the reading list wants the
+ * SHORTEST honest diff, and any older commit holding the same bytes yields
+ * the same one.
+ */
+export async function findVouchedAncestor(docsDir, rel, stampedDigest) {
+    // Belt to the callers' braces: `rel` is derived from loam's own path
+    // spelling, never argv, but every spelled pathspec below rides an argv, so
+    // an option-shaped or empty value is refused here rather than parsed by
+    // git as a flag. Same reason base-git.ts refuses option-shaped refs.
+    if (rel.trim() === "" || rel.startsWith("-")) {
+        return { kind: "no-git", detail: `'${rel}' is not a path git can be asked about.` };
+    }
+    // `--show-prefix` first, and not decoration (base-git.ts proved this): a
+    // docs repo checked out as a subdirectory of a larger repository answers
+    // `show` only under that prefix, and a walk whose paths all miss would
+    // report "no vouched ancestor" about a history that holds one.
+    const where = await gitPlain(docsDir, ["rev-parse", "--show-prefix"]);
+    if (where.spawnError !== undefined || where.code !== 0) {
+        return { kind: "no-git", detail: declineDetail(where) };
+    }
+    const prefix = where.out.trim();
+    // The pathspec is cwd-relative (no prefix — `log` resolves it against the
+    // cwd, unlike `show`'s repo-root spelling below). `-n` is the walk's bound.
+    const log = await gitPlain(docsDir, [
+        "log", "-n", String(ANCESTOR_WALK_CAP), "--format=%H", "--", rel,
+    ]);
+    if (log.spawnError !== undefined || log.code !== 0 || log.overflowed) {
+        return { kind: "no-git", detail: declineDetail(log) };
+    }
+    // Only shas shaped like shas walk on — an unexpected line yields a shorter
+    // walk, never a malformed argv (the gitq/moves.ts token-anchoring rule).
+    const commits = log.out.split("\n").map((l) => l.trim()).filter((l) => /^[0-9a-f]{40}$/.test(l));
+    // Sequential on purpose: newest-first order is the answer's definition, and
+    // the walk stops at the first match — a fan-out would read history it does
+    // not need and could answer with an older commit than the newest match.
+    for (const commit of commits) {
+        const shown = await gitPlain(docsDir, ["show", `${commit}:${prefix}${rel}`]);
+        if (shown.spawnError !== undefined || shown.code === null) {
+            // Git stopped answering (not installed mid-walk, killed, timed out, or
+            // the output cap fired on a monstrous version). Abort rather than walk
+            // on: each further spawn could wait out the whole timeout, and a "none"
+            // built over commits nobody read would claim the history was searched.
+            return {
+                kind: "no-git",
+                detail: shown.overflowed
+                    ? `the file at ${commit.slice(0, 12)} exceeds the git output cap.`
+                    : declineDetail(shown),
+            };
+        }
+        // A real non-zero exit is git ANSWERING — the file is absent at this
+        // commit (renamed since, or the commit only deleted it). Skip it.
+        if (shown.code !== 0)
+            continue;
+        if (contentDigest(shown.out) === stampedDigest ||
+            contentDigest(checkoutRendering(shown.out)) === stampedDigest) {
+            return { kind: "found", commit, text: shown.out };
+        }
+    }
+    return {
+        kind: "none",
+        reason: commits.length < ANCESTOR_WALK_CAP
+            ? "body has no vouched ancestor in history"
+            : `body has no vouched ancestor in history — only the last ${ANCESTOR_WALK_CAP} commits touching the file were walked, and the vouched state may lie beyond them`,
+    };
+}
+/**
+ * The file's diff from its last vouched state: `git diff <commit> -- <rel>`,
+ * commit-to-working-tree, in the docs repo. The output is git's own — when a
+ * hand edit touched the frontmatter after the vouch, its hunks ride along,
+ * which is why the pack's prose says "the file's diff", never "the body's".
+ */
+export async function bodyDiffText(docsDir, commit, rel) {
+    // The commit came out of `findVouchedAncestor`'s own regex-vetted walk, but
+    // this function is exported API: re-vet, so no future caller can place an
+    // option-shaped string in the one argv slot that is not behind `--`.
+    if (!/^[0-9a-f]{40}$/.test(commit)) {
+        return { kind: "failed", reason: `'${commit}' is not a commit this diff can be asked about.` };
+    }
+    if (rel.trim() === "" || rel.startsWith("-")) {
+        return { kind: "failed", reason: `'${rel}' is not a path git can be asked about.` };
+    }
+    // `--no-optional-locks`: a commit-to-worktree diff may opportunistically
+    // refresh `.git/index`'s stat cache, which is a WRITE — small, benign, and
+    // exactly what a command documented as "writes nothing" must not do. The
+    // global flag tells git to skip any operation that would take a lock it
+    // does not strictly need. `--no-ext-diff --no-textconv` close the rest of
+    // the config surface: `diff.external` / a `.gitattributes` diff driver make
+    // `git diff` EXECUTE a user-configured program instead of printing a diff —
+    // an arbitrary write hazard on a read-only path, and output no machine
+    // consumer of `body.diff` could parse. The pack's diff is a machine
+    // artifact, not a terminal rendering; git's own plumbing flags say so.
+    const answer = await gitPlain(docsDir, [
+        "--no-optional-locks", "diff", "--no-ext-diff", "--no-textconv", commit, "--", rel,
+    ]);
+    if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {
+        return { kind: "failed", reason: declineDetail(answer) };
+    }
+    if (answer.out.length > MAX_DIFF_TEXT_CHARS) {
+        return { kind: "failed", reason: "the body diff exceeds the pack's print cap — read the file" };
+    }
+    return { kind: "ok", diff: answer.out };
+}
+//# sourceMappingURL=vouched-ancestor.js.map

package/dist/core/provenance/gitq/vouched-ancestor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vouched-ancestor.js","sourceRoot":"","sources":["../../../../src/core/provenance/gitq/vouched-ancestor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Doc-body ancestry in the DOCS repo — the two git questions behind\n * `loam vouch --pack`'s body delta: which commit last held the body a person\n * vouched for (`findVouchedAncestor`), and what the file's diff from that\n * commit to the working tree says (`bodyDiffText`). Read-only throughout:\n * `rev-parse`/`log`/`show`/`diff`, no checkout, no temp writes.\n *\n * The mechanics are `core/diff/base-git.ts`'s to the letter — literally so:\n * both import the one `gitText`/`GitAnswer`/`declineDetail` set from\n * `../git.js`, so a hardening lands in both or in neither — but the doctrine\n * is deliberately the OPPOSITE consequence. `loam diff` REFUSES when git\n * cannot answer, because a silently empty base would report the whole fleet\n * as added — a lie with a green exit code. The pack DEGRADES to \"full read\"\n * instead: its output is a reading list, and for a reading list the\n * conservative direction — read more, never less — is always honest, the same\n * direction as provenance's existing hash-everything fallback. The shared\n * helpers carry no verdict, so neither module can borrow the other's\n * consequence by accident; each spells its own at its own call sites.\n *\n * The walk is BOUNDED at `ANCESTOR_WALK_CAP` commits. A vouched commit pushed\n * past the cap by a very active docs repo degrades a legitimate incremental\n * read to a full read — safe direction, and the `none` reason names the cap\n * so the human understands why. Within the walk, one commit whose version of\n * the file is absent (git answering \"not here\") is skipped; a git that stops\n * answering mid-walk (spawn error, kill, timeout, output cap) aborts the whole\n * search as `no-git` rather than letting 200 futile spawns each wait out the\n * timeout.\n */\nimport { declineDetail, gitText, type GitAnswer } from \"../git.js\";\nimport { contentDigest } from \"../stamp.js\";\n\n/**\n * How many commits touching the file the ancestor search will read before\n * declaring the vouched state unreachable. Past it the answer is `none` — a\n * full read — with a reason that names the cap.\n */\nconst ANCESTOR_WALK_CAP = 200;\n\n/**\n * How much diff text the pack will print. A body diff past this is not a\n * reading list any more — the honest answer is \"read the file\", as `failed`.\n */\nconst MAX_DIFF_TEXT_CHARS = 1024 * 1024;\n\n/**\n * The shared `gitText` (`../git.js`) with colour forced off. base-git's three\n * questions (`rev-parse`/`ls-tree`/`show`) never colour, but this module runs\n * `log` and `diff`, and a user's `color.ui = always` forces SGR escape\n * sequences into their output even on a pipe — which would put terminal codes\n * inside the `--json` payload's diff text and make the 40-hex-anchored log\n * walk silently match nothing on exactly that machine. The flag lives here,\n * not in the shared helper, because it is this module's need, not a property\n * of asking git a question.\n */\nasync function gitPlain(docsDir: string, args: string[]): Promise<GitAnswer> {\n  return gitText(docsDir, [\"-c\", \"color.ui=false\", ...args]);\n}\n\n/**\n * The bytes this commit's blob would carry on a CRLF checkout. The stamped\n * `content_digest` is byte-exact over the WORKING-TREE file (stamp.ts), while\n * `git show` hands back the BLOB — and on a Windows checkout with\n * `core.autocrlf=true` the blob is LF where every working-tree byte is CRLF,\n * so the exact digest of the blob would never equal a stamp taken over the\n * same content and every vouched ancestor would be invisible on exactly those\n * machines. Same hazard, same direction as `core/verify/pins/pin.ts`'s\n * `pinnedDigest`, resolved the inverse way because the stamp's recipe is\n * published and cannot be re-normalized after the fact: instead of\n * normalizing both sides, the search hashes each candidate twice — as the\n * blob is, and as its CRLF checkout rendering — and a match on either is a\n * match. Only lone LFs are rewritten, so a blob that already carries CRLFs\n * (committed without the clean filter, hence byte-identical on disk) is\n * covered by the exact hash.\n */\nfunction checkoutRendering(text: string): string {\n  return text.replace(/(?<!\\r)\\n/g, \"\\r\\n\");\n}\n\nexport type AncestorSearch =\n  | {\n      kind: \"found\";\n      commit: string;\n      /** The file exactly as that commit holds it — what the section delta reads. */\n      text: string;\n    }\n  /** The walk completed and nothing matched — the honest verdict is a full read. */\n  | { kind: \"none\"; reason: string }\n  /** Git declined somewhere the walk could not continue past — also a full read. */\n  | { kind: \"no-git\"; detail: string };\n\n/**\n * The last commit in the docs repo's history whose version of `rel` (a\n * docs-relative, `/`-separated path) has a body hashing to the stamped\n * `content_digest` — newest first, because the reading list wants the\n * SHORTEST honest diff, and any older commit holding the same bytes yields\n * the same one.\n */\nexport async function findVouchedAncestor(\n  docsDir: string,\n  rel: string,\n  stampedDigest: string,\n): Promise<AncestorSearch> {\n  // Belt to the callers' braces: `rel` is derived from loam's own path\n  // spelling, never argv, but every spelled pathspec below rides an argv, so\n  // an option-shaped or empty value is refused here rather than parsed by\n  // git as a flag. Same reason base-git.ts refuses option-shaped refs.\n  if (rel.trim() === \"\" || rel.startsWith(\"-\")) {\n    return { kind: \"no-git\", detail: `'${rel}' is not a path git can be asked about.` };\n  }\n  // `--show-prefix` first, and not decoration (base-git.ts proved this): a\n  // docs repo checked out as a subdirectory of a larger repository answers\n  // `show` only under that prefix, and a walk whose paths all miss would\n  // report \"no vouched ancestor\" about a history that holds one.\n  const where = await gitPlain(docsDir, [\"rev-parse\", \"--show-prefix\"]);\n  if (where.spawnError !== undefined || where.code !== 0) {\n    return { kind: \"no-git\", detail: declineDetail(where) };\n  }\n  const prefix = where.out.trim();\n\n  // The pathspec is cwd-relative (no prefix — `log` resolves it against the\n  // cwd, unlike `show`'s repo-root spelling below). `-n` is the walk's bound.\n  const log = await gitPlain(docsDir, [\n    \"log\", \"-n\", String(ANCESTOR_WALK_CAP), \"--format=%H\", \"--\", rel,\n  ]);\n  if (log.spawnError !== undefined || log.code !== 0 || log.overflowed) {\n    return { kind: \"no-git\", detail: declineDetail(log) };\n  }\n  // Only shas shaped like shas walk on — an unexpected line yields a shorter\n  // walk, never a malformed argv (the gitq/moves.ts token-anchoring rule).\n  const commits = log.out.split(\"\\n\").map((l) => l.trim()).filter((l) => /^[0-9a-f]{40}$/.test(l));\n  // Sequential on purpose: newest-first order is the answer's definition, and\n  // the walk stops at the first match — a fan-out would read history it does\n  // not need and could answer with an older commit than the newest match.\n  for (const commit of commits) {\n    const shown = await gitPlain(docsDir, [\"show\", `${commit}:${prefix}${rel}`]);\n    if (shown.spawnError !== undefined || shown.code === null) {\n      // Git stopped answering (not installed mid-walk, killed, timed out, or\n      // the output cap fired on a monstrous version). Abort rather than walk\n      // on: each further spawn could wait out the whole timeout, and a \"none\"\n      // built over commits nobody read would claim the history was searched.\n      return {\n        kind: \"no-git\",\n        detail: shown.overflowed\n          ? `the file at ${commit.slice(0, 12)} exceeds the git output cap.`\n          : declineDetail(shown),\n      };\n    }\n    // A real non-zero exit is git ANSWERING — the file is absent at this\n    // commit (renamed since, or the commit only deleted it). Skip it.\n    if (shown.code !== 0) continue;\n    if (\n      contentDigest(shown.out) === stampedDigest ||\n      contentDigest(checkoutRendering(shown.out)) === stampedDigest\n    ) {\n      return { kind: \"found\", commit, text: shown.out };\n    }\n  }\n  return {\n    kind: \"none\",\n    reason:\n      commits.length < ANCESTOR_WALK_CAP\n        ? \"body has no vouched ancestor in history\"\n        : `body has no vouched ancestor in history — only the last ${ANCESTOR_WALK_CAP} commits touching the file were walked, and the vouched state may lie beyond them`,\n  };\n}\n\nexport type BodyDiff =\n  | { kind: \"ok\"; diff: string }\n  /** No diff to print — the honest degrade is a full read, with this reason. */\n  | { kind: \"failed\"; reason: string };\n\n/**\n * The file's diff from its last vouched state: `git diff <commit> -- <rel>`,\n * commit-to-working-tree, in the docs repo. The output is git's own — when a\n * hand edit touched the frontmatter after the vouch, its hunks ride along,\n * which is why the pack's prose says \"the file's diff\", never \"the body's\".\n */\nexport async function bodyDiffText(docsDir: string, commit: string, rel: string): Promise<BodyDiff> {\n  // The commit came out of `findVouchedAncestor`'s own regex-vetted walk, but\n  // this function is exported API: re-vet, so no future caller can place an\n  // option-shaped string in the one argv slot that is not behind `--`.\n  if (!/^[0-9a-f]{40}$/.test(commit)) {\n    return { kind: \"failed\", reason: `'${commit}' is not a commit this diff can be asked about.` };\n  }\n  if (rel.trim() === \"\" || rel.startsWith(\"-\")) {\n    return { kind: \"failed\", reason: `'${rel}' is not a path git can be asked about.` };\n  }\n  // `--no-optional-locks`: a commit-to-worktree diff may opportunistically\n  // refresh `.git/index`'s stat cache, which is a WRITE — small, benign, and\n  // exactly what a command documented as \"writes nothing\" must not do. The\n  // global flag tells git to skip any operation that would take a lock it\n  // does not strictly need. `--no-ext-diff --no-textconv` close the rest of\n  // the config surface: `diff.external` / a `.gitattributes` diff driver make\n  // `git diff` EXECUTE a user-configured program instead of printing a diff —\n  // an arbitrary write hazard on a read-only path, and output no machine\n  // consumer of `body.diff` could parse. The pack's diff is a machine\n  // artifact, not a terminal rendering; git's own plumbing flags say so.\n  const answer = await gitPlain(docsDir, [\n    \"--no-optional-locks\", \"diff\", \"--no-ext-diff\", \"--no-textconv\", commit, \"--\", rel,\n  ]);\n  if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {\n    return { kind: \"failed\", reason: declineDetail(answer) };\n  }\n  if (answer.out.length > MAX_DIFF_TEXT_CHARS) {\n    return { kind: \"failed\", reason: \"the body diff exceeds the pack's print cap — read the file\" };\n  }\n  return { kind: \"ok\", diff: answer.out };\n}\n"]}

package/dist/core/provenance/sample/scope.js

@@ -0,0 +1,238 @@
+/**
+ * What a SAMPLED vouch claims, how its sample is chosen, and how the claim is
+ * written into the document beside `vouched_by`.
+ *
+ * `loam vouch --sample <n>` exists because the alternative to a partial read
+ * is usually not a full read — it is no vouch at all, and a fleet of
+ * unvouched drafts. So this deliberately REDUCES the assurance a stamp
+ * carries, and every line here exists to make sure the reduction is visible:
+ * the scope rides beside `status: verified` (never as a new status — that
+ * string is frozen), it says k of n in the document itself, and it carries
+ * the seed so anyone can recompute exactly which sections the person was
+ * shown. A sampled vouch that could be mistaken for a full one would be worse
+ * than no vouch, because it would spend the one signal loam has.
+ *
+ * The seed is derived from the document's OWN content and the digest of its
+ * sources — never from the clock, a counter or a random number — for three
+ * reasons, in order of how much they matter:
+ *
+ *  1. **Anyone can audit it.** The stamp records the seed, k and n; the
+ *     document records `content_digest` and `sources_digest`. A reviewer
+ *     recomputes `sampleSeed` from those three values and `pickSample` over
+ *     the body, and gets back the exact list the voucher was shown.
+ *  2. **The pick cannot be re-rolled in place.** A random seed would let an
+ *     agent run the vouch — or `--pack --sample` — until the section it wrote
+ *     carelessly fell outside the sample, leaving no trace anywhere. Content
+ *     derivation makes every re-roll an EDIT to the document: recorded in the
+ *     docs repo's history, and moving `content_digest` under any stamp
+ *     already standing over it.
+ *  3. **The same recipe answers before and after.** The pre-vouch reading
+ *     list, the prompt and `loam vouch --pack --sample` all call `planSample`
+ *     with the digests the stamp is about to carry, so the pack cannot
+ *     prescribe one sample while the stamp records another.
+ *
+ * Reproducibility rests on one property of the writer:
+ * `withFrontmatterFields` leaves the body byte-identical, and `contentDigest`
+ * hashes only the body — so `contentDigest(raw)` computed BEFORE the stamp
+ * equals the `content_digest` the stamp writes. That is what lets the sample
+ * be chosen (and shown to a person) before the value it is keyed to exists on
+ * disk.
+ *
+ * What this does NOT do — and the difference is worth stating plainly, since
+ * an overstated claim is worse than none — is make the sample UNPREDICTABLE.
+ * The recipe is published (SCHEMA.md), so anybody holding the document can
+ * compute the pick before anybody vouches: that IS reason 1, and the two
+ * properties are in direct tension. An agent that wants a particular section
+ * left out of the read can append a space and recompute until it is, at the
+ * cost of one cosmetic edit per attempt in a version-controlled file,
+ * immediately before asking a person to vouch. Auditability was chosen over
+ * unpredictability deliberately — hiding the recipe needs a secret loam has
+ * nowhere to keep, and a sample nobody can check is not evidence of anything.
+ * What the design buys is that steering is neither free nor invisible: the
+ * same bargain `sources_digest` strikes, which is a change detector and not a
+ * seal.
+ *
+ * It also does not weight the sample. See `pickSample`.
+ */
+import { createHash } from "node:crypto";
+import { stringField } from "../../document/frontmatter.js";
+import { splitSections } from "./sections.js";
+/**
+ * Hex characters kept from a sha256 — `provenance/stamp.ts`'s DIGEST_LENGTH,
+ * respelled rather than imported because this is a seed and not a digest: the
+ * two would be free to diverge, and importing would tie a sampling decision to
+ * a change-detection budget. 64 bits is not a seal here either; an adversary
+ * who wants a collision can have one, and the audit trail is the git history
+ * of the docs repo, not this number.
+ */
+const SEED_LENGTH = 16;
+/**
+ * The seed for one spec-axis FILE: `sha256(service \0 content_digest \0
+ * sources_digest)`, first 16 hex characters.
+ *
+ * Per file, not per service, because the two inputs are per-file stamps —
+ * spec.md and arch.spec.md carry their own digests, so one `--sample 3` run
+ * picks three sections of each from two different seeds. The service id is in
+ * the hash so two services whose specs happen to be byte-identical (a
+ * scaffold, a copy) do not get the same reading list.
+ *
+ * NUL separators, `sourcesDigest`'s own recipe: without them
+ * `("ab", "c")` and `("a", "bc")` hash alike, and a service id may contain
+ * dots and dashes.
+ */
+export function sampleSeed(service, contentDigest, sourcesDigest) {
+    return createHash("sha256")
+        .update(`${service}\0${contentDigest}\0${sourcesDigest}`)
+        .digest("hex")
+        .slice(0, SEED_LENGTH);
+}
+/**
+ * Pick `n` sections deterministically from `sections`, returned in DOCUMENT
+ * order.
+ *
+ * Rank each section by `sha256(seed \0 index \0 heading)` and take the `n`
+ * lowest ranks. Hash-ranking rather than a seeded PRNG: there is no PRNG in
+ * the standard library, adding a dependency for one is a product decision this
+ * repo has already made against, and a hash rank is recomputable one section
+ * at a time by anybody with a shell. The index is in the rank so two sections
+ * with identical heading text (a document with two `## Notes`) still rank
+ * apart, and the index tiebreak below keeps the sort total.
+ *
+ * Document order on the way out, not rank order: the person is going to read
+ * the file top to bottom, and a list that jumps around is a list they lose
+ * their place in.
+ *
+ * **Uniform — the sample is NOT weighted by fan-in**, and that is a decision
+ * rather than an omission. `core/dependencies/fanin.ts` counts how many
+ * services depend on a SERVICE; nothing in loam says which consumer depends on
+ * which SECTION, and the join that would (section -> `Operations:`/`Publishes:`
+ * -> landscape edge -> caller) has three defects at this stakes. It is
+ * derivable only for `### Requirement:` sections that carry those lines, so
+ * every narrative section — `## Overview`, `## Interfaces`, the prose most
+ * likely to be quietly false — would weight to zero and effectively stop being
+ * sampled. It needs the fleet map and every sibling's contract, so a vouch in
+ * a service repo would depend on documents it cannot see, and an unparseable
+ * landscape would silently flatten the weights back to uniform without saying
+ * so. And decisively: those inputs are documents an agent can edit, and they
+ * are not covered by either digest in the seed — so weighting would hand back
+ * exactly the steering that content-derived seeding exists to take away. The
+ * parameter list has room for weights if a later version can answer those;
+ * v1's answer is that an unweighted sample nobody can aim is worth more than a
+ * weighted one somebody can.
+ */
+export function pickSample(sections, n, seed) {
+    return sections
+        .map((section, index) => ({
+        index,
+        section,
+        rank: createHash("sha256").update(`${seed}\0${index}\0${section.heading}`).digest("hex"),
+    }))
+        // Rank first, index second: sha256 makes a tie astronomically unlikely,
+        // but "unlikely" is not "total", and an unstable sort over equal ranks
+        // would make the pick depend on the engine's sort implementation — which
+        // is exactly the reproducibility this whole module promises.
+        .sort((a, b) => (a.rank < b.rank ? -1 : a.rank > b.rank ? 1 : a.index - b.index))
+        .slice(0, n)
+        .sort((a, b) => a.index - b.index)
+        .map((ranked) => ranked.section);
+}
+/**
+ * The whole per-file derivation in one call, so that the reading list, the
+ * prompt, `--pack --sample` and the stamp cannot drift into prescribing
+ * different samples of the same file. Every caller goes through here.
+ *
+ * A file with `of <= n` comes back with every section picked: the sample
+ * covers the document, so the run is an ordinary full vouch and stamps no
+ * scope at all. That case is decided by comparing `picked.length` with `of`,
+ * one derivation rather than a boolean somebody has to keep true.
+ */
+export function planSample(req) {
+    const sections = splitSections(req.body);
+    const seed = sampleSeed(req.service, req.contentDigest, req.sourcesDigest);
+    return { seed, of: sections.length, picked: pickSample(sections, req.n, seed) };
+}
+/**
+ * The `vouch_scope` value: `sampled 4/17 seed=1a2b3c4d5e6f7089`.
+ *
+ * One flat string rather than a nested YAML mapping, following the
+ * `sources_files` precedent: `withFrontmatterFields` takes string values and
+ * promises a byte-identical body, and a mapping value would put the writer in
+ * the business of composing YAML structure inside somebody's header. It also
+ * reads: a reviewer scanning a diff sees the whole claim on one line.
+ */
+export function encodeVouchScope(scope) {
+    return `sampled ${scope.sections}/${scope.of} seed=${scope.seed}`;
+}
+/** Exactly what `encodeVouchScope` writes, and nothing else. */
+const SCOPE_RE = new RegExp(String.raw `^sampled (\d+)\/(\d+) seed=([0-9a-f]{${SEED_LENGTH}})$`);
+/**
+ * Read a stamped `vouch_scope` back, or null when it is not one this loam
+ * wrote.
+ *
+ * Null means "cannot be read", NEVER "is not sampled" — the two are different
+ * facts and every caller must keep them apart, which is what `isSampled`
+ * below is for. A verified document carrying an unreadable scope is graded as
+ * SAMPLED by `sources.sampled-vouch`, `loam list` and `loam show`: fail
+ * closed, because the alternative is that mangling one field promotes a
+ * partial read to a full one.
+ */
+export function decodeVouchScope(stamped) {
+    if (stamped === undefined)
+        return null;
+    const m = SCOPE_RE.exec(stamped.trim());
+    if (m === null)
+        return null;
+    const scope = { sections: Number(m[1]), of: Number(m[2]), seed: m[3] };
+    // A claim that reads as covering everything is not a sample, and neither is
+    // one that read nothing: both are shapes this writer never produces, so
+    // treating them as decodable would let a hand-edited `sampled 17/17` grade
+    // as a legible partial claim instead of an unreadable one.
+    return scope.sections >= 1 && scope.sections < scope.of ? scope : null;
+}
+export function readVouchScope(fm) {
+    if (!Object.hasOwn(fm.data, "vouch_scope"))
+        return { kind: "none" };
+    const text = stringField(fm, "vouch_scope");
+    if (text === undefined)
+        return { kind: "unreadable", text: null };
+    const scope = decodeVouchScope(text);
+    return scope === null ? { kind: "unreadable", text } : { kind: "sampled", scope, text };
+}
+/**
+ * The scope as a surface shows it: the stamped text, or — for a value that is
+ * not even text — one fixed sentence, because what a reader must not be shown
+ * for a present scope is nothing at all. Null means the key is absent, which
+ * is the only state that reads as a full vouch.
+ *
+ * One spelling of the unreadable case, because `loam show` and the context
+ * pack have to say the same thing about the same document.
+ */
+export function scopeText(fm) {
+    const stamp = readVouchScope(fm);
+    if (stamp.kind === "none")
+        return null;
+    if (stamp.kind === "sampled")
+        return stamp.text;
+    return stamp.text ?? "present, but its value is not text — graded sampled";
+}
+/**
+ * Which sections a recorded scope actually covered, recomputed from its own
+ * seed over the body it was taken over.
+ *
+ * This is the audit property in code: hand it the stamped scope and the body
+ * that was vouched, get back the list the voucher was shown. The re-vouch
+ * pack uses it to say which sections a previous sampled vouch READ, so the
+ * ones it did not can be named as never-read rather than quietly counted as
+ * covered.
+ *
+ * Null when the body no longer has the section count the scope names — the
+ * body has changed, so the pick cannot be reproduced and no claim about what
+ * was read is safe. Fail closed: an unreproducible sample licenses nothing.
+ */
+export function sampledSections(body, scope) {
+    const sections = splitSections(body);
+    if (sections.length !== scope.of)
+        return null;
+    return pickSample(sections, scope.sections, scope.seed);
+}
+//# sourceMappingURL=scope.js.map

package/dist/core/provenance/sample/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../../src/core/provenance/sample/scope.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a SAMPLED vouch claims, how its sample is chosen, and how the claim is\n * written into the document beside `vouched_by`.\n *\n * `loam vouch --sample <n>` exists because the alternative to a partial read\n * is usually not a full read — it is no vouch at all, and a fleet of\n * unvouched drafts. So this deliberately REDUCES the assurance a stamp\n * carries, and every line here exists to make sure the reduction is visible:\n * the scope rides beside `status: verified` (never as a new status — that\n * string is frozen), it says k of n in the document itself, and it carries\n * the seed so anyone can recompute exactly which sections the person was\n * shown. A sampled vouch that could be mistaken for a full one would be worse\n * than no vouch, because it would spend the one signal loam has.\n *\n * The seed is derived from the document's OWN content and the digest of its\n * sources — never from the clock, a counter or a random number — for three\n * reasons, in order of how much they matter:\n *\n *  1. **Anyone can audit it.** The stamp records the seed, k and n; the\n *     document records `content_digest` and `sources_digest`. A reviewer\n *     recomputes `sampleSeed` from those three values and `pickSample` over\n *     the body, and gets back the exact list the voucher was shown.\n *  2. **The pick cannot be re-rolled in place.** A random seed would let an\n *     agent run the vouch — or `--pack --sample` — until the section it wrote\n *     carelessly fell outside the sample, leaving no trace anywhere. Content\n *     derivation makes every re-roll an EDIT to the document: recorded in the\n *     docs repo's history, and moving `content_digest` under any stamp\n *     already standing over it.\n *  3. **The same recipe answers before and after.** The pre-vouch reading\n *     list, the prompt and `loam vouch --pack --sample` all call `planSample`\n *     with the digests the stamp is about to carry, so the pack cannot\n *     prescribe one sample while the stamp records another.\n *\n * Reproducibility rests on one property of the writer:\n * `withFrontmatterFields` leaves the body byte-identical, and `contentDigest`\n * hashes only the body — so `contentDigest(raw)` computed BEFORE the stamp\n * equals the `content_digest` the stamp writes. That is what lets the sample\n * be chosen (and shown to a person) before the value it is keyed to exists on\n * disk.\n *\n * What this does NOT do — and the difference is worth stating plainly, since\n * an overstated claim is worse than none — is make the sample UNPREDICTABLE.\n * The recipe is published (SCHEMA.md), so anybody holding the document can\n * compute the pick before anybody vouches: that IS reason 1, and the two\n * properties are in direct tension. An agent that wants a particular section\n * left out of the read can append a space and recompute until it is, at the\n * cost of one cosmetic edit per attempt in a version-controlled file,\n * immediately before asking a person to vouch. Auditability was chosen over\n * unpredictability deliberately — hiding the recipe needs a secret loam has\n * nowhere to keep, and a sample nobody can check is not evidence of anything.\n * What the design buys is that steering is neither free nor invisible: the\n * same bargain `sources_digest` strikes, which is a change detector and not a\n * seal.\n *\n * It also does not weight the sample. See `pickSample`.\n */\nimport { createHash } from \"node:crypto\";\nimport { stringField, type Frontmatter } from \"../../document/frontmatter.js\";\nimport { splitSections, type DocSection } from \"./sections.js\";\n\n/**\n * Hex characters kept from a sha256 — `provenance/stamp.ts`'s DIGEST_LENGTH,\n * respelled rather than imported because this is a seed and not a digest: the\n * two would be free to diverge, and importing would tie a sampling decision to\n * a change-detection budget. 64 bits is not a seal here either; an adversary\n * who wants a collision can have one, and the audit trail is the git history\n * of the docs repo, not this number.\n */\nconst SEED_LENGTH = 16;\n\n/** What a sampled vouch stamped: how many sections of how many, and the seed that chose them. */\nexport interface VouchScope {\n  /** k — how many sections the person was shown and asked to read. */\n  sections: number;\n  /** n — how many the file had when they read it. Always greater than `sections`. */\n  of: number;\n  /** The seed, `SEED_LENGTH` lowercase hex characters. */\n  seed: string;\n}\n\n/**\n * The seed for one spec-axis FILE: `sha256(service \\0 content_digest \\0\n * sources_digest)`, first 16 hex characters.\n *\n * Per file, not per service, because the two inputs are per-file stamps —\n * spec.md and arch.spec.md carry their own digests, so one `--sample 3` run\n * picks three sections of each from two different seeds. The service id is in\n * the hash so two services whose specs happen to be byte-identical (a\n * scaffold, a copy) do not get the same reading list.\n *\n * NUL separators, `sourcesDigest`'s own recipe: without them\n * `(\"ab\", \"c\")` and `(\"a\", \"bc\")` hash alike, and a service id may contain\n * dots and dashes.\n */\nexport function sampleSeed(service: string, contentDigest: string, sourcesDigest: string): string {\n  return createHash(\"sha256\")\n    .update(`${service}\\0${contentDigest}\\0${sourcesDigest}`)\n    .digest(\"hex\")\n    .slice(0, SEED_LENGTH);\n}\n\n/**\n * Pick `n` sections deterministically from `sections`, returned in DOCUMENT\n * order.\n *\n * Rank each section by `sha256(seed \\0 index \\0 heading)` and take the `n`\n * lowest ranks. Hash-ranking rather than a seeded PRNG: there is no PRNG in\n * the standard library, adding a dependency for one is a product decision this\n * repo has already made against, and a hash rank is recomputable one section\n * at a time by anybody with a shell. The index is in the rank so two sections\n * with identical heading text (a document with two `## Notes`) still rank\n * apart, and the index tiebreak below keeps the sort total.\n *\n * Document order on the way out, not rank order: the person is going to read\n * the file top to bottom, and a list that jumps around is a list they lose\n * their place in.\n *\n * **Uniform — the sample is NOT weighted by fan-in**, and that is a decision\n * rather than an omission. `core/dependencies/fanin.ts` counts how many\n * services depend on a SERVICE; nothing in loam says which consumer depends on\n * which SECTION, and the join that would (section -> `Operations:`/`Publishes:`\n * -> landscape edge -> caller) has three defects at this stakes. It is\n * derivable only for `### Requirement:` sections that carry those lines, so\n * every narrative section — `## Overview`, `## Interfaces`, the prose most\n * likely to be quietly false — would weight to zero and effectively stop being\n * sampled. It needs the fleet map and every sibling's contract, so a vouch in\n * a service repo would depend on documents it cannot see, and an unparseable\n * landscape would silently flatten the weights back to uniform without saying\n * so. And decisively: those inputs are documents an agent can edit, and they\n * are not covered by either digest in the seed — so weighting would hand back\n * exactly the steering that content-derived seeding exists to take away. The\n * parameter list has room for weights if a later version can answer those;\n * v1's answer is that an unweighted sample nobody can aim is worth more than a\n * weighted one somebody can.\n */\nexport function pickSample(sections: readonly DocSection[], n: number, seed: string): DocSection[] {\n  return sections\n    .map((section, index) => ({\n      index,\n      section,\n      rank: createHash(\"sha256\").update(`${seed}\\0${index}\\0${section.heading}`).digest(\"hex\"),\n    }))\n    // Rank first, index second: sha256 makes a tie astronomically unlikely,\n    // but \"unlikely\" is not \"total\", and an unstable sort over equal ranks\n    // would make the pick depend on the engine's sort implementation — which\n    // is exactly the reproducibility this whole module promises.\n    .sort((a, b) => (a.rank < b.rank ? -1 : a.rank > b.rank ? 1 : a.index - b.index))\n    .slice(0, n)\n    .sort((a, b) => a.index - b.index)\n    .map((ranked) => ranked.section);\n}\n\n/** One file's sampling inputs — the two digests its stamp will carry, its body, and k. */\nexport interface SampleInputs {\n  service: string;\n  /** As `content_digest` will read — `contentDigest(raw)`, which the stamp preserves. */\n  contentDigest: string;\n  /** As `sources_digest` will read. */\n  sourcesDigest: string;\n  /** The document BODY, below the frontmatter (`rawBody`). */\n  body: string;\n  /** How many sections to read — `--sample <n>`, a whole number of at least 1. */\n  n: number;\n}\n\n/** What a sample comes to for one file: the seed, how many sections there were, and which were picked. */\nexport interface PlannedSample {\n  seed: string;\n  /** n — every section the body has. `picked` is all of them when `of <= n`. */\n  of: number;\n  picked: DocSection[];\n}\n\n/**\n * The whole per-file derivation in one call, so that the reading list, the\n * prompt, `--pack --sample` and the stamp cannot drift into prescribing\n * different samples of the same file. Every caller goes through here.\n *\n * A file with `of <= n` comes back with every section picked: the sample\n * covers the document, so the run is an ordinary full vouch and stamps no\n * scope at all. That case is decided by comparing `picked.length` with `of`,\n * one derivation rather than a boolean somebody has to keep true.\n */\nexport function planSample(req: SampleInputs): PlannedSample {\n  const sections = splitSections(req.body);\n  const seed = sampleSeed(req.service, req.contentDigest, req.sourcesDigest);\n  return { seed, of: sections.length, picked: pickSample(sections, req.n, seed) };\n}\n\n/**\n * The `vouch_scope` value: `sampled 4/17 seed=1a2b3c4d5e6f7089`.\n *\n * One flat string rather than a nested YAML mapping, following the\n * `sources_files` precedent: `withFrontmatterFields` takes string values and\n * promises a byte-identical body, and a mapping value would put the writer in\n * the business of composing YAML structure inside somebody's header. It also\n * reads: a reviewer scanning a diff sees the whole claim on one line.\n */\nexport function encodeVouchScope(scope: VouchScope): string {\n  return `sampled ${scope.sections}/${scope.of} seed=${scope.seed}`;\n}\n\n/** Exactly what `encodeVouchScope` writes, and nothing else. */\nconst SCOPE_RE = new RegExp(String.raw`^sampled (\\d+)\\/(\\d+) seed=([0-9a-f]{${SEED_LENGTH}})$`);\n\n/**\n * Read a stamped `vouch_scope` back, or null when it is not one this loam\n * wrote.\n *\n * Null means \"cannot be read\", NEVER \"is not sampled\" — the two are different\n * facts and every caller must keep them apart, which is what `isSampled`\n * below is for. A verified document carrying an unreadable scope is graded as\n * SAMPLED by `sources.sampled-vouch`, `loam list` and `loam show`: fail\n * closed, because the alternative is that mangling one field promotes a\n * partial read to a full one.\n */\nexport function decodeVouchScope(stamped: string | undefined): VouchScope | null {\n  if (stamped === undefined) return null;\n  const m = SCOPE_RE.exec(stamped.trim());\n  if (m === null) return null;\n  const scope = { sections: Number(m[1]!), of: Number(m[2]!), seed: m[3]! };\n  // A claim that reads as covering everything is not a sample, and neither is\n  // one that read nothing: both are shapes this writer never produces, so\n  // treating them as decodable would let a hand-edited `sampled 17/17` grade\n  // as a legible partial claim instead of an unreadable one.\n  return scope.sections >= 1 && scope.sections < scope.of ? scope : null;\n}\n\n/**\n * What a document's `vouch_scope` says, as the ONE question every reader that\n * reports trust must ask.\n *\n * It takes the whole frontmatter rather than a field value because the test\n * that matters is KEY PRESENCE, and no field accessor can express it: a scope\n * written as a YAML mapping or sequence — a hand edit, a merge tool, an agent\n * \"tidying\" the header into something more legible — reads back from\n * `stringField` as `undefined`, exactly like an absent field, and grading that\n * as a FULL vouch is the promotion this vocabulary exists to prevent. Asking\n * it here, once, is what stops that hole being reopened one reader at a time:\n *\n * - `none` — the key is not there. The only reading that means a full vouch.\n * - `sampled` — a value this loam wrote, with the k/n and seed decoded.\n * - `unreadable` — the key is there and says something else. Graded sampled\n *   by every caller, with `text` for display (null when the value is not even\n *   a scalar, so there is nothing to quote).\n *\n * One hole remains and is not closable here: `vouch_scope:` with no value at\n * all is a key whose value is YAML null, which reads as PRESENT — and simply\n * deleting the line reads as absent, like every other hand-removed stamp. The\n * answer to that is the docs repo's git history, not this parser.\n */\nexport type ScopeStamp =\n  | { kind: \"none\" }\n  | { kind: \"sampled\"; scope: VouchScope; text: string }\n  | { kind: \"unreadable\"; text: string | null };\n\nexport function readVouchScope(fm: Frontmatter): ScopeStamp {\n  if (!Object.hasOwn(fm.data, \"vouch_scope\")) return { kind: \"none\" };\n  const text = stringField(fm, \"vouch_scope\");\n  if (text === undefined) return { kind: \"unreadable\", text: null };\n  const scope = decodeVouchScope(text);\n  return scope === null ? { kind: \"unreadable\", text } : { kind: \"sampled\", scope, text };\n}\n\n/**\n * The scope as a surface shows it: the stamped text, or — for a value that is\n * not even text — one fixed sentence, because what a reader must not be shown\n * for a present scope is nothing at all. Null means the key is absent, which\n * is the only state that reads as a full vouch.\n *\n * One spelling of the unreadable case, because `loam show` and the context\n * pack have to say the same thing about the same document.\n */\nexport function scopeText(fm: Frontmatter): string | null {\n  const stamp = readVouchScope(fm);\n  if (stamp.kind === \"none\") return null;\n  if (stamp.kind === \"sampled\") return stamp.text;\n  return stamp.text ?? \"present, but its value is not text — graded sampled\";\n}\n\n/**\n * Which sections a recorded scope actually covered, recomputed from its own\n * seed over the body it was taken over.\n *\n * This is the audit property in code: hand it the stamped scope and the body\n * that was vouched, get back the list the voucher was shown. The re-vouch\n * pack uses it to say which sections a previous sampled vouch READ, so the\n * ones it did not can be named as never-read rather than quietly counted as\n * covered.\n *\n * Null when the body no longer has the section count the scope names — the\n * body has changed, so the pick cannot be reproduced and no claim about what\n * was read is safe. Fail closed: an unreproducible sample licenses nothing.\n */\nexport function sampledSections(body: string, scope: VouchScope): DocSection[] | null {\n  const sections = splitSections(body);\n  if (sections.length !== scope.of) return null;\n  return pickSample(sections, scope.sections, scope.seed);\n}\n"]}

package/dist/core/provenance/sample/sections.js

@@ -0,0 +1,61 @@
+/**
+ * A spec body cut into the units a sampled vouch reads.
+ *
+ * The unit is a heading and the contiguous text under it, at H2 *and* H3, cut
+ * at the next heading of either level — leaf blocks, no overlap. H3 counts
+ * because of what a living spec actually looks like: `## Requirements` holds
+ * every `### Requirement:` in the document, so an H2-only cut offers a sample
+ * of four or five units, one of which is most of the file. "Read two of these
+ * nine" is only an honest reduction if the units are the size of a thing a
+ * person reads.
+ *
+ * The fence rule is `core/kernel/fences.ts`'s `fenceTracker`, imported rather
+ * than restated: a `## ` line inside a code block is prose about a heading, not
+ * structure, and a sampler that disagreed with `sectionHeadings` about that
+ * would prescribe sections no reader can find. It sat in `core/document/parse.ts`
+ * when this walk was its only borrower, and moved down to the kernel when a
+ * fourth reader needed it from a package `core/document/` already depends on. On the H2 subset
+ * this walk returns exactly what `sectionHeadings` returns — same test, same
+ * `line.trim()` spelling, same 1-based line — and test/vouch-sample.test.ts
+ * pins that agreement, because the reading list and the re-vouch pack's
+ * "already covered" list name headings to the same person.
+ *
+ * No BOM strip here: every caller hands in `rawBody(raw)`, which already drops
+ * a BOM above the frontmatter, and stripping again at position 0 of a *body*
+ * would eat an author's zero-width no-break space.
+ */
+import { fenceTracker } from "../../kernel/fences.js";
+/**
+ * Two or three `#` followed by whitespace. `####` and deeper cannot match at
+ * all — `#{2,3}` has nowhere to leave a space before the fourth `#` — which is
+ * how a `#### Scenario:` stays interior to the requirement it belongs to
+ * rather than becoming a unit of its own. `sectionHeadings` spells the H2 half
+ * of this as `/^##\s+/` plus a `###` exclusion; both accept the same lines,
+ * and the exclusion is why THIS pattern cannot be written that way: `^##\s+`
+ * never matches `### ` at all, because the character after `##` is a `#`.
+ * Getting that wrong is not a compile error, it is a splitter that silently
+ * drops every requirement in the document.
+ */
+const HEADING_RE = /^(#{2,3})\s+/;
+/**
+ * Every H2 and H3 heading outside a fenced block, in document order.
+ *
+ * The text above the first heading is deliberately not a unit: it has no
+ * heading to name it in a reading list, and it is short. The reading list
+ * says "read the preamble" outside the k/n count instead, so a sample is
+ * never the reason nobody read the opening paragraph.
+ */
+export function splitSections(body) {
+    const fenced = fenceTracker();
+    const out = [];
+    body.split(/\r?\n/).forEach((line, i) => {
+        if (fenced(line))
+            return;
+        const m = HEADING_RE.exec(line);
+        if (m === null)
+            return;
+        out.push({ heading: line.trim(), level: m[1].length === 3 ? 3 : 2, line: i + 1 });
+    });
+    return out;
+}
+//# sourceMappingURL=sections.js.map

package/dist/core/provenance/sample/sections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.js","sourceRoot":"","sources":["../../../../src/core/provenance/sample/sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAWtD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACtC,IAAI,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO;QACzB,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO;QACvB,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrF,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * A spec body cut into the units a sampled vouch reads.\n *\n * The unit is a heading and the contiguous text under it, at H2 *and* H3, cut\n * at the next heading of either level — leaf blocks, no overlap. H3 counts\n * because of what a living spec actually looks like: `## Requirements` holds\n * every `### Requirement:` in the document, so an H2-only cut offers a sample\n * of four or five units, one of which is most of the file. \"Read two of these\n * nine\" is only an honest reduction if the units are the size of a thing a\n * person reads.\n *\n * The fence rule is `core/kernel/fences.ts`'s `fenceTracker`, imported rather\n * than restated: a `## ` line inside a code block is prose about a heading, not\n * structure, and a sampler that disagreed with `sectionHeadings` about that\n * would prescribe sections no reader can find. It sat in `core/document/parse.ts`\n * when this walk was its only borrower, and moved down to the kernel when a\n * fourth reader needed it from a package `core/document/` already depends on. On the H2 subset\n * this walk returns exactly what `sectionHeadings` returns — same test, same\n * `line.trim()` spelling, same 1-based line — and test/vouch-sample.test.ts\n * pins that agreement, because the reading list and the re-vouch pack's\n * \"already covered\" list name headings to the same person.\n *\n * No BOM strip here: every caller hands in `rawBody(raw)`, which already drops\n * a BOM above the frontmatter, and stripping again at position 0 of a *body*\n * would eat an author's zero-width no-break space.\n */\nimport { fenceTracker } from \"../../kernel/fences.js\";\n\n/** One sampling unit: the heading that names it, and where it starts. */\nexport interface DocSection {\n  /** The heading line as the document spells it, trimmed — `sectionHeadings`' spelling. */\n  heading: string;\n  level: 2 | 3;\n  /** 1-based, counted within the BODY that was passed — not the file. */\n  line: number;\n}\n\n/**\n * Two or three `#` followed by whitespace. `####` and deeper cannot match at\n * all — `#{2,3}` has nowhere to leave a space before the fourth `#` — which is\n * how a `#### Scenario:` stays interior to the requirement it belongs to\n * rather than becoming a unit of its own. `sectionHeadings` spells the H2 half\n * of this as `/^##\\s+/` plus a `###` exclusion; both accept the same lines,\n * and the exclusion is why THIS pattern cannot be written that way: `^##\\s+`\n * never matches `### ` at all, because the character after `##` is a `#`.\n * Getting that wrong is not a compile error, it is a splitter that silently\n * drops every requirement in the document.\n */\nconst HEADING_RE = /^(#{2,3})\\s+/;\n\n/**\n * Every H2 and H3 heading outside a fenced block, in document order.\n *\n * The text above the first heading is deliberately not a unit: it has no\n * heading to name it in a reading list, and it is short. The reading list\n * says \"read the preamble\" outside the k/n count instead, so a sample is\n * never the reason nobody read the opening paragraph.\n */\nexport function splitSections(body: string): DocSection[] {\n  const fenced = fenceTracker();\n  const out: DocSection[] = [];\n  body.split(/\\r?\\n/).forEach((line, i) => {\n    if (fenced(line)) return;\n    const m = HEADING_RE.exec(line);\n    if (m === null) return;\n    out.push({ heading: line.trim(), level: m[1]!.length === 3 ? 3 : 2, line: i + 1 });\n  });\n  return out;\n}\n"]}