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

package/dist/core/provenance/sources.js

@@ -0,0 +1,263 @@
+/**
+ * The `sources` list: vetting the entries an author wrote — patterns, escapes,
+ * missing paths, the refusal vocabulary `loam vouch` and `loam validate` share
+ * — and grading the vetted list against the service repo: resolved, unvouched,
+ * current, stale, and whether the walk reached the whole repository. Vetting
+ * and grading are one doctrine about one field, so they live in one file.
+ */
+import { existsSync } from "node:fs";
+import { listField, stringField } from "../document/frontmatter.js";
+import { resolveInside } from "../kernel/path-safety.js";
+import { decodeSourceIndex, movedSources, sourcesDigest } from "./stamp.js";
+import { gitTrackedFiles } from "./git.js";
+export async function sourceFindings(fm, service, label, repoDir) {
+    const sources = listField(fm, "sources");
+    if (sources.length === 0) {
+        return [
+            {
+                severity: "warn",
+                code: "sources.absent",
+                message: `${label} names no sources — nothing ties it to the code, so nothing can tell you when it goes out of date`,
+            },
+        ];
+    }
+    // Someone else's repository: the paths describe a tree loam is not standing in.
+    if (repoDir === undefined)
+        return [];
+    // Before existence: a pattern entry would "not exist" as a literal path, and
+    // grading it missing would send the author fixing the wrong thing.
+    const patterns = patternSources(sources);
+    if (patterns.length > 0) {
+        return [
+            {
+                severity: "error",
+                code: "sources.path-missing",
+                message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(", ")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it).`,
+                details: patterns,
+                text: { detailPrefix: "- " },
+            },
+        ];
+    }
+    const unsafe = unsafeSources(repoDir, sources);
+    if (unsafe.length > 0) {
+        return [
+            {
+                severity: "error",
+                code: "sources.path-outside",
+                message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(", ")}. Sources must be relative paths contained by this repository, including through symlinks.`,
+                details: unsafe,
+                text: { detailPrefix: "- " },
+            },
+        ];
+    }
+    const missing = missingSources(repoDir, sources);
+    if (missing.length > 0) {
+        return [
+            {
+                severity: "error",
+                code: "sources.path-missing",
+                message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(", ")}`,
+                details: missing,
+                text: { detailPrefix: "- " },
+            },
+        ];
+    }
+    const resolved = {
+        severity: "ok",
+        code: "sources.resolved",
+        message: `${label}: ${sources.length} source(s) resolve`,
+    };
+    // The walk happens here rather than inside the staleness branch below, even
+    // though only staleness needs the hashes: what the walk REFUSED to follow is
+    // a hole in the tie to the code whether or not anybody has vouched yet, and
+    // an unvouched service is exactly where a reader is about to decide the
+    // sources list is honest.
+    const { digest, files, index, skipped } = await sourcesDigest(repoDir, sources);
+    const findings = [
+        resolved,
+        ...skippedFindings(skipped, label),
+        ...(await walkFindings(repoDir, files, label)),
+    ];
+    // The paths are there; the question staleness answers is whether what is AT
+    // them is still what somebody read.
+    const stamped = stringField(fm, "sources_digest");
+    if (stamped === undefined) {
+        return [
+            ...findings,
+            {
+                severity: "warn",
+                code: "sources.unvouched",
+                message: `${label}: no sources_digest — nobody has vouched for this against the code, so nothing can tell you when it goes stale. Run \`loam vouch --service ${service}\`.`,
+            },
+        ];
+    }
+    const since = stringField(fm, "last_verified") ?? "it was stamped";
+    if (digest === stamped) {
+        return [
+            ...findings,
+            {
+                severity: "ok",
+                code: "sources.current",
+                message: `${label}: sources unchanged since ${since} (${files.length} file(s), digest ${digest})`,
+            },
+        ];
+    }
+    // What MOVED, when the stamp recorded enough to say. Repeating the frontmatter's
+    // own `sources` entries back at a reader — which is all this finding could do
+    // before `sources_files` existed — answers a question nobody asked: they wrote
+    // that list, and "one of these five directories changed somehow" is where the
+    // search starts, not where it ends.
+    const moved = movedSources(decodeSourceIndex(stringField(fm, "sources_files")), index);
+    return [
+        ...findings,
+        {
+            // A warning, not an error: the doc may still be right, and only a person
+            // can say. What loam knows is that nobody has looked since the code moved.
+            severity: "warn",
+            code: "sources.stale",
+            message: `${label}: sources changed since ${since}${moved.summary} — run \`loam vouch --pack --service ${service}\` for the reading list, then \`loam vouch --service ${service}\``,
+            details: moved.paths ?? sources,
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+/** The first path segment — the top-level directory, or a root file's own name. */
+function topLevel(path) {
+    const cut = path.indexOf("/");
+    return cut === -1 ? path : path.slice(0, cut);
+}
+/**
+ * Was the service WALKED, or only the part somebody wrote about?
+ *
+ * Every other check loam owns is computed from the documents, so a corpus can
+ * agree with itself perfectly while describing a third of a service — the
+ * failure `UNCHECKED` names as COMPLETENESS and then, correctly, declines to
+ * grade. This is the one measurement that escapes that circle, because it
+ * compares the document's `sources` against the REPOSITORY: a top-level path
+ * git tracks and no source reaches into is a part of the service nobody opened.
+ *
+ * git is the denominator on purpose. The alternative is walking the tree and
+ * excluding what does not look like source, which means a hand-maintained list
+ * of build directories that is wrong for the first language nobody thought of —
+ * and a check that is wrong for a whole ecosystem is a warning that ecosystem
+ * learns to ignore. `git ls-files` already answers "what does this repository
+ * consider its own", it is the author's own answer, and `node_modules` and
+ * `target/` fall out of it for free. Where git cannot answer — not a
+ * repository, not installed, a timeout — there is no denominator and therefore
+ * no finding: proving nothing and saying nothing is the same doctrine
+ * `sources.unverifiable-from-here` follows.
+ *
+ * TOP-LEVEL granularity, not a percentage threshold. A ratio needs a line
+ * drawn somewhere, and an invented threshold is exactly the number this
+ * codebase refuses to write into other people's dashboards; a named directory
+ * needs no threshold and is answerable — either it holds nothing this document
+ * owes, and the hand-back says so in one sentence, or the walk stopped early.
+ * The ratio still rides along in the message as a dial, where it informs
+ * without grading.
+ */
+async function walkFindings(repoDir, covered, label) {
+    const tracked = await gitTrackedFiles(repoDir);
+    if (tracked === null || tracked.length === 0)
+        return [];
+    // The honest intersection, not "every file under a directory somebody
+    // touched": reading one file in src/ does not make the other four hundred
+    // read, and a coverage number that says it does is worse than none.
+    const coveredSet = new Set(covered);
+    const hit = tracked.filter((p) => coveredSet.has(p)).length;
+    const ratio = `${String(hit)} of ${String(tracked.length)} tracked file(s)`;
+    const touched = new Set(covered.map(topLevel));
+    const untouched = [...new Set(tracked.map(topLevel))].filter((t) => !touched.has(t)).sort();
+    if (untouched.length === 0) {
+        return [
+            {
+                severity: "ok",
+                code: "sources.walked",
+                message: `${label}: sources reach into every top-level path this repository tracks (${ratio})`,
+            },
+        ];
+    }
+    return [
+        {
+            severity: "warn",
+            code: "sources.unwalked",
+            message: `${label}: sources cover ${ratio}, and ${String(untouched.length)} top-level path(s) were never opened. ` +
+                `Either they hold nothing this document owes — say which, and why, in the hand-back — or the walk stopped early ` +
+                `and the baseline describes part of a service.`,
+            details: untouched,
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+/**
+ * The paths the digest walk would not follow. Never silent: a symlink dropped
+ * on the floor is a file whose content nobody is watching, while the document
+ * beside it says `verified` — the digest cannot go stale over bytes it never
+ * hashed, so the one thing the stamp promises is quietly untrue for them.
+ *
+ * A warning, not an error, and for the same reason staleness is: the doc may be
+ * perfectly right about the code behind that link. What loam can say is that it
+ * is not watching it.
+ */
+function skippedFindings(skipped, label) {
+    if (skipped.length === 0)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "sources.skipped",
+            message: `${label}: ${skipped.length} path(s) under the listed sources were not hashed — the digest says nothing about what is behind them`,
+            details: skipped.map((s) => `${s.path} — ${s.reason}`),
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+/** The characters that made an entry a pattern under the glob dialect loam no longer ships. */
+const PATTERN_CHARS = /[*?[]/;
+/**
+ * The `sources` entries that look like glob patterns — anything containing
+ * `*`, `?` or `[`. Patterns are refused loudly everywhere sources are consumed
+ * (`loam vouch` refuses the run, `loam validate` grades an error), never
+ * resolved: the glob dialect loam used to ship silently differed from the
+ * gitignore/minimatch conventions authors assume — bracket classes literal,
+ * its own `**` handling — so a pattern quietly digested a different file set
+ * than intended, corrupting the staleness signal in both directions. A
+ * directory already means "everything beneath it", so the fix is to name one.
+ *
+ * The cost accepted with the rule: a real file with `[` in its name (a Next.js
+ * route, say) cannot be listed on its own — its parent directory covers it.
+ */
+export function patternSources(sources) {
+    return sources.filter((s) => PATTERN_CHARS.test(s.trim()));
+}
+/** The `sources` entries that resolve to nothing in this repo. */
+export function missingSources(repoDir, sources) {
+    return sources.filter((s) => !sourceExists(repoDir, s));
+}
+/** Entries that are absolute, traverse upward, or escape through a symlink. */
+export function unsafeSources(repoDir, sources) {
+    return sources.filter((source) => {
+        const cleaned = source.trim();
+        if (cleaned.length === 0)
+            return false;
+        try {
+            resolveInside(repoDir, cleaned, `source '${source}'`);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    });
+}
+/** Does a `sources` entry point at something real? Literal paths only, checked exactly. */
+function sourceExists(repoDir, source) {
+    const cleaned = source.trim();
+    if (cleaned.length === 0)
+        return false;
+    try {
+        return existsSync(resolveInside(repoDir, cleaned, `source '${source}'`));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=sources.js.map

package/dist/core/provenance/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../../src/core/provenance/sources.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `sources` list: vetting the entries an author wrote — patterns, escapes,\n * missing paths, the refusal vocabulary `loam vouch` and `loam validate` share\n * — and grading the vetted list against the service repo: resolved, unvouched,\n * current, stale, and whether the walk reached the whole repository. Vetting\n * and grading are one doctrine about one field, so they live in one file.\n */\nimport { existsSync } from \"node:fs\";\nimport { listField, stringField, type Frontmatter } from \"../document/frontmatter.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { resolveInside } from \"../kernel/path-safety.js\";\nimport { decodeSourceIndex, movedSources, sourcesDigest } from \"./stamp.js\";\nimport type { SkippedSource } from \"./walk.js\";\nimport { gitTrackedFiles } from \"./git.js\";\n\nexport async function sourceFindings(\n  fm: Frontmatter,\n  service: string,\n  label: string,\n  repoDir: string | undefined,\n): Promise<Finding[]> {\n  const sources = listField(fm, \"sources\");\n  if (sources.length === 0) {\n    return [\n      {\n        severity: \"warn\",\n        code: \"sources.absent\",\n        message: `${label} names no sources — nothing ties it to the code, so nothing can tell you when it goes out of date`,\n      },\n    ];\n  }\n  // Someone else's repository: the paths describe a tree loam is not standing in.\n  if (repoDir === undefined) return [];\n\n  // Before existence: a pattern entry would \"not exist\" as a literal path, and\n  // grading it missing would send the author fixing the wrong thing.\n  const patterns = patternSources(sources);\n  if (patterns.length > 0) {\n    return [\n      {\n        severity: \"error\",\n        code: \"sources.path-missing\",\n        message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(\", \")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it).`,\n        details: patterns,\n        text: { detailPrefix: \"- \" },\n      },\n    ];\n  }\n\n  const unsafe = unsafeSources(repoDir, sources);\n  if (unsafe.length > 0) {\n    return [\n      {\n        severity: \"error\",\n        code: \"sources.path-outside\",\n        message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(\", \")}. Sources must be relative paths contained by this repository, including through symlinks.`,\n        details: unsafe,\n        text: { detailPrefix: \"- \" },\n      },\n    ];\n  }\n\n  const missing = missingSources(repoDir, sources);\n  if (missing.length > 0) {\n    return [\n      {\n        severity: \"error\",\n        code: \"sources.path-missing\",\n        message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(\", \")}`,\n        details: missing,\n        text: { detailPrefix: \"- \" },\n      },\n    ];\n  }\n  const resolved: Finding = {\n    severity: \"ok\",\n    code: \"sources.resolved\",\n    message: `${label}: ${sources.length} source(s) resolve`,\n  };\n\n  // The walk happens here rather than inside the staleness branch below, even\n  // though only staleness needs the hashes: what the walk REFUSED to follow is\n  // a hole in the tie to the code whether or not anybody has vouched yet, and\n  // an unvouched service is exactly where a reader is about to decide the\n  // sources list is honest.\n  const { digest, files, index, skipped } = await sourcesDigest(repoDir, sources);\n  const findings: Finding[] = [\n    resolved,\n    ...skippedFindings(skipped, label),\n    ...(await walkFindings(repoDir, files, label)),\n  ];\n\n  // The paths are there; the question staleness answers is whether what is AT\n  // them is still what somebody read.\n  const stamped = stringField(fm, \"sources_digest\");\n  if (stamped === undefined) {\n    return [\n      ...findings,\n      {\n        severity: \"warn\",\n        code: \"sources.unvouched\",\n        message: `${label}: no sources_digest — nobody has vouched for this against the code, so nothing can tell you when it goes stale. Run \\`loam vouch --service ${service}\\`.`,\n      },\n    ];\n  }\n\n  const since = stringField(fm, \"last_verified\") ?? \"it was stamped\";\n  if (digest === stamped) {\n    return [\n      ...findings,\n      {\n        severity: \"ok\",\n        code: \"sources.current\",\n        message: `${label}: sources unchanged since ${since} (${files.length} file(s), digest ${digest})`,\n      },\n    ];\n  }\n\n  // What MOVED, when the stamp recorded enough to say. Repeating the frontmatter's\n  // own `sources` entries back at a reader — which is all this finding could do\n  // before `sources_files` existed — answers a question nobody asked: they wrote\n  // that list, and \"one of these five directories changed somehow\" is where the\n  // search starts, not where it ends.\n  const moved = movedSources(decodeSourceIndex(stringField(fm, \"sources_files\")), index);\n  return [\n    ...findings,\n    {\n      // A warning, not an error: the doc may still be right, and only a person\n      // can say. What loam knows is that nobody has looked since the code moved.\n      severity: \"warn\",\n      code: \"sources.stale\",\n      message: `${label}: sources changed since ${since}${moved.summary} — run \\`loam vouch --pack --service ${service}\\` for the reading list, then \\`loam vouch --service ${service}\\``,\n      details: moved.paths ?? sources,\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n\n/** The first path segment — the top-level directory, or a root file's own name. */\nfunction topLevel(path: string): string {\n  const cut = path.indexOf(\"/\");\n  return cut === -1 ? path : path.slice(0, cut);\n}\n\n/**\n * Was the service WALKED, or only the part somebody wrote about?\n *\n * Every other check loam owns is computed from the documents, so a corpus can\n * agree with itself perfectly while describing a third of a service — the\n * failure `UNCHECKED` names as COMPLETENESS and then, correctly, declines to\n * grade. This is the one measurement that escapes that circle, because it\n * compares the document's `sources` against the REPOSITORY: a top-level path\n * git tracks and no source reaches into is a part of the service nobody opened.\n *\n * git is the denominator on purpose. The alternative is walking the tree and\n * excluding what does not look like source, which means a hand-maintained list\n * of build directories that is wrong for the first language nobody thought of —\n * and a check that is wrong for a whole ecosystem is a warning that ecosystem\n * learns to ignore. `git ls-files` already answers \"what does this repository\n * consider its own\", it is the author's own answer, and `node_modules` and\n * `target/` fall out of it for free. Where git cannot answer — not a\n * repository, not installed, a timeout — there is no denominator and therefore\n * no finding: proving nothing and saying nothing is the same doctrine\n * `sources.unverifiable-from-here` follows.\n *\n * TOP-LEVEL granularity, not a percentage threshold. A ratio needs a line\n * drawn somewhere, and an invented threshold is exactly the number this\n * codebase refuses to write into other people's dashboards; a named directory\n * needs no threshold and is answerable — either it holds nothing this document\n * owes, and the hand-back says so in one sentence, or the walk stopped early.\n * The ratio still rides along in the message as a dial, where it informs\n * without grading.\n */\nasync function walkFindings(repoDir: string, covered: string[], label: string): Promise<Finding[]> {\n  const tracked = await gitTrackedFiles(repoDir);\n  if (tracked === null || tracked.length === 0) return [];\n\n  // The honest intersection, not \"every file under a directory somebody\n  // touched\": reading one file in src/ does not make the other four hundred\n  // read, and a coverage number that says it does is worse than none.\n  const coveredSet = new Set(covered);\n  const hit = tracked.filter((p) => coveredSet.has(p)).length;\n  const ratio = `${String(hit)} of ${String(tracked.length)} tracked file(s)`;\n\n  const touched = new Set(covered.map(topLevel));\n  const untouched = [...new Set(tracked.map(topLevel))].filter((t) => !touched.has(t)).sort();\n  if (untouched.length === 0) {\n    return [\n      {\n        severity: \"ok\",\n        code: \"sources.walked\",\n        message: `${label}: sources reach into every top-level path this repository tracks (${ratio})`,\n      },\n    ];\n  }\n  return [\n    {\n      severity: \"warn\",\n      code: \"sources.unwalked\",\n      message:\n        `${label}: sources cover ${ratio}, and ${String(untouched.length)} top-level path(s) were never opened. ` +\n        `Either they hold nothing this document owes — say which, and why, in the hand-back — or the walk stopped early ` +\n        `and the baseline describes part of a service.`,\n      details: untouched,\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n\n/**\n * The paths the digest walk would not follow. Never silent: a symlink dropped\n * on the floor is a file whose content nobody is watching, while the document\n * beside it says `verified` — the digest cannot go stale over bytes it never\n * hashed, so the one thing the stamp promises is quietly untrue for them.\n *\n * A warning, not an error, and for the same reason staleness is: the doc may be\n * perfectly right about the code behind that link. What loam can say is that it\n * is not watching it.\n */\nfunction skippedFindings(skipped: SkippedSource[], label: string): Finding[] {\n  if (skipped.length === 0) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"sources.skipped\",\n      message: `${label}: ${skipped.length} path(s) under the listed sources were not hashed — the digest says nothing about what is behind them`,\n      details: skipped.map((s) => `${s.path} — ${s.reason}`),\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n\n/** The characters that made an entry a pattern under the glob dialect loam no longer ships. */\nconst PATTERN_CHARS = /[*?[]/;\n\n/**\n * The `sources` entries that look like glob patterns — anything containing\n * `*`, `?` or `[`. Patterns are refused loudly everywhere sources are consumed\n * (`loam vouch` refuses the run, `loam validate` grades an error), never\n * resolved: the glob dialect loam used to ship silently differed from the\n * gitignore/minimatch conventions authors assume — bracket classes literal,\n * its own `**` handling — so a pattern quietly digested a different file set\n * than intended, corrupting the staleness signal in both directions. A\n * directory already means \"everything beneath it\", so the fix is to name one.\n *\n * The cost accepted with the rule: a real file with `[` in its name (a Next.js\n * route, say) cannot be listed on its own — its parent directory covers it.\n */\nexport function patternSources(sources: string[]): string[] {\n  return sources.filter((s) => PATTERN_CHARS.test(s.trim()));\n}\n\n/** The `sources` entries that resolve to nothing in this repo. */\nexport function missingSources(repoDir: string, sources: string[]): string[] {\n  return sources.filter((s) => !sourceExists(repoDir, s));\n}\n\n/** Entries that are absolute, traverse upward, or escape through a symlink. */\nexport function unsafeSources(repoDir: string, sources: string[]): string[] {\n  return sources.filter((source) => {\n    const cleaned = source.trim();\n    if (cleaned.length === 0) return false;\n    try {\n      resolveInside(repoDir, cleaned, `source '${source}'`);\n      return false;\n    } catch {\n      return true;\n    }\n  });\n}\n\n/** Does a `sources` entry point at something real? Literal paths only, checked exactly. */\nfunction sourceExists(repoDir: string, source: string): boolean {\n  const cleaned = source.trim();\n  if (cleaned.length === 0) return false;\n  try {\n    return existsSync(resolveInside(repoDir, cleaned, `source '${source}'`));\n  } catch {\n    return false;\n  }\n}\n"]}

package/dist/core/provenance/stamp.js

@@ -0,0 +1,232 @@
+/**
+ * The stamp vocabulary: what `loam vouch` computes for a frontmatter stamp and
+ * what a later check reads back out of one — `sources_digest` and the per-file
+ * `sources_files` index beside it, the document's own `content_digest`, and
+ * the local calendar day `last_verified` carries.
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { rawBody } from "../document/frontmatter.js";
+import { collectSources } from "./walk.js";
+/**
+ * The local calendar day, for the two commands that date a stamp. A vouch or a
+ * verification record is a person saying "today I read this", so it is their
+ * date, not UTC's — `toISOString` files an evening in the Americas under
+ * tomorrow. It sits here because this module already owns the stamp vocabulary
+ * the date is written into.
+ */
+export function today(now) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+/* ------------------------------------------------------------------ */
+/* The content digest                                                  */
+/* ------------------------------------------------------------------ */
+/** How much of the sha256 is written into the document. */
+const DIGEST_LENGTH = 16;
+/** How many source files the digest reads at once — see `sourcesDigest`. */
+const DIGEST_READ_BATCH = 32;
+/**
+ * Digest the CONTENT of the files `sources` names. The recipe is spelled out
+ * because the value is written into documents, and anything reading them has to
+ * be able to reproduce it:
+ *
+ *   1. expand each entry to repo-relative file paths (`/` separators) — a file
+ *      is itself, a directory everything beneath it, minus what the repository
+ *      does not consider its own (see collectSources) — sorted and de-duplicated;
+ *   2. per file, `sha256(bytes)`;
+ *   3. feed `<path>\0<hex>\n` for each file, in that order, into an outer
+ *      sha256;
+ *   4. keep the first 16 hex characters.
+ *
+ * Content, not mtime: git does not preserve modification times, so after a
+ * fresh clone every file looks changed and the check would be false positives
+ * end to end. Bytes survive the clone. Hashing the path alongside the content
+ * means a rename registers, which is what a reader of the doc would want.
+ *
+ * 64 bits is a change detector, not a seal — it answers "did this move?", and
+ * an adversary who wants a collision can have one.
+ */
+export async function sourcesDigest(repoDir, sources) {
+    const { found, skipped } = await collectSources(repoDir, sources);
+    const outer = createHash("sha256");
+    const index = [];
+    // Read in fixed batches, hash in array order. `found` is already sorted and
+    // every file's own sha depends on nothing but its own bytes, so the sequence
+    // fed to `outer` — and therefore the digest — is unchanged by construction;
+    // only the waiting overlaps. A `sources: [src/]` over a real service repo is
+    // thousands of files, and one-await-per-file spent nearly all of its time
+    // idle. The batch is bounded rather than a single `Promise.all` over the
+    // whole list because an unbounded fan-out over a source tree runs the process
+    // out of file descriptors, which would turn a stamp into an EMFILE.
+    for (let start = 0; start < found.length; start += DIGEST_READ_BATCH) {
+        const hashed = await Promise.all(found.slice(start, start + DIGEST_READ_BATCH).map(async (file) => ({
+            rel: file.rel,
+            content: createHash("sha256").update(await readFile(file.abs)).digest("hex"),
+        })));
+        for (const { rel, content } of hashed) {
+            outer.update(`${rel}\0${content}\n`);
+            index.push({ path: rel, sha: content.slice(0, DIGEST_LENGTH) });
+        }
+    }
+    // `empty` is deliberately not set here: it is a sentence about a named
+    // document, and a digest has no name to put in it. Callers that need it say
+    // emptySourcesMessage(label, sources) — the same words, from one definition.
+    return { digest: outer.digest("hex").slice(0, DIGEST_LENGTH), files: index.map((e) => e.path), index, skipped };
+}
+/**
+ * What a `sources` list actually covers — the digest's file set without the
+ * hashing.
+ *
+ * Exported because two commands must give the SAME answer to "does this list
+ * cover anything?". `loam vouch` refuses to stamp an expansion that covers no
+ * files (a digest over nothing never changes, so the stamp would read as
+ * current forever), and until `loam validate` could say the same thing in the
+ * same words, an author got a green validate followed by a vouch that refused —
+ * two commands contradicting each other about one document, with nothing in the
+ * green run hinting at it.
+ */
+export async function expandSourceFiles(repoDir, sources, label) {
+    const { found, skipped } = await collectSources(repoDir, sources);
+    const files = found.map((f) => f.rel);
+    return { files, skipped, ...(files.length === 0 ? { empty: emptySourcesMessage(label, sources) } : {}) };
+}
+/**
+ * The one sentence for "these paths exist and cover no file". One definition,
+ * because `vouch`'s refusal and `validate`'s finding are the same diagnosis
+ * about the same document and must not drift into two descriptions of it — the
+ * author fixes it once, in the sources list.
+ */
+export function emptySourcesMessage(label, sources) {
+    return `${label}: the sources listed match no files — ${sources.join(", ")}. A digest over nothing would read as current forever.`;
+}
+/**
+ * The stamp `loam vouch` writes into `content_digest`: sha256 of the
+ * document's own BODY — every byte after the frontmatter block (below the
+ * closing `---` line and its newline; `rawBody` is the one definition of that
+ * cut) — first 16 hex characters, the sources recipe's length.
+ *
+ * Byte-exact, no normalization. Body-only is load-bearing: vouch itself
+ * rewrites the frontmatter as it stamps, and a later frontmatter-only edit
+ * (another vouch, a corrected owner) must not read as the document moving.
+ */
+export function contentDigest(source) {
+    return createHash("sha256").update(rawBody(source), "utf8").digest("hex").slice(0, DIGEST_LENGTH);
+}
+/* ------------------------------------------------------------------ */
+/* The per-file index: what `sources.stale` names                      */
+/* ------------------------------------------------------------------ */
+/**
+ * How many files `sources_files` will list one by one before it gives up and
+ * records only how many there were.
+ *
+ * A readability budget, not a correctness one: the index lives in the header of
+ * a document a person reads, and a `sources: [src/]` over a legacy service can
+ * expand to thousands of files. Past the limit `sources.stale` falls back to
+ * repeating the `sources` entries — worse advice, but a spec.md whose
+ * frontmatter is longer than its requirements is worse still.
+ */
+const SOURCE_INDEX_LIMIT = 100;
+/**
+ * The `sources_files` value `loam vouch` stamps beside `sources_digest`: one
+ * `<sha>  <path>` line per file (sha256sum's layout, and its column order, so
+ * the path may contain spaces), or just the file count once the list would run
+ * past SOURCE_INDEX_LIMIT.
+ *
+ * Its whole purpose is the next `sources.stale`. `sources_digest` can say THAT
+ * the code moved and never which part of it; with the index a reader gets the
+ * added, removed and changed paths, which is the difference between re-reading
+ * one file and re-reading a directory. It is also a readable git diff in the
+ * docs repo: the vouch commit shows exactly which source files the stamp now
+ * stands over.
+ */
+export function encodeSourceIndex(index) {
+    if (index.length > SOURCE_INDEX_LIMIT)
+        return String(index.length);
+    return index.map((e) => `${e.sha}  ${e.path}`).join("\n");
+}
+/**
+ * Read back what `encodeSourceIndex` wrote. Anything unrecognised reads as "the
+ * stamp said nothing" rather than as an empty index: a header nobody can parse
+ * must not turn into a `sources.stale` claiming every file was deleted.
+ */
+export function decodeSourceIndex(stamped) {
+    if (stamped === undefined)
+        return { entries: null };
+    const text = stamped.trim();
+    if (text.length === 0)
+        return { entries: null };
+    if (/^\d+$/.test(text))
+        return { entries: null, count: Number(text) };
+    const entries = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^([0-9a-f]{16})\s+(.+)$/.exec(line.trim());
+        if (match === null)
+            return { entries: null };
+        entries.set(match[2], match[1]);
+    }
+    return { entries, count: entries.size };
+}
+/**
+ * The structured half of the answer: which paths were added, changed and
+ * removed between a stamp and the current index — or null when the stamp
+ * cannot say. Null covers two distinct silences on purpose, both of which mean
+ * "do not print a path list": a stamp that recorded no per-file entries (the
+ * count-only >100-file fallback, or a header nobody could parse), and an index
+ * that AGREES with the current tree while the caller's digest comparison said
+ * stale — a contradiction (a truncation collision, or a hand-edited header),
+ * where an empty delta under a staleness warning would read as proof that
+ * nothing moved. Callers that need the counts anyway read `stamp.count`.
+ *
+ * Extracted from `movedSources` (which now consumes it) when the re-vouch
+ * reading pack became a second reader: the pack wants the three lists as
+ * data, the stale finding wants them annotated in one column.
+ */
+export function sourceDelta(stamp, now) {
+    if (stamp.entries === null)
+        return null;
+    const added = [];
+    const changed = [];
+    const current = new Map(now.map((e) => [e.path, e.sha]));
+    for (const [path, sha] of current) {
+        const before = stamp.entries.get(path);
+        if (before === undefined)
+            added.push(path);
+        else if (before !== sha)
+            changed.push(path);
+    }
+    const removed = [...stamp.entries.keys()].filter((path) => !current.has(path));
+    if (added.length + changed.length + removed.length === 0)
+        return null;
+    added.sort();
+    changed.sort();
+    removed.sort();
+    return { added, changed, removed };
+}
+/**
+ * added / removed / changed, from the stamped index against the current one.
+ * The annotation travels IN the detail line rather than in three separate
+ * lists: a reader scanning a stale report wants the paths in one column, and
+ * "which of the three" is one word wide.
+ */
+export function movedSources(stamp, now) {
+    const delta = sourceDelta(stamp, now);
+    if (delta === null) {
+        // A recorded index that came back null is the contradiction case — say
+        // nothing rather than print an empty list under a staleness warning. With
+        // no index at all, the count alone still beats silence: "12 files then,
+        // 14 now" tells a reader to go looking for two new files.
+        return {
+            summary: stamp.entries !== null || stamp.count === undefined
+                ? ""
+                : ` (${stamp.count} file(s) then, ${now.length} now)`,
+        };
+    }
+    const paths = [
+        ...delta.added.map((path) => `added    ${path}`),
+        ...delta.changed.map((path) => `changed  ${path}`),
+        ...delta.removed.map((path) => `removed  ${path}`),
+    ].sort();
+    return { paths, summary: ` (${paths.length} path(s) moved)` };
+}
+//# sourceMappingURL=stamp.js.map

package/dist/core/provenance/stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp.js","sourceRoot":"","sources":["../../../src/core/provenance/stamp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The stamp vocabulary: what `loam vouch` computes for a frontmatter stamp and\n * what a later check reads back out of one — `sources_digest` and the per-file\n * `sources_files` index beside it, the document's own `content_digest`, and\n * the local calendar day `last_verified` carries.\n */\nimport { createHash } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { rawBody } from \"../document/frontmatter.js\";\nimport { collectSources, type SkippedSource } from \"./walk.js\";\n\n/**\n * The local calendar day, for the two commands that date a stamp. A vouch or a\n * verification record is a person saying \"today I read this\", so it is their\n * date, not UTC's — `toISOString` files an evening in the Americas under\n * tomorrow. It sits here because this module already owns the stamp vocabulary\n * the date is written into.\n */\nexport function today(now: Date): string {\n  const pad = (n: number): string => String(n).padStart(2, \"0\");\n  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;\n}\n\n/* ------------------------------------------------------------------ */\n/* The content digest                                                  */\n/* ------------------------------------------------------------------ */\n\n/** How much of the sha256 is written into the document. */\nconst DIGEST_LENGTH = 16;\n\n/** How many source files the digest reads at once — see `sourcesDigest`. */\nconst DIGEST_READ_BATCH = 32;\n\nexport interface SourcesDigest extends SourcesExpansion {\n  /** The stamp that goes in `sources_digest`. */\n  digest: string;\n  /**\n   * Per file, its own short sha — the record `sources_files` carries so a later\n   * `sources.stale` can name what moved instead of guessing. Same order as `files`.\n   */\n  index: SourceIndexEntry[];\n}\n\n/** One file's share of the stamp: what it is called, and what it said. */\nexport interface SourceIndexEntry {\n  /** Repo-relative, `/`-separated. */\n  path: string;\n  /** sha256 of its bytes, truncated the way `sources_digest` is. */\n  sha: string;\n}\n\n/** What a `sources` list covers, and what it does not. */\nexport interface SourcesExpansion {\n  /** Repo-relative paths, sorted — exactly what a digest would hash. */\n  files: string[];\n  /** Everything the walk refused to follow. Empty in the ordinary case. */\n  skipped: SkippedSource[];\n  /**\n   * Set only when `files` is empty: the one sentence that says the list covers\n   * nothing. `loam vouch` refuses with it, `loam validate` grades it — see\n   * emptySourcesMessage for why they must be the same words.\n   */\n  empty?: string;\n}\n\n/**\n * Digest the CONTENT of the files `sources` names. The recipe is spelled out\n * because the value is written into documents, and anything reading them has to\n * be able to reproduce it:\n *\n *   1. expand each entry to repo-relative file paths (`/` separators) — a file\n *      is itself, a directory everything beneath it, minus what the repository\n *      does not consider its own (see collectSources) — sorted and de-duplicated;\n *   2. per file, `sha256(bytes)`;\n *   3. feed `<path>\\0<hex>\\n` for each file, in that order, into an outer\n *      sha256;\n *   4. keep the first 16 hex characters.\n *\n * Content, not mtime: git does not preserve modification times, so after a\n * fresh clone every file looks changed and the check would be false positives\n * end to end. Bytes survive the clone. Hashing the path alongside the content\n * means a rename registers, which is what a reader of the doc would want.\n *\n * 64 bits is a change detector, not a seal — it answers \"did this move?\", and\n * an adversary who wants a collision can have one.\n */\nexport async function sourcesDigest(repoDir: string, sources: string[]): Promise<SourcesDigest> {\n  const { found, skipped } = await collectSources(repoDir, sources);\n  const outer = createHash(\"sha256\");\n  const index: SourceIndexEntry[] = [];\n  // Read in fixed batches, hash in array order. `found` is already sorted and\n  // every file's own sha depends on nothing but its own bytes, so the sequence\n  // fed to `outer` — and therefore the digest — is unchanged by construction;\n  // only the waiting overlaps. A `sources: [src/]` over a real service repo is\n  // thousands of files, and one-await-per-file spent nearly all of its time\n  // idle. The batch is bounded rather than a single `Promise.all` over the\n  // whole list because an unbounded fan-out over a source tree runs the process\n  // out of file descriptors, which would turn a stamp into an EMFILE.\n  for (let start = 0; start < found.length; start += DIGEST_READ_BATCH) {\n    const hashed = await Promise.all(\n      found.slice(start, start + DIGEST_READ_BATCH).map(async (file) => ({\n        rel: file.rel,\n        content: createHash(\"sha256\").update(await readFile(file.abs)).digest(\"hex\"),\n      })),\n    );\n    for (const { rel, content } of hashed) {\n      outer.update(`${rel}\\0${content}\\n`);\n      index.push({ path: rel, sha: content.slice(0, DIGEST_LENGTH) });\n    }\n  }\n  // `empty` is deliberately not set here: it is a sentence about a named\n  // document, and a digest has no name to put in it. Callers that need it say\n  // emptySourcesMessage(label, sources) — the same words, from one definition.\n  return { digest: outer.digest(\"hex\").slice(0, DIGEST_LENGTH), files: index.map((e) => e.path), index, skipped };\n}\n\n/**\n * What a `sources` list actually covers — the digest's file set without the\n * hashing.\n *\n * Exported because two commands must give the SAME answer to \"does this list\n * cover anything?\". `loam vouch` refuses to stamp an expansion that covers no\n * files (a digest over nothing never changes, so the stamp would read as\n * current forever), and until `loam validate` could say the same thing in the\n * same words, an author got a green validate followed by a vouch that refused —\n * two commands contradicting each other about one document, with nothing in the\n * green run hinting at it.\n */\nexport async function expandSourceFiles(\n  repoDir: string,\n  sources: string[],\n  label: string,\n): Promise<SourcesExpansion> {\n  const { found, skipped } = await collectSources(repoDir, sources);\n  const files = found.map((f) => f.rel);\n  return { files, skipped, ...(files.length === 0 ? { empty: emptySourcesMessage(label, sources) } : {}) };\n}\n\n/**\n * The one sentence for \"these paths exist and cover no file\". One definition,\n * because `vouch`'s refusal and `validate`'s finding are the same diagnosis\n * about the same document and must not drift into two descriptions of it — the\n * author fixes it once, in the sources list.\n */\nexport function emptySourcesMessage(label: string, sources: string[]): string {\n  return `${label}: the sources listed match no files — ${sources.join(\", \")}. A digest over nothing would read as current forever.`;\n}\n\n/**\n * The stamp `loam vouch` writes into `content_digest`: sha256 of the\n * document's own BODY — every byte after the frontmatter block (below the\n * closing `---` line and its newline; `rawBody` is the one definition of that\n * cut) — first 16 hex characters, the sources recipe's length.\n *\n * Byte-exact, no normalization. Body-only is load-bearing: vouch itself\n * rewrites the frontmatter as it stamps, and a later frontmatter-only edit\n * (another vouch, a corrected owner) must not read as the document moving.\n */\nexport function contentDigest(source: string): string {\n  return createHash(\"sha256\").update(rawBody(source), \"utf8\").digest(\"hex\").slice(0, DIGEST_LENGTH);\n}\n\n/* ------------------------------------------------------------------ */\n/* The per-file index: what `sources.stale` names                      */\n/* ------------------------------------------------------------------ */\n\n/**\n * How many files `sources_files` will list one by one before it gives up and\n * records only how many there were.\n *\n * A readability budget, not a correctness one: the index lives in the header of\n * a document a person reads, and a `sources: [src/]` over a legacy service can\n * expand to thousands of files. Past the limit `sources.stale` falls back to\n * repeating the `sources` entries — worse advice, but a spec.md whose\n * frontmatter is longer than its requirements is worse still.\n */\nconst SOURCE_INDEX_LIMIT = 100;\n\n/**\n * The `sources_files` value `loam vouch` stamps beside `sources_digest`: one\n * `<sha>  <path>` line per file (sha256sum's layout, and its column order, so\n * the path may contain spaces), or just the file count once the list would run\n * past SOURCE_INDEX_LIMIT.\n *\n * Its whole purpose is the next `sources.stale`. `sources_digest` can say THAT\n * the code moved and never which part of it; with the index a reader gets the\n * added, removed and changed paths, which is the difference between re-reading\n * one file and re-reading a directory. It is also a readable git diff in the\n * docs repo: the vouch commit shows exactly which source files the stamp now\n * stands over.\n */\nexport function encodeSourceIndex(index: SourceIndexEntry[]): string {\n  if (index.length > SOURCE_INDEX_LIMIT) return String(index.length);\n  return index.map((e) => `${e.sha}  ${e.path}`).join(\"\\n\");\n}\n\n/** What a stamped `sources_files` says: the per-file shas, the count, or nothing. */\ninterface StampedIndex {\n  /** path -> sha, or null when the stamp did not record them. */\n  entries: Map<string, string> | null;\n  /** How many files the stamp covered, when that is knowable. */\n  count?: number;\n}\n\n/**\n * Read back what `encodeSourceIndex` wrote. Anything unrecognised reads as \"the\n * stamp said nothing\" rather than as an empty index: a header nobody can parse\n * must not turn into a `sources.stale` claiming every file was deleted.\n */\nexport function decodeSourceIndex(stamped: string | undefined): StampedIndex {\n  if (stamped === undefined) return { entries: null };\n  const text = stamped.trim();\n  if (text.length === 0) return { entries: null };\n  if (/^\\d+$/.test(text)) return { entries: null, count: Number(text) };\n\n  const entries = new Map<string, string>();\n  for (const line of text.split(\"\\n\")) {\n    const match = /^([0-9a-f]{16})\\s+(.+)$/.exec(line.trim());\n    if (match === null) return { entries: null };\n    entries.set(match[2]!, match[1]!);\n  }\n  return { entries, count: entries.size };\n}\n\n/** The paths that moved between a stamp and now, with a phrase for the message. */\ninterface MovedSources {\n  /** Annotated paths, or undefined when the stamp did not record enough to say. */\n  paths?: string[];\n  /** Appended to the `sources.stale` message; empty when there is nothing to add. */\n  summary: string;\n}\n\n/**\n * The structured half of the answer: which paths were added, changed and\n * removed between a stamp and the current index — or null when the stamp\n * cannot say. Null covers two distinct silences on purpose, both of which mean\n * \"do not print a path list\": a stamp that recorded no per-file entries (the\n * count-only >100-file fallback, or a header nobody could parse), and an index\n * that AGREES with the current tree while the caller's digest comparison said\n * stale — a contradiction (a truncation collision, or a hand-edited header),\n * where an empty delta under a staleness warning would read as proof that\n * nothing moved. Callers that need the counts anyway read `stamp.count`.\n *\n * Extracted from `movedSources` (which now consumes it) when the re-vouch\n * reading pack became a second reader: the pack wants the three lists as\n * data, the stale finding wants them annotated in one column.\n */\nexport function sourceDelta(\n  stamp: StampedIndex,\n  now: SourceIndexEntry[],\n): { added: string[]; changed: string[]; removed: string[] } | null {\n  if (stamp.entries === null) return null;\n  const added: string[] = [];\n  const changed: string[] = [];\n  const current = new Map(now.map((e) => [e.path, e.sha]));\n  for (const [path, sha] of current) {\n    const before = stamp.entries.get(path);\n    if (before === undefined) added.push(path);\n    else if (before !== sha) changed.push(path);\n  }\n  const removed = [...stamp.entries.keys()].filter((path) => !current.has(path));\n  if (added.length + changed.length + removed.length === 0) return null;\n  added.sort();\n  changed.sort();\n  removed.sort();\n  return { added, changed, removed };\n}\n\n/**\n * added / removed / changed, from the stamped index against the current one.\n * The annotation travels IN the detail line rather than in three separate\n * lists: a reader scanning a stale report wants the paths in one column, and\n * \"which of the three\" is one word wide.\n */\nexport function movedSources(stamp: StampedIndex, now: SourceIndexEntry[]): MovedSources {\n  const delta = sourceDelta(stamp, now);\n  if (delta === null) {\n    // A recorded index that came back null is the contradiction case — say\n    // nothing rather than print an empty list under a staleness warning. With\n    // no index at all, the count alone still beats silence: \"12 files then,\n    // 14 now\" tells a reader to go looking for two new files.\n    return {\n      summary:\n        stamp.entries !== null || stamp.count === undefined\n          ? \"\"\n          : ` (${stamp.count} file(s) then, ${now.length} now)`,\n    };\n  }\n  const paths = [\n    ...delta.added.map((path) => `added    ${path}`),\n    ...delta.changed.map((path) => `changed  ${path}`),\n    ...delta.removed.map((path) => `removed  ${path}`),\n  ].sort();\n  return { paths, summary: ` (${paths.length} path(s) moved)` };\n}\n"]}