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

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

package/dist/core/provenance/sources.js

@@ -0,0 +1,280 @@
+/**
+ * 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, repo) {
+    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 (repo === undefined)
+        return [];
+    const repoDir = repo.dir;
+    // 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(repo, 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.
+ *
+ * Two kinds of tracked file are NOT the service, and the denominator leaves
+ * them out — both by a rule that needs no list of what source looks like:
+ *
+ *   - loam's OWN files: `loam.json` and the agent files `loam init` recorded in
+ *     it (`SourcesRepo.loamOwned`). loam wrote them and knows they hold nothing
+ *     a spec owes; counting them made the warning fire in every service repo
+ *     straight after a fresh vouch, with no honest way to clear it — listing
+ *     loam.json in `sources` would stale the digest on every `loam init`.
+ *   - `.gitignore`, at any depth: it is the file that DEFINES this check's
+ *     denominator — what git considers the repository's own — so it is the
+ *     measuring instrument, not a part of the service anybody could owe a
+ *     reading of. The line is deliberately that narrow: `package.json`, a
+ *     README or `.github/` are the author's call (they can hold what a spec
+ *     owes), so they stay in and are answered in the hand-back as before.
+ */
+async function walkFindings(repo, covered, label) {
+    const owned = new Set(repo.loamOwned);
+    const tracked = (await gitTrackedFiles(repo.dir))?.filter((p) => !owned.has(p) && p !== ".gitignore" && !p.endsWith("/.gitignore"));
+    if (tracked === undefined || 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\n/**\n * The service repository `sources` resolve against, as the walk check needs\n * it: where it is, and which files in it are loam's own.\n */\nexport interface SourcesRepo {\n  dir: string;\n  /**\n   * Repo-relative paths loam wrote and owns there — its `loam.json` and the\n   * agent files `loam init` recorded in it. No `sources` list owes a reading of\n   * them, so `walkFindings` leaves them out of its denominator.\n   */\n  loamOwned: readonly string[];\n}\n\nexport async function sourceFindings(\n  fm: Frontmatter,\n  service: string,\n  label: string,\n  repo: SourcesRepo | 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 (repo === undefined) return [];\n  const repoDir = repo.dir;\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(repo, 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 *\n * Two kinds of tracked file are NOT the service, and the denominator leaves\n * them out — both by a rule that needs no list of what source looks like:\n *\n *   - loam's OWN files: `loam.json` and the agent files `loam init` recorded in\n *     it (`SourcesRepo.loamOwned`). loam wrote them and knows they hold nothing\n *     a spec owes; counting them made the warning fire in every service repo\n *     straight after a fresh vouch, with no honest way to clear it — listing\n *     loam.json in `sources` would stale the digest on every `loam init`.\n *   - `.gitignore`, at any depth: it is the file that DEFINES this check's\n *     denominator — what git considers the repository's own — so it is the\n *     measuring instrument, not a part of the service anybody could owe a\n *     reading of. The line is deliberately that narrow: `package.json`, a\n *     README or `.github/` are the author's call (they can hold what a spec\n *     owes), so they stay in and are answered in the hand-back as before.\n */\nasync function walkFindings(repo: SourcesRepo, covered: string[], label: string): Promise<Finding[]> {\n  const owned = new Set(repo.loamOwned);\n  const tracked = (await gitTrackedFiles(repo.dir))?.filter(\n    (p) => !owned.has(p) && p !== \".gitignore\" && !p.endsWith(\"/.gitignore\"),\n  );\n  if (tracked === undefined || 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"]}