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

package/dist/core/provenance/gitq/moves.js

@@ -0,0 +1,139 @@
+/**
+ * The subsystem surface's git questions, beside the provenance ones
+ * (`../git.ts`) whose `gitText` — one spawn, its timeout and its capped
+ * stdout reader — they ask through. A package of their own because `git.ts`
+ * sat against the then 300-line limit and these three are one subject: what a
+ * `subsystem move` must know before renaming (`gitDirtyPaths`), what
+ * `subsystem history` asks after (`gitRenameHops`), and the ONE write the
+ * roadmap blesses (`gitStageRenames` — "move stages renames without
+ * committing"). The doctrine is unchanged: every way git can decline reads as
+ * "git will not say", never as an error a caller must handle.
+ */
+import { gitText } from "../git.js";
+/**
+ * Which of these repo-relative paths carry UNCOMMITTED work — anything
+ * `git status --porcelain` reports beneath them, untracked files included: an
+ * untracked file is exactly a change no commit records. Null for every way
+ * git declines (not a repository, not installed, a timeout, a non-zero exit),
+ * and the one caller — `subsystem move`'s only refusal — treats null as
+ * "proceed": a refusal needs positive evidence, and a fleet that does not use
+ * git must not be refused a move over it.
+ *
+ * `-z` for the same reason `gitTrackedFiles` uses it: line output QUOTES
+ * paths with spaces or non-ASCII bytes. A rename entry (`R ` when something
+ * is already staged) carries a second NUL-separated path; both belong in the
+ * answer.
+ */
+export async function gitDirtyPaths(repoDir, rels) {
+    if (rels.length === 0)
+        return [];
+    const a = await gitText(repoDir, ["status", "--porcelain", "-z", "--", ...rels]);
+    if (a.code !== 0 || a.overflowed)
+        return null;
+    const tokens = a.out.split("\0").filter((t) => t !== "");
+    const paths = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const entry = tokens[i];
+        // "XY <path>" — two status letters and a space. A rename/copy entry's
+        // ORIGINAL path follows as its own NUL token; take it too.
+        paths.push(entry.slice(3));
+        if (entry.startsWith("R") || entry.startsWith("C")) {
+            i += 1;
+            if (tokens[i] !== undefined)
+                paths.push(tokens[i]);
+        }
+    }
+    return paths;
+}
+/**
+ * How this file moved over time, OLDEST hop first — or null when git will not
+ * say. The question follows one FILE deliberately: `git log --follow` is
+ * defined for a single file and prints NOTHING for a directory path, so
+ * `subsystem history` follows a representative file inside the directory it
+ * is asked about (a service's spec.md, a subsystem's marker) and reads each
+ * hop's directories off the file's own rename record. An empty array is git
+ * ANSWERING "never renamed"; null is git declining — the caller renders the
+ * two differently and exits 0 for both, per the doctrine above.
+ *
+ * Output shape under `-z --format=%H`: `<hash>\0\nR<score>\0<old>\0<new>\0…`,
+ * newest commit first — the token walk below is anchored on the two shapes a
+ * token can have (a 40-hex hash, an R-status) so an unexpected shape yields
+ * fewer hops, never a wrong pairing.
+ */
+export async function gitRenameHops(repoDir, rel) {
+    const a = await gitText(repoDir, ["log", "--follow", "--diff-filter=R", "--name-status", "-z", "--format=%H", "--", rel]);
+    if (a.code !== 0 || a.overflowed)
+        return null;
+    const tokens = a.out.split("\0").map((t) => (t.startsWith("\n") ? t.slice(1) : t));
+    const hops = [];
+    let commit = "";
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (/^[0-9a-f]{40}$/.test(token))
+            commit = token;
+        else if (/^R\d*$/.test(token) && tokens[i + 1] !== undefined && tokens[i + 2] !== undefined) {
+            hops.push({ commit, from: tokens[i + 1], to: tokens[i + 2] });
+            i += 2;
+        }
+    }
+    return hops.reverse();
+}
+/**
+ * Was the rename record that produced a hop into `dest` at `commit` a GUESS?
+ * `git log --follow` pairs old and new paths by CONTENT similarity, and two
+ * identical files moved (or one moved while its twin is created or deleted)
+ * in the same commit give it a coin to flip — subsystem markers are routinely
+ * byte-identical (often empty), so a multi-directory move can report a hop
+ * from a directory the followed file never occupied. The cross-check asks the
+ * commit itself: if two or more of its diff entries carry the same blob as
+ * the one `dest` received, the pairing chose between equals and the hop is
+ * not evidence. `false` = unambiguous; `true` = a guess; null = git will not
+ * say — and the caller must treat BOTH non-false answers as "will not say",
+ * because repeating a maybe-phantom hop is worse than answering nothing.
+ */
+export async function gitRenamePairingAmbiguous(repoDir, commit, dest) {
+    const a = await gitText(repoDir, ["diff-tree", "-r", "-M", "-z", commit]);
+    if (a.code !== 0 || a.overflowed)
+        return null;
+    // `-z` raw form: `:<mode> <mode> <sha> <sha> <status>` NUL, then one
+    // path token — two for a rename/copy. The leading token is the commit.
+    const tokens = a.out.split("\0").filter((t) => t !== "");
+    const entries = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (!token.startsWith(":"))
+            continue;
+        const fields = token.slice(1).split(" ");
+        const status = fields[4] ?? "";
+        const paths = status.startsWith("R") || status.startsWith("C") ? [tokens[i + 1], tokens[i + 2]] : [tokens[i + 1]];
+        entries.push({
+            srcSha: fields[2] ?? "",
+            dstSha: fields[3] ?? "",
+            status,
+            paths: paths.filter((p) => p !== undefined),
+        });
+        i += paths.length;
+    }
+    const own = entries.find((e) => e.status.startsWith("R") && e.paths[1] === dest);
+    // The hop's own rename is not in the commit's record — an answer this
+    // check cannot ground is an answer git will not give.
+    if (own === undefined)
+        return null;
+    const twins = entries.filter((e) => e.srcSha === own.dstSha || e.dstSha === own.dstSha);
+    return twins.length > 1;
+}
+/**
+ * Best-effort `git add -A` over these repo-relative paths — the ONE write
+ * (module banner): after a `subsystem move` lands its renames, staging the
+ * delete-side and add-side together is what lets git record the pair as a
+ * rename, which is what keeps `subsystem history` answerable after the user
+ * commits. Failure-silent in every direction: a fleet without git, an index
+ * lock, a timeout — the move already succeeded, and nothing here may turn it
+ * into an error.
+ */
+export async function gitStageRenames(repoDir, rels) {
+    if (rels.length === 0)
+        return;
+    await gitText(repoDir, ["add", "-A", "--", ...rels]);
+}
+//# sourceMappingURL=moves.js.map

package/dist/core/provenance/gitq/moves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moves.js","sourceRoot":"","sources":["../../../../src/core/provenance/gitq/moves.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The subsystem surface's git questions, beside the provenance ones\n * (`../git.ts`) whose `gitText` — one spawn, its timeout and its capped\n * stdout reader — they ask through. A package of their own because `git.ts`\n * sat against the then 300-line limit and these three are one subject: what a\n * `subsystem move` must know before renaming (`gitDirtyPaths`), what\n * `subsystem history` asks after (`gitRenameHops`), and the ONE write the\n * roadmap blesses (`gitStageRenames` — \"move stages renames without\n * committing\"). The doctrine is unchanged: every way git can decline reads as\n * \"git will not say\", never as an error a caller must handle.\n */\nimport { gitText } from \"../git.js\";\n\n/**\n * Which of these repo-relative paths carry UNCOMMITTED work — anything\n * `git status --porcelain` reports beneath them, untracked files included: an\n * untracked file is exactly a change no commit records. Null for every way\n * git declines (not a repository, not installed, a timeout, a non-zero exit),\n * and the one caller — `subsystem move`'s only refusal — treats null as\n * \"proceed\": a refusal needs positive evidence, and a fleet that does not use\n * git must not be refused a move over it.\n *\n * `-z` for the same reason `gitTrackedFiles` uses it: line output QUOTES\n * paths with spaces or non-ASCII bytes. A rename entry (`R ` when something\n * is already staged) carries a second NUL-separated path; both belong in the\n * answer.\n */\nexport async function gitDirtyPaths(repoDir: string, rels: string[]): Promise<string[] | null> {\n  if (rels.length === 0) return [];\n  const a = await gitText(repoDir, [\"status\", \"--porcelain\", \"-z\", \"--\", ...rels]);\n  if (a.code !== 0 || a.overflowed) return null;\n  const tokens = a.out.split(\"\\0\").filter((t) => t !== \"\");\n  const paths: string[] = [];\n  for (let i = 0; i < tokens.length; i += 1) {\n    const entry = tokens[i]!;\n    // \"XY <path>\" — two status letters and a space. A rename/copy entry's\n    // ORIGINAL path follows as its own NUL token; take it too.\n    paths.push(entry.slice(3));\n    if (entry.startsWith(\"R\") || entry.startsWith(\"C\")) {\n      i += 1;\n      if (tokens[i] !== undefined) paths.push(tokens[i]!);\n    }\n  }\n  return paths;\n}\n\n/** One hop of a path's rename history: the commit, and the path either side of it. */\nexport interface RenameHop {\n  commit: string;\n  from: string;\n  to: string;\n}\n\n/**\n * How this file moved over time, OLDEST hop first — or null when git will not\n * say. The question follows one FILE deliberately: `git log --follow` is\n * defined for a single file and prints NOTHING for a directory path, so\n * `subsystem history` follows a representative file inside the directory it\n * is asked about (a service's spec.md, a subsystem's marker) and reads each\n * hop's directories off the file's own rename record. An empty array is git\n * ANSWERING \"never renamed\"; null is git declining — the caller renders the\n * two differently and exits 0 for both, per the doctrine above.\n *\n * Output shape under `-z --format=%H`: `<hash>\\0\\nR<score>\\0<old>\\0<new>\\0…`,\n * newest commit first — the token walk below is anchored on the two shapes a\n * token can have (a 40-hex hash, an R-status) so an unexpected shape yields\n * fewer hops, never a wrong pairing.\n */\nexport async function gitRenameHops(repoDir: string, rel: string): Promise<RenameHop[] | null> {\n  const a = await gitText(repoDir, [\"log\", \"--follow\", \"--diff-filter=R\", \"--name-status\", \"-z\", \"--format=%H\", \"--\", rel]);\n  if (a.code !== 0 || a.overflowed) return null;\n  const tokens = a.out.split(\"\\0\").map((t) => (t.startsWith(\"\\n\") ? t.slice(1) : t));\n  const hops: RenameHop[] = [];\n  let commit = \"\";\n  for (let i = 0; i < tokens.length; i += 1) {\n    const token = tokens[i]!;\n    if (/^[0-9a-f]{40}$/.test(token)) commit = token;\n    else if (/^R\\d*$/.test(token) && tokens[i + 1] !== undefined && tokens[i + 2] !== undefined) {\n      hops.push({ commit, from: tokens[i + 1]!, to: tokens[i + 2]! });\n      i += 2;\n    }\n  }\n  return hops.reverse();\n}\n\n/**\n * Was the rename record that produced a hop into `dest` at `commit` a GUESS?\n * `git log --follow` pairs old and new paths by CONTENT similarity, and two\n * identical files moved (or one moved while its twin is created or deleted)\n * in the same commit give it a coin to flip — subsystem markers are routinely\n * byte-identical (often empty), so a multi-directory move can report a hop\n * from a directory the followed file never occupied. The cross-check asks the\n * commit itself: if two or more of its diff entries carry the same blob as\n * the one `dest` received, the pairing chose between equals and the hop is\n * not evidence. `false` = unambiguous; `true` = a guess; null = git will not\n * say — and the caller must treat BOTH non-false answers as \"will not say\",\n * because repeating a maybe-phantom hop is worse than answering nothing.\n */\nexport async function gitRenamePairingAmbiguous(\n  repoDir: string,\n  commit: string,\n  dest: string,\n): Promise<boolean | null> {\n  const a = await gitText(repoDir, [\"diff-tree\", \"-r\", \"-M\", \"-z\", commit]);\n  if (a.code !== 0 || a.overflowed) return null;\n  // `-z` raw form: `:<mode> <mode> <sha> <sha> <status>` NUL, then one\n  // path token — two for a rename/copy. The leading token is the commit.\n  const tokens = a.out.split(\"\\0\").filter((t) => t !== \"\");\n  const entries: { srcSha: string; dstSha: string; status: string; paths: string[] }[] = [];\n  for (let i = 0; i < tokens.length; i += 1) {\n    const token = tokens[i]!;\n    if (!token.startsWith(\":\")) continue;\n    const fields = token.slice(1).split(\" \");\n    const status = fields[4] ?? \"\";\n    const paths = status.startsWith(\"R\") || status.startsWith(\"C\") ? [tokens[i + 1], tokens[i + 2]] : [tokens[i + 1]];\n    entries.push({\n      srcSha: fields[2] ?? \"\",\n      dstSha: fields[3] ?? \"\",\n      status,\n      paths: paths.filter((p): p is string => p !== undefined),\n    });\n    i += paths.length;\n  }\n  const own = entries.find((e) => e.status.startsWith(\"R\") && e.paths[1] === dest);\n  // The hop's own rename is not in the commit's record — an answer this\n  // check cannot ground is an answer git will not give.\n  if (own === undefined) return null;\n  const twins = entries.filter((e) => e.srcSha === own.dstSha || e.dstSha === own.dstSha);\n  return twins.length > 1;\n}\n\n/**\n * Best-effort `git add -A` over these repo-relative paths — the ONE write\n * (module banner): after a `subsystem move` lands its renames, staging the\n * delete-side and add-side together is what lets git record the pair as a\n * rename, which is what keeps `subsystem history` answerable after the user\n * commits. Failure-silent in every direction: a fleet without git, an index\n * lock, a timeout — the move already succeeded, and nothing here may turn it\n * into an error.\n */\nexport async function gitStageRenames(repoDir: string, rels: string[]): Promise<void> {\n  if (rels.length === 0) return;\n  await gitText(repoDir, [\"add\", \"-A\", \"--\", ...rels]);\n}\n"]}

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

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

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

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

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

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