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

package/dist/core/provenance/findings.js

@@ -0,0 +1,244 @@
+/**
+ * Provenance checks: is this artifact anchored to anything, and has anyone
+ * vouched for it?
+ *
+ * SCHEMA.md has declared `status` / `owner` / `sources` / `last_verified` since
+ * the beginning and nothing read them. They matter more now that the prose is
+ * written by an agent: coherence proves the corpus agrees with itself, and only
+ * `sources` says it has anything to do with the code.
+ *
+ * Absence and contradiction are graded differently on purpose. A missing field
+ * is incompleteness — a warning, something to work through. A field that says
+ * the wrong thing (a spec claiming to be another service, a status nobody
+ * defined) is a bug, and gates.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { movedUnderVouch, parseFrontmatter, readFrontmatter, stringField, FEATURE_STATUSES, SERVICE_STATUSES, } from "../document/frontmatter.js";
+import { featurePaths, SPEC_AXES } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { readVouchScope } from "./sample/scope.js";
+import { sourceFindings } from "./sources.js";
+/** Fields every artifact is expected to carry, beyond its identity and status. */
+const EXPECTED = ["owner"];
+export async function serviceProvenance(docsDir, service, opts = {}) {
+    const paths = await locateServicePaths(docsDir, service, opts.fleet);
+    const repo = opts.repoDir === undefined ? undefined : { dir: opts.repoDir, loamOwned: opts.loamOwned ?? [] };
+    const findings = [];
+    const owners = [];
+    // Both requirement-carrying specs get the same pass: arch.spec.md follows
+    // spec.md's frontmatter conventions exactly, so the checks are one loop —
+    // only the label tells a reader which file moved. The pair comes from
+    // SPEC_AXES rather than being respelled, so a third axis is graded here the
+    // day it is declared instead of the day somebody notices.
+    for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {
+        if (!existsSync(path))
+            continue;
+        const raw = await readFile(path, "utf8");
+        const fm = parseFrontmatter(raw);
+        const label = `${service}: ${file}`;
+        findings.push(...identityFindings(fm, {
+            label,
+            idField: "service",
+            idValue: service,
+            statuses: [...SERVICE_STATUSES],
+        }));
+        // With no frontmatter at all, "it names no sources" says nothing the missing
+        // header did not already say — and a malformed one proves nothing either:
+        // `sources.absent` against a header nobody can read is the same false
+        // advice as the field cascade, so frontmatter.malformed stands alone.
+        if (fm.present && !fm.malformed) {
+            findings.push(...(await sourceFindings(fm, service, label, repo)));
+            findings.push(...contentFindings(fm, raw, service, label));
+            findings.push(...scopeFindings(fm, service, label));
+            // Trimmed and non-empty, so `owner: ""` stays the absence it means
+            // rather than a second owner that disagrees with the first.
+            const owner = stringField(fm, "owner")?.trim();
+            if (owner !== undefined && owner.length > 0)
+                owners.push({ file, owner });
+        }
+    }
+    findings.push(...ownerFindings(service, owners));
+    return findings;
+}
+/**
+ * The two spec files of ONE service naming two different owners.
+ *
+ * `owner` is free text and loam never decides who owns anything (SCHEMA:
+ * ownership is CODEOWNERS, and there is no permission model to grow). But
+ * `loam show` and `loam context` print spec.md's value as the service's badge,
+ * so when spec.md says `orders-team` and arch.spec.md says a team that left
+ * last quarter, an agent reading arch.spec.md routes its question to one team
+ * while every summary names the other — and nothing said so. That is a
+ * disagreement between two documents in one directory, which is loam's own job
+ * to catch whatever the forge says. Comparing against CODEOWNERS is NOT done
+ * here: that is a separate question with a separate owner decision behind it.
+ *
+ * A WARNING: neither value is wrong on its own, and only a person knows which
+ * one is current. Silent when either file names no owner — absence is
+ * `frontmatter.field-missing`'s finding, and one fact gets one code.
+ */
+function ownerFindings(service, owners) {
+    if (new Set(owners.map((o) => o.owner)).size < 2)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "frontmatter.owner-mismatch",
+            subject: service,
+            message: `${service}: ${owners.map((o) => `${o.file} names owner '${o.owner}'`).join(", ")} — ` +
+                "one service, two owners, while `loam show` and `loam context` print only spec.md's. " +
+                "Make them agree; only a person knows which one is current",
+            details: owners.map((o) => `${o.file}: ${o.owner}`),
+        },
+    ];
+}
+export async function featureProvenance(featureDir, featureId) {
+    const path = featurePaths(featureDir).intent;
+    if (!existsSync(path))
+        return [];
+    const fm = await readFrontmatter(path);
+    return identityFindings(fm, {
+        label: "intent.md",
+        idField: "feature",
+        idValue: featureId,
+        statuses: [...FEATURE_STATUSES],
+    });
+}
+function identityFindings(fm, spec) {
+    const findings = [];
+    if (!fm.present) {
+        return [
+            {
+                severity: "warn",
+                code: "frontmatter.missing",
+                subject: spec.idValue,
+                message: `${spec.label} has no frontmatter — no owner, no status, no link to the code it describes`,
+            },
+        ];
+    }
+    // One honest error instead of the cascade: with an unreadable header the
+    // field checks below would grade owner/status/service "missing" and send the
+    // author adding fields to a block YAML refuses to parse. Nothing can be
+    // concluded from a header nobody can read — including that it lacks fields.
+    if (fm.malformed) {
+        return [
+            {
+                severity: "error",
+                code: "frontmatter.malformed",
+                subject: spec.idValue,
+                message: `${spec.label} has frontmatter that does not parse as YAML — owner, status and sources are unreadable until the header is fixed`,
+            },
+        ];
+    }
+    const id = stringField(fm, spec.idField);
+    if (id !== undefined && id !== spec.idValue) {
+        findings.push({
+            severity: "error",
+            code: "frontmatter.field-mismatch",
+            subject: spec.idValue,
+            message: `${spec.label} declares ${spec.idField}: ${id}, but it lives under ${spec.idValue}`,
+        });
+    }
+    const status = stringField(fm, "status");
+    if (status !== undefined && !spec.statuses.includes(status)) {
+        findings.push({
+            severity: "error",
+            code: "frontmatter.status-unknown",
+            subject: spec.idValue,
+            message: `${spec.label} has status '${status}' — expected one of ${spec.statuses.join(", ")}`,
+        });
+    }
+    const missing = [
+        ...(id === undefined ? [spec.idField] : []),
+        ...(status === undefined ? ["status"] : []),
+        ...EXPECTED.filter((f) => stringField(fm, f) === undefined),
+    ];
+    if (missing.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "frontmatter.field-missing",
+            subject: spec.idValue,
+            message: `${spec.label} is missing ${missing.length} frontmatter field(s)`,
+            details: missing,
+            text: { detailPrefix: "- " },
+        });
+    }
+    return findings;
+}
+/**
+ * The doc-side half of the freshness check. `sources_digest` says whether the
+ * CODE moved since a person looked, and only that service's repo can recompute
+ * it; `content_digest` says whether the DOCUMENT did, and needs nothing but
+ * the document — so this runs wherever the spec is readable, `--service` and
+ * `--all` alike. Without it, editing a spec after it was vouched left
+ * `status: verified` standing over words nobody read — forged freshness, in
+ * the exact agent-written-prose threat model this layer exists for.
+ */
+function contentFindings(fm, raw, service, label) {
+    // `movedUnderVouch` is the one spelling of the condition, read by the fleet
+    // enumeration (core/repo/repo.ts) and `loam archive` too, so `loam list`
+    // cannot call a document fresh that this check calls stale. A verified doc
+    // with no stamp predates the field and is quiet on purpose; `contentStamp`'s
+    // docblock says why.
+    if (!movedUnderVouch(fm, raw))
+        return [];
+    const since = stringField(fm, "last_verified") ?? "it was vouched";
+    return [
+        {
+            // A warning, not an error — the sources.stale doctrine: the doc changed
+            // since it was vouched, and only a person can say whether verified still
+            // holds of the new words.
+            severity: "warn",
+            code: "content.stale",
+            message: `${label} changed since ${since} — the doc moved under its vouch, and only a person can say whether 'verified' still holds. Run \`loam vouch --pack --service ${service}\` for what to re-read, then \`loam vouch --service ${service}\`.`,
+        },
+    ];
+}
+/**
+ * The other half of what a stamp can hide: a `verified` document that a person
+ * read only a SAMPLE of.
+ *
+ * `loam vouch --sample <n>` deliberately trades assurance for a vouch that
+ * actually happens, and the trade is only sound while the reduction stays
+ * visible. `status: verified` cannot carry it — that string is a published
+ * contract and the maturity rung `vouched` is derived from it — so the scope
+ * rides beside it in `vouch_scope`, and this is the check that makes a fleet
+ * able to see it: one warning per sampled spec file, with the k/n, the seed
+ * to recompute the sample from, and the one action that clears it.
+ *
+ * A WARNING, following the `sources.stale` / `content.stale` doctrine: the
+ * document is not wrong, it is incompletely read, and only a person can close
+ * that. Warnings never gate, which is exactly what a fleet adopting sampling
+ * as policy needs — and a fleet that wants to gate on it branches on the code
+ * in its own CI, which is what stable codes are for.
+ *
+ * Doc-side, like `content.stale`: it needs no service repo, so it fires from
+ * the docs repo under `--service` and `--all` alike. A scope that does not
+ * decode still fires, saying so — `isSampled` asks about PRESENCE, because a
+ * mangled field must never be the way a partial read is promoted to a full
+ * one.
+ */
+function scopeFindings(fm, service, label) {
+    if (stringField(fm, "status") !== "verified")
+        return [];
+    const stamp = readVouchScope(fm);
+    if (stamp.kind === "none")
+        return [];
+    const when = stringField(fm, "last_verified");
+    const said = stamp.kind === "unreadable"
+        ? `carries a vouch_scope that does not decode (${stamp.text === null ? "its value is not text at all" : `\`${stamp.text}\``}), so it is graded as sampled — an unreadable scope must never read as a full vouch`
+        : `was vouched from a sample: ${stamp.scope.sections} of ${stamp.scope.of} section(s) were read${when === undefined ? "" : ` on ${when}`}, ` +
+            `chosen by seed ${stamp.scope.seed} — the other ${stamp.scope.of - stamp.scope.sections} were read by nobody`;
+    return [
+        {
+            severity: "warn",
+            code: "sources.sampled-vouch",
+            subject: service,
+            message: `${label} ${said}. \`status: verified\` stands over the whole document either way. Only a person can clear ` +
+                `it, by reading the rest and running a full \`loam vouch --service ${service}\` (no --sample); ` +
+                `\`loam vouch --pack --service ${service}\` lists what that sample left unread.`,
+        },
+    ];
+}
+//# sourceMappingURL=findings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/provenance/findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,kFAAkF;AAClF,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAU,CAAC;AAmBpC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAgB,EAChB,OAAwB,EACxB,IAAI,GAAsB,EAAE;IAE5B,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;IAC7G,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAsC,EAAE,CAAC;IACrD,0EAA0E;IAC1E,0EAA0E;IAC1E,sEAAsE;IACtE,4EAA4E;IAC5E,0DAA0D;IAC1D,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACnG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzC,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,GAAG,OAAO,KAAK,IAAI,EAAE,CAAC;QACpC,QAAQ,CAAC,IAAI,CACX,GAAG,gBAAgB,CAAC,EAAE,EAAE;YACtB,KAAK;YACL,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE,OAAO;YAChB,QAAQ,EAAE,CAAC,GAAG,gBAAgB,CAAC;SAChC,CAAC,CACH,CAAC;QACF,6EAA6E;QAC7E,0EAA0E;QAC1E,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,EAAE,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;YAC3D,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;YACpD,mEAAmE;YACnE,4DAA4D;YAC5D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC;YAC/C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,aAAa,CAAC,OAAe,EAAE,MAAyC;IAC/E,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5D,OAAO;QACL;YACE,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,4BAA4B;YAClC,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,OAAO,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;gBACtF,sFAAsF;gBACtF,2DAA2D;YAC7D,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;SACpD;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,UAAsB,EACtB,SAAiB;IAEjB,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,EAAE,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,gBAAgB,CAAC,EAAE,EAAE;QAC1B,KAAK,EAAE,WAAW;QAClB,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,SAAS;QAClB,QAAQ,EAAE,CAAC,GAAG,gBAAgB,CAAC;KAChC,CAAC,CAAC;AACL,CAAC;AASD,SAAS,gBAAgB,CAAC,EAAe,EAAE,IAAkB;IAC3D,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;QAChB,OAAO;YACL;gBACE,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,6EAA6E;aACpG;SACF,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,6EAA6E;IAC7E,wEAAwE;IACxE,4EAA4E;IAC5E,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO;YACL;gBACE,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,uBAAuB;gBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,mHAAmH;aAC1I;SACF,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,4BAA4B;YAClC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,aAAa,IAAI,CAAC,OAAO,KAAK,EAAE,wBAAwB,IAAI,CAAC,OAAO,EAAE;SAC7F,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5D,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,4BAA4B;YAClC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,gBAAgB,MAAM,uBAAuB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC9F,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG;QACd,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;KAC5D,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,eAAe,OAAO,CAAC,MAAM,uBAAuB;YAC1E,OAAO,EAAE,OAAO;YAChB,IAAI,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;SAC7B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,EAAe,EAAE,GAAW,EAAE,OAAe,EAAE,KAAa;IACnF,4EAA4E;IAC5E,yEAAyE;IACzE,2EAA2E;IAC3E,6EAA6E;IAC7E,qBAAqB;IACrB,IAAI,CAAC,eAAe,CAAC,EAAE,EAAE,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,EAAE,eAAe,CAAC,IAAI,gBAAgB,CAAC;IACnE,OAAO;QACL;YACE,wEAAwE;YACxE,yEAAyE;YACzE,0BAA0B;YAC1B,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,GAAG,KAAK,kBAAkB,KAAK,iIAAiI,OAAO,uDAAuD,OAAO,KAAK;SACpP;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,aAAa,CAAC,EAAe,EAAE,OAAe,EAAE,KAAa;IACpE,IAAI,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IACxD,MAAM,KAAK,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;IAC9C,MAAM,IAAI,GACR,KAAK,CAAC,IAAI,KAAK,YAAY;QACzB,CAAC,CAAC,+CAA+C,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,qFAAqF;QAChN,CAAC,CAAC,8BAA8B,KAAK,CAAC,KAAK,CAAC,QAAQ,OAAO,KAAK,CAAC,KAAK,CAAC,EAAE,wBAAwB,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,IAAI;YAC1I,kBAAkB,KAAK,CAAC,KAAK,CAAC,IAAI,gBAAgB,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,sBAAsB,CAAC;IACpH,OAAO;QACL;YACE,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,KAAK,IAAI,IAAI,4FAA4F;gBAC5G,qEAAqE,OAAO,oBAAoB;gBAChG,iCAAiC,OAAO,wCAAwC;SACnF;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Provenance checks: is this artifact anchored to anything, and has anyone\n * vouched for it?\n *\n * SCHEMA.md has declared `status` / `owner` / `sources` / `last_verified` since\n * the beginning and nothing read them. They matter more now that the prose is\n * written by an agent: coherence proves the corpus agrees with itself, and only\n * `sources` says it has anything to do with the code.\n *\n * Absence and contradiction are graded differently on purpose. A missing field\n * is incompleteness — a warning, something to work through. A field that says\n * the wrong thing (a spec claiming to be another service, a status nobody\n * defined) is a bug, and gates.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport {\n  movedUnderVouch,\n  parseFrontmatter,\n  readFrontmatter,\n  stringField,\n  FEATURE_STATUSES,\n  SERVICE_STATUSES,\n  type Frontmatter,\n} from \"../document/frontmatter.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { featurePaths, SPEC_AXES } from \"../repo/paths.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { readVouchScope } from \"./sample/scope.js\";\nimport { sourceFindings } from \"./sources.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n\n/** Fields every artifact is expected to carry, beyond its identity and status. */\nconst EXPECTED = [\"owner\"] as const;\n\nexport interface ProvenanceOptions {\n  /**\n   * The repo `sources` resolve against — the service repo loam is running in.\n   * Undefined when the docs being validated describe some other repository, in\n   * which case the paths are not ours to resolve and are left alone.\n   */\n  repoDir?: string;\n  /**\n   * Repo-relative files loam itself owns in `repoDir` — loam.json and the agent\n   * files it records (`loamOwnedFiles`). Only the walk check reads them, to\n   * leave them out of `sources.unwalked`'s denominator; absent means none.\n   */\n  loamOwned?: readonly string[];\n  /** The invocation's read index, when the caller holds one — resolves the service's directory without a second walk. */\n  fleet?: FleetContext;\n}\n\nexport async function serviceProvenance(\n  docsDir: DocsDir,\n  service: PathableService,\n  opts: ProvenanceOptions = {},\n): Promise<Finding[]> {\n  const paths = await locateServicePaths(docsDir, service, opts.fleet);\n  const repo = opts.repoDir === undefined ? undefined : { dir: opts.repoDir, loamOwned: opts.loamOwned ?? [] };\n  const findings: Finding[] = [];\n  const owners: { file: string; owner: string }[] = [];\n  // Both requirement-carrying specs get the same pass: arch.spec.md follows\n  // spec.md's frontmatter conventions exactly, so the checks are one loop —\n  // only the label tells a reader which file moved. The pair comes from\n  // SPEC_AXES rather than being respelled, so a third axis is graded here the\n  // day it is declared instead of the day somebody notices.\n  for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {\n    if (!existsSync(path)) continue;\n    const raw = await readFile(path, \"utf8\");\n    const fm = parseFrontmatter(raw);\n    const label = `${service}: ${file}`;\n    findings.push(\n      ...identityFindings(fm, {\n        label,\n        idField: \"service\",\n        idValue: service,\n        statuses: [...SERVICE_STATUSES],\n      }),\n    );\n    // With no frontmatter at all, \"it names no sources\" says nothing the missing\n    // header did not already say — and a malformed one proves nothing either:\n    // `sources.absent` against a header nobody can read is the same false\n    // advice as the field cascade, so frontmatter.malformed stands alone.\n    if (fm.present && !fm.malformed) {\n      findings.push(...(await sourceFindings(fm, service, label, repo)));\n      findings.push(...contentFindings(fm, raw, service, label));\n      findings.push(...scopeFindings(fm, service, label));\n      // Trimmed and non-empty, so `owner: \"\"` stays the absence it means\n      // rather than a second owner that disagrees with the first.\n      const owner = stringField(fm, \"owner\")?.trim();\n      if (owner !== undefined && owner.length > 0) owners.push({ file, owner });\n    }\n  }\n  findings.push(...ownerFindings(service, owners));\n  return findings;\n}\n\n/**\n * The two spec files of ONE service naming two different owners.\n *\n * `owner` is free text and loam never decides who owns anything (SCHEMA:\n * ownership is CODEOWNERS, and there is no permission model to grow). But\n * `loam show` and `loam context` print spec.md's value as the service's badge,\n * so when spec.md says `orders-team` and arch.spec.md says a team that left\n * last quarter, an agent reading arch.spec.md routes its question to one team\n * while every summary names the other — and nothing said so. That is a\n * disagreement between two documents in one directory, which is loam's own job\n * to catch whatever the forge says. Comparing against CODEOWNERS is NOT done\n * here: that is a separate question with a separate owner decision behind it.\n *\n * A WARNING: neither value is wrong on its own, and only a person knows which\n * one is current. Silent when either file names no owner — absence is\n * `frontmatter.field-missing`'s finding, and one fact gets one code.\n */\nfunction ownerFindings(service: string, owners: { file: string; owner: string }[]): Finding[] {\n  if (new Set(owners.map((o) => o.owner)).size < 2) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"frontmatter.owner-mismatch\",\n      subject: service,\n      message:\n        `${service}: ${owners.map((o) => `${o.file} names owner '${o.owner}'`).join(\", \")} — ` +\n        \"one service, two owners, while `loam show` and `loam context` print only spec.md's. \" +\n        \"Make them agree; only a person knows which one is current\",\n      details: owners.map((o) => `${o.file}: ${o.owner}`),\n    },\n  ];\n}\n\nexport async function featureProvenance(\n  featureDir: FeatureDir,\n  featureId: string,\n): Promise<Finding[]> {\n  const path = featurePaths(featureDir).intent;\n  if (!existsSync(path)) return [];\n  const fm = await readFrontmatter(path);\n  return identityFindings(fm, {\n    label: \"intent.md\",\n    idField: \"feature\",\n    idValue: featureId,\n    statuses: [...FEATURE_STATUSES],\n  });\n}\n\ninterface IdentitySpec {\n  label: string;\n  idField: \"service\" | \"feature\";\n  idValue: string;\n  statuses: string[];\n}\n\nfunction identityFindings(fm: Frontmatter, spec: IdentitySpec): Finding[] {\n  const findings: Finding[] = [];\n  if (!fm.present) {\n    return [\n      {\n        severity: \"warn\",\n        code: \"frontmatter.missing\",\n        subject: spec.idValue,\n        message: `${spec.label} has no frontmatter — no owner, no status, no link to the code it describes`,\n      },\n    ];\n  }\n\n  // One honest error instead of the cascade: with an unreadable header the\n  // field checks below would grade owner/status/service \"missing\" and send the\n  // author adding fields to a block YAML refuses to parse. Nothing can be\n  // concluded from a header nobody can read — including that it lacks fields.\n  if (fm.malformed) {\n    return [\n      {\n        severity: \"error\",\n        code: \"frontmatter.malformed\",\n        subject: spec.idValue,\n        message: `${spec.label} has frontmatter that does not parse as YAML — owner, status and sources are unreadable until the header is fixed`,\n      },\n    ];\n  }\n\n  const id = stringField(fm, spec.idField);\n  if (id !== undefined && id !== spec.idValue) {\n    findings.push({\n      severity: \"error\",\n      code: \"frontmatter.field-mismatch\",\n      subject: spec.idValue,\n      message: `${spec.label} declares ${spec.idField}: ${id}, but it lives under ${spec.idValue}`,\n    });\n  }\n\n  const status = stringField(fm, \"status\");\n  if (status !== undefined && !spec.statuses.includes(status)) {\n    findings.push({\n      severity: \"error\",\n      code: \"frontmatter.status-unknown\",\n      subject: spec.idValue,\n      message: `${spec.label} has status '${status}' — expected one of ${spec.statuses.join(\", \")}`,\n    });\n  }\n\n  const missing = [\n    ...(id === undefined ? [spec.idField] : []),\n    ...(status === undefined ? [\"status\"] : []),\n    ...EXPECTED.filter((f) => stringField(fm, f) === undefined),\n  ];\n  if (missing.length > 0) {\n    findings.push({\n      severity: \"warn\",\n      code: \"frontmatter.field-missing\",\n      subject: spec.idValue,\n      message: `${spec.label} is missing ${missing.length} frontmatter field(s)`,\n      details: missing,\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  return findings;\n}\n\n/**\n * The doc-side half of the freshness check. `sources_digest` says whether the\n * CODE moved since a person looked, and only that service's repo can recompute\n * it; `content_digest` says whether the DOCUMENT did, and needs nothing but\n * the document — so this runs wherever the spec is readable, `--service` and\n * `--all` alike. Without it, editing a spec after it was vouched left\n * `status: verified` standing over words nobody read — forged freshness, in\n * the exact agent-written-prose threat model this layer exists for.\n */\nfunction contentFindings(fm: Frontmatter, raw: string, service: string, label: string): Finding[] {\n  // `movedUnderVouch` is the one spelling of the condition, read by the fleet\n  // enumeration (core/repo/repo.ts) and `loam archive` too, so `loam list`\n  // cannot call a document fresh that this check calls stale. A verified doc\n  // with no stamp predates the field and is quiet on purpose; `contentStamp`'s\n  // docblock says why.\n  if (!movedUnderVouch(fm, raw)) return [];\n  const since = stringField(fm, \"last_verified\") ?? \"it was vouched\";\n  return [\n    {\n      // A warning, not an error — the sources.stale doctrine: the doc changed\n      // since it was vouched, and only a person can say whether verified still\n      // holds of the new words.\n      severity: \"warn\",\n      code: \"content.stale\",\n      message: `${label} changed since ${since} — the doc moved under its vouch, and only a person can say whether 'verified' still holds. Run \\`loam vouch --pack --service ${service}\\` for what to re-read, then \\`loam vouch --service ${service}\\`.`,\n    },\n  ];\n}\n\n/**\n * The other half of what a stamp can hide: a `verified` document that a person\n * read only a SAMPLE of.\n *\n * `loam vouch --sample <n>` deliberately trades assurance for a vouch that\n * actually happens, and the trade is only sound while the reduction stays\n * visible. `status: verified` cannot carry it — that string is a published\n * contract and the maturity rung `vouched` is derived from it — so the scope\n * rides beside it in `vouch_scope`, and this is the check that makes a fleet\n * able to see it: one warning per sampled spec file, with the k/n, the seed\n * to recompute the sample from, and the one action that clears it.\n *\n * A WARNING, following the `sources.stale` / `content.stale` doctrine: the\n * document is not wrong, it is incompletely read, and only a person can close\n * that. Warnings never gate, which is exactly what a fleet adopting sampling\n * as policy needs — and a fleet that wants to gate on it branches on the code\n * in its own CI, which is what stable codes are for.\n *\n * Doc-side, like `content.stale`: it needs no service repo, so it fires from\n * the docs repo under `--service` and `--all` alike. A scope that does not\n * decode still fires, saying so — `isSampled` asks about PRESENCE, because a\n * mangled field must never be the way a partial read is promoted to a full\n * one.\n */\nfunction scopeFindings(fm: Frontmatter, service: string, label: string): Finding[] {\n  if (stringField(fm, \"status\") !== \"verified\") return [];\n  const stamp = readVouchScope(fm);\n  if (stamp.kind === \"none\") return [];\n  const when = stringField(fm, \"last_verified\");\n  const said =\n    stamp.kind === \"unreadable\"\n      ? `carries a vouch_scope that does not decode (${stamp.text === null ? \"its value is not text at all\" : `\\`${stamp.text}\\``}), so it is graded as sampled — an unreadable scope must never read as a full vouch`\n      : `was vouched from a sample: ${stamp.scope.sections} of ${stamp.scope.of} section(s) were read${when === undefined ? \"\" : ` on ${when}`}, ` +\n        `chosen by seed ${stamp.scope.seed} — the other ${stamp.scope.of - stamp.scope.sections} were read by nobody`;\n  return [\n    {\n      severity: \"warn\",\n      code: \"sources.sampled-vouch\",\n      subject: service,\n      message:\n        `${label} ${said}. \\`status: verified\\` stands over the whole document either way. Only a person can clear ` +\n        `it, by reading the rest and running a full \\`loam vouch --service ${service}\\` (no --sample); ` +\n        `\\`loam vouch --pack --service ${service}\\` lists what that sample left unread.`,\n    },\n  ];\n}\n"]}

package/dist/core/provenance/git.js

@@ -0,0 +1,201 @@
+/**
+ * Subprocess questions to git: what the repository tracks, what it ignores,
+ * and who is working in it. Four questions, one spawn (`gitText`), one
+ * timeout, one doctrine — every way git can decline to answer (not a
+ * repository, not installed, a non-zero exit, a timeout) reads as "git will
+ * not say", never as an error a caller must handle. No denominator, no
+ * finding. The subsystem surface's own questions (dirty paths, rename hops,
+ * the one blessed `git add`) live in `./gitq/`, asked through the same
+ * `gitText` and so under the same timeout and output cap.
+ *
+ * Beside this module's own four questions live the neutral ANSWER-SHAPE
+ * helpers — `gitText`, `GitAnswer`, `gitSaid`, `declineDetail`,
+ * `collectStderr` — shared by the two modules that carry git's words to a
+ * user: `core/diff/base-git.ts` (which REFUSES when git declines, because a
+ * silently empty base reports the fleet as added) and `./gitq/vouched-ancestor.ts`
+ * (which DEGRADES to "full read", because a reading list may only ever grow
+ * when nobody could look). The helpers are spawn-and-capture with no verdict
+ * in them: the consequence of a decline belongs to each caller and is stated
+ * there — sharing the mechanics is what keeps a hardening (an env pin, a cap
+ * change) from landing in one of two byte-identical copies.
+ */
+import { spawn } from "node:child_process";
+/** How long the digest waits on git before deciding it learned nothing. */
+export const GIT_TIMEOUT_MS = 10_000;
+/**
+ * How much a git answer may SAY. The three streamed reads below accumulated
+ * without bound — a fleet repo's ls-files fits in single-digit MiB, so the
+ * cap is generous, and past it the child is killed and the doctrine answers
+ * exactly as for any other way git declines: null, or the empty set — "git
+ * will not say", never a truncated denominator presented as the whole one.
+ */
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+ * Accumulate a child's stdout up to the cap; past it, kill the child and
+ * remember why. One helper because the three readers below had three copies
+ * of the same `out += chunk` line, which is where an unbounded buffer hides;
+ * every text question now reaches it through `gitText`, so it is private.
+ */
+function collectStdout(child) {
+    let out = "";
+    let overflowed = false;
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+        if (overflowed)
+            return;
+        if (out.length + chunk.length > MAX_GIT_OUTPUT_BYTES) {
+            overflowed = true;
+            child.kill();
+            return;
+        }
+        out += chunk;
+    });
+    return { text: () => out, overflowed: () => overflowed };
+}
+/**
+ * How much of git's stderr an outcome may quote. The point is the first
+ * `fatal:` line, not a transcript; past the cap the words are dropped, never
+ * the outcome.
+ */
+const STDERR_CAP = 2048;
+/** Accumulate a child's stderr up to the cap; past it, keep what is held. */
+export function collectStderr(child) {
+    let err = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+        if (err.length < STDERR_CAP)
+            err = (err + chunk).slice(0, STDERR_CAP);
+    });
+    return () => err;
+}
+/**
+ * One git question, stdout as text, stderr held for quoting. No verdict here
+ * — see the banner: what a decline MEANS belongs to the caller. `input`, when
+ * given, is written to git's stdin and closed (`check-ignore --stdin`); every
+ * other question leaves stdin unopened.
+ */
+export async function gitText(cwd, args, input) {
+    return new Promise((done) => {
+        const child = spawn("git", args, {
+            cwd,
+            stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        const out = collectStdout(child);
+        const err = collectStderr(child);
+        child.on("error", (e) => done({ code: null, out: "", err: "", spawnError: e.message, overflowed: false }));
+        child.on("close", (code) => done({ code, out: out.text(), err: err(), overflowed: out.overflowed() }));
+        if (input === undefined)
+            return;
+        // A git that died before reading its input hands us EPIPE; the close
+        // handler above is what decides the outcome either way.
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(input);
+    });
+}
+/** The first line of git's stderr, trimmed — the quotable half of a decline. */
+export function gitSaid(answer) {
+    const line = answer.err.split("\n").find((l) => l.trim() !== "");
+    return line === undefined ? "" : line.trim();
+}
+/** The one sentence a decline collapses to when git left no words behind. */
+export function declineDetail(answer) {
+    if (answer.spawnError !== undefined)
+        return `git could not be started: ${answer.spawnError}.`;
+    const said = gitSaid(answer);
+    return said === "" ? "git answered nothing (killed or timed out)." : `git said: ${said}`;
+}
+/**
+ * What this repository considers its own, as repo-relative paths — or null for
+ * every way git can decline to say: not a repository, not installed, a timeout,
+ * a non-zero exit. The caller distinguishes none of them, exactly as
+ * `gitConfig` does not, because they all mean the same thing: there is no
+ * denominator here, so there is nothing to report.
+ *
+ * `-z` rather than the default line output: git QUOTES paths containing spaces
+ * or non-ASCII bytes when it is writing lines, so a service with one such file
+ * would have had a phantom top-level directory named `"src` in its untouched
+ * list.
+ */
+export async function gitTrackedFiles(repoDir) {
+    const a = await gitText(repoDir, ["ls-files", "-z", "--cached", "--exclude-standard"]);
+    return a.code === 0 && !a.overflowed ? a.out.split("\0").filter((p) => p !== "") : null;
+}
+/**
+ * Which of these repo-relative paths the repository ignores, asked once for the
+ * whole list. `git check-ignore` is the authority on purpose — it reads
+ * `.gitignore` at every level, `.git/info/exclude` and the user's global
+ * excludes, and it already knows that a TRACKED file is not ignored no matter
+ * what a pattern says, which is the distinction a re-implementation always gets
+ * wrong.
+ *
+ * Every failure answers "nothing is ignored": exit 1 is git saying so, exit 128
+ * is "not a git repository", a spawn error is git not being installed, and a
+ * timeout is a repository too strange to wait for. None of them justify
+ * dropping a file from a digest a person is going to sign.
+ */
+export async function gitIgnoredPaths(repoDir, rels) {
+    if (rels.length === 0)
+        return new Set();
+    const a = await gitText(repoDir, ["check-ignore", "--stdin", "-z"], rels.join("\0") + "\0");
+    // 0: some paths are ignored and are on stdout. 1: none are — an empty
+    // answer, not a failure. Anything else, the overflow and a spawn failure
+    // included: we learned nothing, and nothing is ignored.
+    return (a.code === 0 || a.code === 1) && !a.overflowed
+        ? new Set(a.out.split("\0").filter((s) => s.length > 0))
+        : new Set();
+}
+/**
+ * Who git says is working in this repository — `Name <email>`, or null when git
+ * cannot answer.
+ *
+ * This is the only identity loam has, and it is deliberately a weak one: git
+ * config is a text file anybody can edit, so `vouched_by` is a name, not a
+ * signature, and it proves nothing cryptographically. What it does is make the
+ * claim ATTRIBUTABLE — a `status: verified` with nobody's name against it says
+ * only that some process wrote the word, which is exactly the state that let a
+ * vouch be indistinguishable from an agent's own draft. A reviewer reading the
+ * frontmatter, or `git log` on the docs repo, can now ask a specific person what
+ * they read. Signing is the real answer and it is not this one; nothing here
+ * pretends otherwise.
+ *
+ * `user.email` is what is required — it is the field git itself refuses to
+ * commit without, so a repository where a person has ever committed has one —
+ * and `user.name` rides along when it is set.
+ */
+export async function gitIdentity(repoDir) {
+    // The environment first, because that is git's own precedence: GIT_COMMITTER_*
+    // overrides `user.*` for the identity git records, and GIT_AUTHOR_* behind it.
+    // Reading them is loam agreeing with git rather than inventing a second rule —
+    // and it is the only identity a CI job or a container has, where there is no
+    // `user.email` anywhere and running `git config --global` first would be a
+    // step nobody documents.
+    const fromEnv = identity(process.env.GIT_COMMITTER_NAME ?? process.env.GIT_AUTHOR_NAME, process.env.GIT_COMMITTER_EMAIL ?? process.env.GIT_AUTHOR_EMAIL);
+    if (fromEnv !== null)
+        return fromEnv;
+    const [name, email] = await Promise.all([
+        gitConfig(repoDir, "user.name"),
+        gitConfig(repoDir, "user.email"),
+    ]);
+    return identity(name ?? undefined, email ?? undefined);
+}
+/** `Name <email>`, or the bare email, or null — the one spelling of the stamp. */
+function identity(name, email) {
+    const e = email?.trim();
+    if (e === undefined || e === "")
+        return null;
+    const n = name?.trim();
+    return n === undefined || n === "" ? e : `${n} <${e}>`;
+}
+/**
+ * One `git config --get` value, or null for every way it can fail to be one:
+ * unset (exit 1), not a repository, git not installed, a timeout. The caller
+ * distinguishes none of them, and should not — they all mean "git will not tell
+ * us who this is", and the fix is the same sentence in each case.
+ */
+async function gitConfig(repoDir, key) {
+    const a = await gitText(repoDir, ["config", "--get", key]);
+    const value = a.out.trim();
+    return a.code === 0 && !a.overflowed && value !== "" ? value : null;
+}
+//# sourceMappingURL=git.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/core/provenance/git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subprocess questions to git: what the repository tracks, what it ignores,\n * and who is working in it. Four questions, one spawn (`gitText`), one\n * timeout, one doctrine — every way git can decline to answer (not a\n * repository, not installed, a non-zero exit, a timeout) reads as \"git will\n * not say\", never as an error a caller must handle. No denominator, no\n * finding. The subsystem surface's own questions (dirty paths, rename hops,\n * the one blessed `git add`) live in `./gitq/`, asked through the same\n * `gitText` and so under the same timeout and output cap.\n *\n * Beside this module's own four questions live the neutral ANSWER-SHAPE\n * helpers — `gitText`, `GitAnswer`, `gitSaid`, `declineDetail`,\n * `collectStderr` — shared by the two modules that carry git's words to a\n * user: `core/diff/base-git.ts` (which REFUSES when git declines, because a\n * silently empty base reports the fleet as added) and `./gitq/vouched-ancestor.ts`\n * (which DEGRADES to \"full read\", because a reading list may only ever grow\n * when nobody could look). The helpers are spawn-and-capture with no verdict\n * in them: the consequence of a decline belongs to each caller and is stated\n * there — sharing the mechanics is what keeps a hardening (an env pin, a cap\n * change) from landing in one of two byte-identical copies.\n */\nimport { spawn } from \"node:child_process\";\n\n/** How long the digest waits on git before deciding it learned nothing. */\nexport const GIT_TIMEOUT_MS = 10_000;\n\n/**\n * How much a git answer may SAY. The three streamed reads below accumulated\n * without bound — a fleet repo's ls-files fits in single-digit MiB, so the\n * cap is generous, and past it the child is killed and the doctrine answers\n * exactly as for any other way git declines: null, or the empty set — \"git\n * will not say\", never a truncated denominator presented as the whole one.\n */\nconst MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;\n\n/**\n * Accumulate a child's stdout up to the cap; past it, kill the child and\n * remember why. One helper because the three readers below had three copies\n * of the same `out += chunk` line, which is where an unbounded buffer hides;\n * every text question now reaches it through `gitText`, so it is private.\n */\nfunction collectStdout(child: import(\"node:child_process\").ChildProcess): { text: () => string; overflowed: () => boolean } {\n  let out = \"\";\n  let overflowed = false;\n  child.stdout?.setEncoding(\"utf8\");\n  child.stdout?.on(\"data\", (chunk: string) => {\n    if (overflowed) return;\n    if (out.length + chunk.length > MAX_GIT_OUTPUT_BYTES) {\n      overflowed = true;\n      child.kill();\n      return;\n    }\n    out += chunk;\n  });\n  return { text: () => out, overflowed: () => overflowed };\n}\n\n/**\n * How much of git's stderr an outcome may quote. The point is the first\n * `fatal:` line, not a transcript; past the cap the words are dropped, never\n * the outcome.\n */\nconst STDERR_CAP = 2048;\n\n/** Everything one git question can come back as. `code` is null when the child never ran or was killed. */\nexport interface GitAnswer {\n  code: number | null;\n  out: string;\n  err: string;\n  /** The spawn itself failed — git is not installed, or cannot be started. */\n  spawnError?: string;\n  overflowed: boolean;\n}\n\n/** Accumulate a child's stderr up to the cap; past it, keep what is held. */\nexport function collectStderr(child: import(\"node:child_process\").ChildProcess): () => string {\n  let err = \"\";\n  child.stderr?.setEncoding(\"utf8\");\n  child.stderr?.on(\"data\", (chunk: string) => {\n    if (err.length < STDERR_CAP) err = (err + chunk).slice(0, STDERR_CAP);\n  });\n  return () => err;\n}\n\n/**\n * One git question, stdout as text, stderr held for quoting. No verdict here\n * — see the banner: what a decline MEANS belongs to the caller. `input`, when\n * given, is written to git's stdin and closed (`check-ignore --stdin`); every\n * other question leaves stdin unopened.\n */\nexport async function gitText(cwd: string, args: string[], input?: string): Promise<GitAnswer> {\n  return new Promise<GitAnswer>((done) => {\n    const child = spawn(\"git\", args, {\n      cwd,\n      stdio: [input === undefined ? \"ignore\" : \"pipe\", \"pipe\", \"pipe\"],\n      timeout: GIT_TIMEOUT_MS,\n    });\n    const out = collectStdout(child);\n    const err = collectStderr(child);\n    child.on(\"error\", (e) =>\n      done({ code: null, out: \"\", err: \"\", spawnError: e.message, overflowed: false }),\n    );\n    child.on(\"close\", (code) =>\n      done({ code, out: out.text(), err: err(), overflowed: out.overflowed() }),\n    );\n    if (input === undefined) return;\n    // A git that died before reading its input hands us EPIPE; the close\n    // handler above is what decides the outcome either way.\n    child.stdin?.on(\"error\", () => undefined);\n    child.stdin?.end(input);\n  });\n}\n\n/** The first line of git's stderr, trimmed — the quotable half of a decline. */\nexport function gitSaid(answer: GitAnswer): string {\n  const line = answer.err.split(\"\\n\").find((l) => l.trim() !== \"\");\n  return line === undefined ? \"\" : line.trim();\n}\n\n/** The one sentence a decline collapses to when git left no words behind. */\nexport function declineDetail(answer: GitAnswer): string {\n  if (answer.spawnError !== undefined) return `git could not be started: ${answer.spawnError}.`;\n  const said = gitSaid(answer);\n  return said === \"\" ? \"git answered nothing (killed or timed out).\" : `git said: ${said}`;\n}\n\n/**\n * What this repository considers its own, as repo-relative paths — or null for\n * every way git can decline to say: not a repository, not installed, a timeout,\n * a non-zero exit. The caller distinguishes none of them, exactly as\n * `gitConfig` does not, because they all mean the same thing: there is no\n * denominator here, so there is nothing to report.\n *\n * `-z` rather than the default line output: git QUOTES paths containing spaces\n * or non-ASCII bytes when it is writing lines, so a service with one such file\n * would have had a phantom top-level directory named `\"src` in its untouched\n * list.\n */\nexport async function gitTrackedFiles(repoDir: string): Promise<string[] | null> {\n  const a = await gitText(repoDir, [\"ls-files\", \"-z\", \"--cached\", \"--exclude-standard\"]);\n  return a.code === 0 && !a.overflowed ? a.out.split(\"\\0\").filter((p) => p !== \"\") : null;\n}\n\n/**\n * Which of these repo-relative paths the repository ignores, asked once for the\n * whole list. `git check-ignore` is the authority on purpose — it reads\n * `.gitignore` at every level, `.git/info/exclude` and the user's global\n * excludes, and it already knows that a TRACKED file is not ignored no matter\n * what a pattern says, which is the distinction a re-implementation always gets\n * wrong.\n *\n * Every failure answers \"nothing is ignored\": exit 1 is git saying so, exit 128\n * is \"not a git repository\", a spawn error is git not being installed, and a\n * timeout is a repository too strange to wait for. None of them justify\n * dropping a file from a digest a person is going to sign.\n */\nexport async function gitIgnoredPaths(repoDir: string, rels: string[]): Promise<Set<string>> {\n  if (rels.length === 0) return new Set();\n  const a = await gitText(repoDir, [\"check-ignore\", \"--stdin\", \"-z\"], rels.join(\"\\0\") + \"\\0\");\n  // 0: some paths are ignored and are on stdout. 1: none are — an empty\n  // answer, not a failure. Anything else, the overflow and a spawn failure\n  // included: we learned nothing, and nothing is ignored.\n  return (a.code === 0 || a.code === 1) && !a.overflowed\n    ? new Set(a.out.split(\"\\0\").filter((s) => s.length > 0))\n    : new Set();\n}\n\n/**\n * Who git says is working in this repository — `Name <email>`, or null when git\n * cannot answer.\n *\n * This is the only identity loam has, and it is deliberately a weak one: git\n * config is a text file anybody can edit, so `vouched_by` is a name, not a\n * signature, and it proves nothing cryptographically. What it does is make the\n * claim ATTRIBUTABLE — a `status: verified` with nobody's name against it says\n * only that some process wrote the word, which is exactly the state that let a\n * vouch be indistinguishable from an agent's own draft. A reviewer reading the\n * frontmatter, or `git log` on the docs repo, can now ask a specific person what\n * they read. Signing is the real answer and it is not this one; nothing here\n * pretends otherwise.\n *\n * `user.email` is what is required — it is the field git itself refuses to\n * commit without, so a repository where a person has ever committed has one —\n * and `user.name` rides along when it is set.\n */\nexport async function gitIdentity(repoDir: string): Promise<string | null> {\n  // The environment first, because that is git's own precedence: GIT_COMMITTER_*\n  // overrides `user.*` for the identity git records, and GIT_AUTHOR_* behind it.\n  // Reading them is loam agreeing with git rather than inventing a second rule —\n  // and it is the only identity a CI job or a container has, where there is no\n  // `user.email` anywhere and running `git config --global` first would be a\n  // step nobody documents.\n  const fromEnv = identity(\n    process.env.GIT_COMMITTER_NAME ?? process.env.GIT_AUTHOR_NAME,\n    process.env.GIT_COMMITTER_EMAIL ?? process.env.GIT_AUTHOR_EMAIL,\n  );\n  if (fromEnv !== null) return fromEnv;\n  const [name, email] = await Promise.all([\n    gitConfig(repoDir, \"user.name\"),\n    gitConfig(repoDir, \"user.email\"),\n  ]);\n  return identity(name ?? undefined, email ?? undefined);\n}\n\n/** `Name <email>`, or the bare email, or null — the one spelling of the stamp. */\nfunction identity(name: string | undefined, email: string | undefined): string | null {\n  const e = email?.trim();\n  if (e === undefined || e === \"\") return null;\n  const n = name?.trim();\n  return n === undefined || n === \"\" ? e : `${n} <${e}>`;\n}\n\n/**\n * One `git config --get` value, or null for every way it can fail to be one:\n * unset (exit 1), not a repository, git not installed, a timeout. The caller\n * distinguishes none of them, and should not — they all mean \"git will not tell\n * us who this is\", and the fix is the same sentence in each case.\n */\nasync function gitConfig(repoDir: string, key: string): Promise<string | null> {\n  const a = await gitText(repoDir, [\"config\", \"--get\", key]);\n  const value = a.out.trim();\n  return a.code === 0 && !a.overflowed && value !== \"\" ? value : null;\n}\n"]}