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

package/dist/commands/verify/results.js

@@ -0,0 +1,328 @@
+/**
+ * The cucumber report, and the repository it has to be evidence FROM.
+ *
+ * A results file is only evidence if it describes the commit the attestation
+ * names, so reading it and checking the repository are one subject: the git
+ * helpers below are here because they answer the same question — is this
+ * working tree the one the report was produced from.
+ */
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { resolvePortableFileInside } from "../../core/kernel/path-safety.js";
+import { GIT_TIMEOUT_MS } from "../../core/provenance/git.js";
+import { isScenarioReport, readCucumberReport, readScenarioReport } from "../../core/results.js";
+import {} from "../../core/verify/answers.js";
+import { citedLine, pinnedDigest, sourceLines } from "../../core/verify/pins/pin.js";
+import {} from "../../core/verify/record.js";
+import {} from "./evidence/pins.js";
+import { readReportArtifact } from "./evidence/read.js";
+/**
+ * The two shapes `--results` reads, named wherever a file is refused for being
+ * neither — a fleet whose runner has no cucumber formatter learns here that
+ * the runner-neutral shape exists, rather than from a parse error.
+ */
+const RESULTS_SHAPES = "--results reads two JSON shapes: a cucumber JSON report (cucumber-js --format json, cucumber-jvm, behave, " +
+    "SpecFlow/Reqnroll, pytest-bdd --cucumberjson and godog's cucumber formatter all write one), or loam's runner-neutral " +
+    '{"loamScenarioReport": 1, "results": [{"digest": "<16 hex>", "status": "passed"}]} — the shape a JUnit, pytest, ' +
+    "Vitest or house runner's report is adapted into, keyed by each scenario's @loam-digest tag.";
+/**
+ * The report as an artifact, not merely as a parse. The resolve/read/digest
+ * plumbing lives in `./evidence/read.ts`, shared with `--contract-results`:
+ * the bytes are digested and the file's mtime read, because loam cannot prove
+ * a JSON file came from executing this commit and should stop implying
+ * otherwise. It can say precisely which file it consumed, and that goes on
+ * the record.
+ */
+export async function readResults(spelled, repoDir) {
+    const artifact = await readReportArtifact(spelled, repoDir, "test report", RESULTS_SHAPES);
+    if (!artifact.ok)
+        return artifact;
+    // The reader is chosen by MARKER, before either shape has validated
+    // anything. A file declaring `loamScenarioReport` must be graded as that
+    // shape even when it is malformed — falling through to the cucumber parser
+    // would tell an author their report is not a cucumber array, which is true,
+    // useless, and hides the actual mistake.
+    const parsed = isScenarioReport(artifact.doc)
+        ? readScenarioReport(artifact.doc, spelled)
+        : readCucumberReport(artifact.doc, spelled);
+    if (!parsed.ok)
+        return { ok: false, code: "answers-unreadable", message: parsed.message };
+    return {
+        ok: true,
+        scenarios: parsed.scenarios,
+        report: {
+            path: artifact.spelled,
+            digest: artifact.digest,
+            mtime: artifact.mtime,
+            scenarios: parsed.scenarios.length,
+        },
+    };
+}
+/**
+ * In federated mode, a confirmation is accepted only when its evidence holds up
+ * in this repository: an agent's `file:line` resolves to a real line that is
+ * unchanged at the attested commit, and each runner's evidence names the report
+ * loam just read — the cucumber report for `runner`, the contract report for
+ * `external-runner`. The legacy all-at-once form binds to no commit, so it gets
+ * only the first half of that — {@link validateLocalEvidence}.
+ *
+ * The same pass now STAMPS what it validated: one `EvidencePin` per agent
+ * citation, built where `committedFile`'s blob is already in hand (zero new
+ * git calls), and one `TokenMiss` per citation whose blob does not contain the
+ * claim's token (`tokens`, claim id → the literal the claim asserts). Runner
+ * and contract answers get no pins — their evidence names a report entry, not
+ * a file — and the legacy all-at-once form never calls this validator, so it
+ * stamps nothing.
+ */
+export async function validateServiceEvidence(answers, binding, reports, tokens) {
+    const { repoDir, commit } = binding;
+    const err = (message) => ({ ok: false, message });
+    const pins = new Map();
+    const tokenMisses = [];
+    for (const report of [reports.results, reports.contract]) {
+        if (report === undefined)
+            continue;
+        // Most reports are build output and untracked, and `git diff` is quiet on
+        // those — nothing here invents a rule for them. One the repository DOES
+        // carry has to match the commit being attested, like any other file the
+        // evidence rests on. Both reports independently: each is its own file
+        // making its own claim about this commit.
+        const clean = await git(repoDir, ["diff", "--quiet", commit, "--", report.path]);
+        if (clean.code !== 0) {
+            // Only `1` is git ANSWERING — "that file differs". Every other non-zero
+            // code is git failing to answer at all: no git on PATH, a fork that never
+            // happened, a child killed by a CI timeout or the OOM killer. Testing for
+            // `1` alone made those silently pass the check, so the one run that most
+            // needs the binding — the one where the machine is falling over — is the
+            // one that would mint an attestation whose report was never bound to the
+            // commit. An unanswered check is not a passed one, so the unknown refuses
+            // on the same terms as the known, and `clean.stderr` carries whatever
+            // account of itself the child managed to leave.
+            return err(clean.code === 1
+                ? `The test report '${report.path}' is committed to this repository and differs from ${commit.slice(0, 12)} — commit it or attest the commit it belongs to.`
+                : `Cannot tell whether the test report '${report.path}' is bound to ${commit.slice(0, 12)} — git could not be run to completion: ${clean.stderr || "git diff failed"}`);
+        }
+    }
+    for (const answer of answers) {
+        if (answer.verdict !== "confirmed")
+            continue;
+        if (answer.answered_by === "runner" || answer.answered_by === "external-runner") {
+            // A runner's evidence is an entry inside its report, not a file:line in
+            // the source — there is nothing to resolve. What must hold is that it
+            // names THAT report: an answer pointing anywhere else is not this run's.
+            const report = answer.answered_by === "runner" ? reports.results : reports.contract;
+            const stray = answer.evidence.filter((e) => report === undefined || !e.startsWith(`${report.path}: `));
+            if (stray.length > 0) {
+                return err(`Claim ${answer.id} has runner evidence ${stray.map((e) => `'${e}'`).join(", ")} that does not name the report loam read.`);
+            }
+            continue;
+        }
+        for (const evidence of answer.evidence) {
+            const cited = await resolveCitation(repoDir, answer.id, evidence);
+            if (!cited.ok)
+                return err(cited.message);
+            const { relativePath, line } = cited;
+            try {
+                const committed = await committedFile(repoDir, commit, relativePath);
+                if (!committed.ok) {
+                    return err(`Claim ${answer.id} has evidence '${evidence}' that is not bound to ${commit.slice(0, 12)}: ${committed.message}`);
+                }
+                // The pin, built from the blob just fetched. `citedLine` is undefined
+                // exactly when the line is past the committed file's end — the refusal
+                // this validator already owed — so the bounds check and the pinned
+                // text can never disagree about where lines fall.
+                const text = citedLine(committed.source, line);
+                if (text === undefined) {
+                    const committedLines = sourceLines(committed.source).length;
+                    return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' has only ${committedLines} line(s) at ${commit.slice(0, 12)}.`);
+                }
+                // The token scan happens here, per citation, because the blob is in
+                // hand and record time is when the answerer can still re-read what
+                // they cited. Substring, never a parse: the claim asserts a literal.
+                // A blob that does NOT contain the token is warned once (the notice
+                // built from `tokenMisses`) and the pin then omits the token — see
+                // EvidencePin.token for why re-litigating a never-there token at
+                // every later validate would be a false sentence with no repair.
+                const token = tokens.get(answer.id);
+                const held = token !== undefined && committed.source.includes(token);
+                if (token !== undefined && !held)
+                    tokenMisses.push({ id: answer.id, evidence, token });
+                const list = pins.get(answer.id) ?? [];
+                list.push({
+                    path: relativePath,
+                    line,
+                    file_sha256: pinnedDigest(committed.source),
+                    text,
+                    ...(held && token !== undefined ? { token } : {}),
+                });
+                pins.set(answer.id, list);
+            }
+            catch (cause) {
+                return err(`Claim ${answer.id} has unreadable evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+    }
+    return { ok: true, pins, tokenMisses };
+}
+/**
+ * One `file:line` citation, resolved in the working tree: canonical form, a
+ * path that stays inside the repository, a regular file, and a line that
+ * exists. What both recording forms owe every agent citation before anything
+ * else — the federated form then binds it to the attested commit.
+ */
+async function resolveCitation(repoDir, id, evidence) {
+    const err = (message) => ({ ok: false, message });
+    const match = /^(.+):([1-9]\d*)$/.exec(evidence);
+    if (match === null) {
+        return err(`Claim ${id} has evidence '${evidence}' — evidence must be a canonical relative file:line.`);
+    }
+    const relativePath = match[1];
+    const line = Number(match[2]);
+    let absolutePath;
+    try {
+        absolutePath = resolvePortableFileInside(repoDir, relativePath, `evidence for ${id}`);
+    }
+    catch (cause) {
+        return err(`Claim ${id} has unsafe evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    try {
+        // Absence named in the repository's own spelling: the stat's ENOENT
+        // carries the absolute path of whatever machine ran this, which tells the
+        // reader nothing the citation did not.
+        const info = await stat(absolutePath).catch((cause) => {
+            if (cause.code === "ENOENT")
+                return null;
+            throw cause;
+        });
+        if (info === null)
+            return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' does not exist in this repository.`);
+        if (!info.isFile())
+            return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' is not a regular file.`);
+        const lines = sourceLines(await readFile(absolutePath, "utf8")).length;
+        if (line > lines)
+            return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' has only ${lines} line(s).`);
+    }
+    catch (cause) {
+        return err(`Claim ${id} has unreadable evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    return { ok: true, relativePath, line };
+}
+/**
+ * The all-at-once form's evidence check: every agent citation must resolve to a
+ * real line of a real file in THIS repository. The form binds to no commit, so
+ * there is nothing to pin and no blob to compare — but it used to check
+ * nothing at all, and accepted `src/foo.py:1` for a file that did not exist
+ * while printing `verified`, in the same release whose `--service` form refused
+ * exactly that citation. The commit binding is the federated form's addition,
+ * not the difference between checked and unchecked.
+ *
+ * A CITATION is what is checked, and only a citation: an entry shaped like a
+ * `path:line` (see {@link citesALine}). The all-at-once form has always taken
+ * other evidence — "manual QA by Alice", a CI run's URL, `README.md` with no
+ * line — and still records it as it stands; holding every entry to the
+ * `file:line` grammar refused all of that with `answers-unevidenced`, which
+ * was never the defect. What a `path:line` claims is checkable, so it is
+ * checked; prose claims nothing a file can contradict. The federated form
+ * keeps its stricter contract — every agent entry a `file:line` bound to the
+ * attested commit — because its whole promise is that binding.
+ */
+export async function validateLocalEvidence(answers, repoDir) {
+    for (const answer of answers) {
+        if (answer.verdict !== "confirmed" || answer.answered_by === "runner" || answer.answered_by === "external-runner")
+            continue;
+        for (const evidence of answer.evidence.filter(citesALine)) {
+            const cited = await resolveCitation(repoDir, answer.id, evidence);
+            if (!cited.ok)
+                return cited;
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Is this evidence entry shaped like a `path:line` — something that names a
+ * line of a file and can therefore be wrong about it? One token (no
+ * whitespace: prose such as "checked at 10:30" is not a citation), not a URL
+ * (`https://ci.example:8443` ends in a number too), ending in `:<digits>`.
+ * Deliberately wider than `resolveCitation`'s canonical form: `src/x.py:0` and
+ * `../x.py:3` are citations, badly made, and must be refused rather than
+ * waved through as prose.
+ */
+function citesALine(evidence) {
+    return /^\S+:\d+$/.test(evidence) && !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(evidence);
+}
+/** Require the evidence blob to exist at HEAD and have no uncommitted edits. */
+export async function committedFile(repoDir, commit, path) {
+    const clean = await git(repoDir, ["diff", "--quiet", commit, "--", path]);
+    if (clean.code !== 0) {
+        return {
+            ok: false,
+            message: clean.code === 1 ? `'${path}' has uncommitted changes` : clean.stderr || "git diff failed",
+        };
+    }
+    const blob = await git(repoDir, ["show", `${commit}:${path}`]);
+    if (blob.code !== 0) {
+        return { ok: false, message: blob.stderr || `'${path}' is not tracked by that commit` };
+    }
+    return { ok: true, source: blob.stdout };
+}
+/**
+ * How long one git question may take, and how much it may say. Both bounds
+ * exist because every call in this module now runs while `loam verify --record`
+ * HOLDS the docs lock: a `git rev-parse` blocked on a credential-helper prompt
+ * used to hang this process forever with the lock in hand, wedging every
+ * archive, rebase and record in the fleet behind a live pid that
+ * `breakStaleLock` rightly refuses to break. The timeout IS
+ * `core/provenance/git.ts`'s (imported, so the two cannot drift); the cap is
+ * sized for `git show` of a source file an attestation cites (the default
+ * 1 MiB refused sound evidence the moment a generated client crossed it), not
+ * for arbitrary blobs.
+ *
+ * Not `gitText` itself: its answer carries no signal, so a child killed by
+ * the deadline and one killed from outside would read alike, and the
+ * deadline's own message below is the one that names the fix.
+ */
+const GIT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+function git(repoDir, args) {
+    return new Promise((done) => {
+        execFile("git", ["-C", repoDir, ...args], { encoding: "utf8", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_OUTPUT_BYTES }, (error, stdout, stderr) => {
+            done({
+                // `error.code` is an exit status only when it is a number: a spawn
+                // failure reports an errno string ("ENOENT") and a signal-killed child
+                // reports none at all. Folding those onto 1 would state that `git diff`
+                // found a difference — a Ctrl-C or an OOM kill during
+                // `loam verify --record` would read as an uncommitted edit and refuse
+                // a sound attestation. -1 is not a status git assigns, so both diff
+                // sites fall to their stderr-carrying arm and say what happened.
+                code: error === null ? 0 : typeof error.code === "number" ? error.code : -1,
+                stdout,
+                // A child that never ran writes nothing to stderr, so its only account
+                // of itself is on the error; without this the refusal would name no
+                // cause at all. A child WE killed gets its account written for it: the
+                // deadline exists for a git blocked on a credential-helper prompt, and
+                // the raw "Command failed: git …" says nothing about a deadline — the
+                // operator re-runs, waits the same 10 s, and reads the same message,
+                // with the actual fix (GIT_TERMINAL_PROMPT=0, or the helper) never
+                // reachable from it.
+                stderr: error !== null && error.killed && error.signal !== null
+                    ? `git did not answer within ${GIT_TIMEOUT_MS / 1000}s and was stopped — a prompt or a hung remote; GIT_TERMINAL_PROMPT=0 disables credential prompts`
+                    : stderr.trim() || (error === null ? "" : error.message),
+            });
+        });
+    });
+}
+/** Resolve HEAD without a shell, so repository paths remain data, never code. */
+export async function repositoryCommit(repoDir) {
+    const result = await git(repoDir, ["rev-parse", "--verify", "HEAD^{commit}"]);
+    if (result.code !== 0) {
+        return {
+            ok: false,
+            message: `Federated verification requires a git repository with a committed HEAD: ${result.stderr || "git rev-parse failed"}`,
+        };
+    }
+    const commit = result.stdout.trim();
+    if (!/^[0-9a-f]{40,64}$/i.test(commit)) {
+        return { ok: false, message: `Git returned an invalid HEAD commit '${commit}'.` };
+    }
+    return { ok: true, commit };
+}
+//# sourceMappingURL=results.js.map

package/dist/commands/verify/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../../src/commands/verify/results.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The cucumber report, and the repository it has to be evidence FROM.\n *\n * A results file is only evidence if it describes the commit the attestation\n * names, so reading it and checking the repository are one subject: the git\n * helpers below are here because they answer the same question — is this\n * working tree the one the report was produced from.\n */\nimport { execFile } from \"node:child_process\";\nimport { readFile, stat } from \"node:fs/promises\";\nimport { resolvePortableFileInside } from \"../../core/kernel/path-safety.js\";\nimport { GIT_TIMEOUT_MS } from \"../../core/provenance/git.js\";\nimport { isScenarioReport, readCucumberReport, readScenarioReport, type ReportScenario } from \"../../core/results.js\";\nimport { type Answer } from \"../../core/verify/answers.js\";\nimport { citedLine, pinnedDigest, sourceLines, type EvidencePin } from \"../../core/verify/pins/pin.js\";\nimport { type ConsumedReport, type ConsumedReports } from \"../../core/verify/record.js\";\nimport { type EvidencePins, type TokenMiss } from \"./evidence/pins.js\";\nimport { readReportArtifact } from \"./evidence/read.js\";\n\nexport type ResultsRead =\n  | { ok: true; report: ConsumedReport; scenarios: ReportScenario[] }\n  | { ok: false; code: \"answers-unreadable\"; message: string };\n\n/**\n * The two shapes `--results` reads, named wherever a file is refused for being\n * neither — a fleet whose runner has no cucumber formatter learns here that\n * the runner-neutral shape exists, rather than from a parse error.\n */\nconst RESULTS_SHAPES =\n  \"--results reads two JSON shapes: a cucumber JSON report (cucumber-js --format json, cucumber-jvm, behave, \" +\n  \"SpecFlow/Reqnroll, pytest-bdd --cucumberjson and godog's cucumber formatter all write one), or loam's runner-neutral \" +\n  '{\"loamScenarioReport\": 1, \"results\": [{\"digest\": \"<16 hex>\", \"status\": \"passed\"}]} — the shape a JUnit, pytest, ' +\n  \"Vitest or house runner's report is adapted into, keyed by each scenario's @loam-digest tag.\";\n\n/**\n * The report as an artifact, not merely as a parse. The resolve/read/digest\n * plumbing lives in `./evidence/read.ts`, shared with `--contract-results`:\n * the bytes are digested and the file's mtime read, because loam cannot prove\n * a JSON file came from executing this commit and should stop implying\n * otherwise. It can say precisely which file it consumed, and that goes on\n * the record.\n */\nexport async function readResults(spelled: string, repoDir: string | undefined): Promise<ResultsRead> {\n  const artifact = await readReportArtifact(spelled, repoDir, \"test report\", RESULTS_SHAPES);\n  if (!artifact.ok) return artifact;\n  // The reader is chosen by MARKER, before either shape has validated\n  // anything. A file declaring `loamScenarioReport` must be graded as that\n  // shape even when it is malformed — falling through to the cucumber parser\n  // would tell an author their report is not a cucumber array, which is true,\n  // useless, and hides the actual mistake.\n  const parsed = isScenarioReport(artifact.doc)\n    ? readScenarioReport(artifact.doc, spelled)\n    : readCucumberReport(artifact.doc, spelled);\n  if (!parsed.ok) return { ok: false, code: \"answers-unreadable\", message: parsed.message };\n  return {\n    ok: true,\n    scenarios: parsed.scenarios,\n    report: {\n      path: artifact.spelled,\n      digest: artifact.digest,\n      mtime: artifact.mtime,\n      scenarios: parsed.scenarios.length,\n    },\n  };\n}\n\n/**\n * The repository an attestation binds to and the commit it binds at — two\n * values only ever asked about together, so they travel as one and the\n * inconsistent pair (this repo, that commit) stops being representable.\n */\nexport interface AttestationBinding {\n  repoDir: string;\n  commit: string;\n}\n\nexport type ServiceEvidenceCheck =\n  /** Every citation held up; `pins`/`tokenMisses` are the stamp and the honesty it computed en route. */\n  | ({ ok: true } & EvidencePins)\n  | { ok: false; message: string };\n\n/**\n * In federated mode, a confirmation is accepted only when its evidence holds up\n * in this repository: an agent's `file:line` resolves to a real line that is\n * unchanged at the attested commit, and each runner's evidence names the report\n * loam just read — the cucumber report for `runner`, the contract report for\n * `external-runner`. The legacy all-at-once form binds to no commit, so it gets\n * only the first half of that — {@link validateLocalEvidence}.\n *\n * The same pass now STAMPS what it validated: one `EvidencePin` per agent\n * citation, built where `committedFile`'s blob is already in hand (zero new\n * git calls), and one `TokenMiss` per citation whose blob does not contain the\n * claim's token (`tokens`, claim id → the literal the claim asserts). Runner\n * and contract answers get no pins — their evidence names a report entry, not\n * a file — and the legacy all-at-once form never calls this validator, so it\n * stamps nothing.\n */\nexport async function validateServiceEvidence(\n  answers: Answer[],\n  binding: AttestationBinding,\n  reports: ConsumedReports,\n  tokens: ReadonlyMap<string, string>,\n): Promise<ServiceEvidenceCheck> {\n  const { repoDir, commit } = binding;\n  const err = (message: string): ServiceEvidenceCheck => ({ ok: false, message });\n  const pins = new Map<string, EvidencePin[]>();\n  const tokenMisses: TokenMiss[] = [];\n  for (const report of [reports.results, reports.contract]) {\n    if (report === undefined) continue;\n    // Most reports are build output and untracked, and `git diff` is quiet on\n    // those — nothing here invents a rule for them. One the repository DOES\n    // carry has to match the commit being attested, like any other file the\n    // evidence rests on. Both reports independently: each is its own file\n    // making its own claim about this commit.\n    const clean = await git(repoDir, [\"diff\", \"--quiet\", commit, \"--\", report.path]);\n    if (clean.code !== 0) {\n      // Only `1` is git ANSWERING — \"that file differs\". Every other non-zero\n      // code is git failing to answer at all: no git on PATH, a fork that never\n      // happened, a child killed by a CI timeout or the OOM killer. Testing for\n      // `1` alone made those silently pass the check, so the one run that most\n      // needs the binding — the one where the machine is falling over — is the\n      // one that would mint an attestation whose report was never bound to the\n      // commit. An unanswered check is not a passed one, so the unknown refuses\n      // on the same terms as the known, and `clean.stderr` carries whatever\n      // account of itself the child managed to leave.\n      return err(\n        clean.code === 1\n          ? `The test report '${report.path}' is committed to this repository and differs from ${commit.slice(0, 12)} — commit it or attest the commit it belongs to.`\n          : `Cannot tell whether the test report '${report.path}' is bound to ${commit.slice(0, 12)} — git could not be run to completion: ${clean.stderr || \"git diff failed\"}`,\n      );\n    }\n  }\n  for (const answer of answers) {\n    if (answer.verdict !== \"confirmed\") continue;\n    if (answer.answered_by === \"runner\" || answer.answered_by === \"external-runner\") {\n      // A runner's evidence is an entry inside its report, not a file:line in\n      // the source — there is nothing to resolve. What must hold is that it\n      // names THAT report: an answer pointing anywhere else is not this run's.\n      const report = answer.answered_by === \"runner\" ? reports.results : reports.contract;\n      const stray = answer.evidence.filter((e) => report === undefined || !e.startsWith(`${report.path}: `));\n      if (stray.length > 0) {\n        return err(`Claim ${answer.id} has runner evidence ${stray.map((e) => `'${e}'`).join(\", \")} that does not name the report loam read.`);\n      }\n      continue;\n    }\n    for (const evidence of answer.evidence) {\n      const cited = await resolveCitation(repoDir, answer.id, evidence);\n      if (!cited.ok) return err(cited.message);\n      const { relativePath, line } = cited;\n      try {\n        const committed = await committedFile(repoDir, commit, relativePath);\n        if (!committed.ok) {\n          return err(`Claim ${answer.id} has evidence '${evidence}' that is not bound to ${commit.slice(0, 12)}: ${committed.message}`);\n        }\n        // The pin, built from the blob just fetched. `citedLine` is undefined\n        // exactly when the line is past the committed file's end — the refusal\n        // this validator already owed — so the bounds check and the pinned\n        // text can never disagree about where lines fall.\n        const text = citedLine(committed.source, line);\n        if (text === undefined) {\n          const committedLines = sourceLines(committed.source).length;\n          return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' has only ${committedLines} line(s) at ${commit.slice(0, 12)}.`);\n        }\n        // The token scan happens here, per citation, because the blob is in\n        // hand and record time is when the answerer can still re-read what\n        // they cited. Substring, never a parse: the claim asserts a literal.\n        // A blob that does NOT contain the token is warned once (the notice\n        // built from `tokenMisses`) and the pin then omits the token — see\n        // EvidencePin.token for why re-litigating a never-there token at\n        // every later validate would be a false sentence with no repair.\n        const token = tokens.get(answer.id);\n        const held = token !== undefined && committed.source.includes(token);\n        if (token !== undefined && !held) tokenMisses.push({ id: answer.id, evidence, token });\n        const list = pins.get(answer.id) ?? [];\n        list.push({\n          path: relativePath,\n          line,\n          file_sha256: pinnedDigest(committed.source),\n          text,\n          ...(held && token !== undefined ? { token } : {}),\n        });\n        pins.set(answer.id, list);\n      } catch (cause) {\n        return err(`Claim ${answer.id} has unreadable evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);\n      }\n    }\n  }\n  return { ok: true, pins, tokenMisses };\n}\n\ntype Citation = { ok: true; relativePath: string; line: number } | { ok: false; message: string };\n\n/**\n * One `file:line` citation, resolved in the working tree: canonical form, a\n * path that stays inside the repository, a regular file, and a line that\n * exists. What both recording forms owe every agent citation before anything\n * else — the federated form then binds it to the attested commit.\n */\nasync function resolveCitation(repoDir: string, id: string, evidence: string): Promise<Citation> {\n  const err = (message: string): Citation => ({ ok: false, message });\n  const match = /^(.+):([1-9]\\d*)$/.exec(evidence);\n  if (match === null) {\n    return err(`Claim ${id} has evidence '${evidence}' — evidence must be a canonical relative file:line.`);\n  }\n  const relativePath = match[1]!;\n  const line = Number(match[2]);\n  let absolutePath: string;\n  try {\n    absolutePath = resolvePortableFileInside(repoDir, relativePath, `evidence for ${id}`);\n  } catch (cause) {\n    return err(`Claim ${id} has unsafe evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);\n  }\n  try {\n    // Absence named in the repository's own spelling: the stat's ENOENT\n    // carries the absolute path of whatever machine ran this, which tells the\n    // reader nothing the citation did not.\n    const info = await stat(absolutePath).catch((cause: NodeJS.ErrnoException) => {\n      if (cause.code === \"ENOENT\") return null;\n      throw cause;\n    });\n    if (info === null) return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' does not exist in this repository.`);\n    if (!info.isFile()) return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' is not a regular file.`);\n    const lines = sourceLines(await readFile(absolutePath, \"utf8\")).length;\n    if (line > lines) return err(`Claim ${id} has evidence '${evidence}', but '${relativePath}' has only ${lines} line(s).`);\n  } catch (cause) {\n    return err(`Claim ${id} has unreadable evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);\n  }\n  return { ok: true, relativePath, line };\n}\n\n/**\n * The all-at-once form's evidence check: every agent citation must resolve to a\n * real line of a real file in THIS repository. The form binds to no commit, so\n * there is nothing to pin and no blob to compare — but it used to check\n * nothing at all, and accepted `src/foo.py:1` for a file that did not exist\n * while printing `verified`, in the same release whose `--service` form refused\n * exactly that citation. The commit binding is the federated form's addition,\n * not the difference between checked and unchecked.\n *\n * A CITATION is what is checked, and only a citation: an entry shaped like a\n * `path:line` (see {@link citesALine}). The all-at-once form has always taken\n * other evidence — \"manual QA by Alice\", a CI run's URL, `README.md` with no\n * line — and still records it as it stands; holding every entry to the\n * `file:line` grammar refused all of that with `answers-unevidenced`, which\n * was never the defect. What a `path:line` claims is checkable, so it is\n * checked; prose claims nothing a file can contradict. The federated form\n * keeps its stricter contract — every agent entry a `file:line` bound to the\n * attested commit — because its whole promise is that binding.\n */\nexport async function validateLocalEvidence(answers: Answer[], repoDir: string): Promise<{ ok: true } | { ok: false; message: string }> {\n  for (const answer of answers) {\n    if (answer.verdict !== \"confirmed\" || answer.answered_by === \"runner\" || answer.answered_by === \"external-runner\") continue;\n    for (const evidence of answer.evidence.filter(citesALine)) {\n      const cited = await resolveCitation(repoDir, answer.id, evidence);\n      if (!cited.ok) return cited;\n    }\n  }\n  return { ok: true };\n}\n\n/**\n * Is this evidence entry shaped like a `path:line` — something that names a\n * line of a file and can therefore be wrong about it? One token (no\n * whitespace: prose such as \"checked at 10:30\" is not a citation), not a URL\n * (`https://ci.example:8443` ends in a number too), ending in `:<digits>`.\n * Deliberately wider than `resolveCitation`'s canonical form: `src/x.py:0` and\n * `../x.py:3` are citations, badly made, and must be refused rather than\n * waved through as prose.\n */\nfunction citesALine(evidence: string): boolean {\n  return /^\\S+:\\d+$/.test(evidence) && !/^[A-Za-z][A-Za-z0-9+.-]*:\\/\\//.test(evidence);\n}\n\ntype CommitResult = { ok: true; commit: string } | { ok: false; message: string };\ntype CommittedFileResult = { ok: true; source: string } | { ok: false; message: string };\n\n/** Require the evidence blob to exist at HEAD and have no uncommitted edits. */\nexport async function committedFile(repoDir: string, commit: string, path: string): Promise<CommittedFileResult> {\n  const clean = await git(repoDir, [\"diff\", \"--quiet\", commit, \"--\", path]);\n  if (clean.code !== 0) {\n    return {\n      ok: false,\n      message: clean.code === 1 ? `'${path}' has uncommitted changes` : clean.stderr || \"git diff failed\",\n    };\n  }\n  const blob = await git(repoDir, [\"show\", `${commit}:${path}`]);\n  if (blob.code !== 0) {\n    return { ok: false, message: blob.stderr || `'${path}' is not tracked by that commit` };\n  }\n  return { ok: true, source: blob.stdout };\n}\n\ninterface GitResult {\n  /**\n   * Git's own exit status, or `-1` for \"git could not be run to completion\" —\n   * no git on PATH, a spawn failure, a child killed by a signal (the deadline\n   * below included), or output past the declared cap. Callers read specific\n   * meaning into small numbers (`1` from `git diff --quiet` is \"that file\n   * differs\"), so a run that never reached an exit status must not borrow one\n   * of them.\n   */\n  code: number;\n  stdout: string;\n  stderr: string;\n}\n\n/**\n * How long one git question may take, and how much it may say. Both bounds\n * exist because every call in this module now runs while `loam verify --record`\n * HOLDS the docs lock: a `git rev-parse` blocked on a credential-helper prompt\n * used to hang this process forever with the lock in hand, wedging every\n * archive, rebase and record in the fleet behind a live pid that\n * `breakStaleLock` rightly refuses to break. The timeout IS\n * `core/provenance/git.ts`'s (imported, so the two cannot drift); the cap is\n * sized for `git show` of a source file an attestation cites (the default\n * 1 MiB refused sound evidence the moment a generated client crossed it), not\n * for arbitrary blobs.\n *\n * Not `gitText` itself: its answer carries no signal, so a child killed by\n * the deadline and one killed from outside would read alike, and the\n * deadline's own message below is the one that names the fix.\n */\nconst GIT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;\n\nfunction git(repoDir: string, args: string[]): Promise<GitResult> {\n  return new Promise((done) => {\n    execFile(\n      \"git\",\n      [\"-C\", repoDir, ...args],\n      { encoding: \"utf8\", timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_OUTPUT_BYTES },\n      (error, stdout, stderr) => {\n      done({\n        // `error.code` is an exit status only when it is a number: a spawn\n        // failure reports an errno string (\"ENOENT\") and a signal-killed child\n        // reports none at all. Folding those onto 1 would state that `git diff`\n        // found a difference — a Ctrl-C or an OOM kill during\n        // `loam verify --record` would read as an uncommitted edit and refuse\n        // a sound attestation. -1 is not a status git assigns, so both diff\n        // sites fall to their stderr-carrying arm and say what happened.\n        code: error === null ? 0 : typeof error.code === \"number\" ? error.code : -1,\n        stdout,\n        // A child that never ran writes nothing to stderr, so its only account\n        // of itself is on the error; without this the refusal would name no\n        // cause at all. A child WE killed gets its account written for it: the\n        // deadline exists for a git blocked on a credential-helper prompt, and\n        // the raw \"Command failed: git …\" says nothing about a deadline — the\n        // operator re-runs, waits the same 10 s, and reads the same message,\n        // with the actual fix (GIT_TERMINAL_PROMPT=0, or the helper) never\n        // reachable from it.\n        stderr:\n          error !== null && error.killed && error.signal !== null\n            ? `git did not answer within ${GIT_TIMEOUT_MS / 1000}s and was stopped — a prompt or a hung remote; GIT_TERMINAL_PROMPT=0 disables credential prompts`\n            : stderr.trim() || (error === null ? \"\" : error.message),\n      });\n    });\n  });\n}\n\n/** Resolve HEAD without a shell, so repository paths remain data, never code. */\nexport async function repositoryCommit(repoDir: string): Promise<CommitResult> {\n  const result = await git(repoDir, [\"rev-parse\", \"--verify\", \"HEAD^{commit}\"]);\n  if (result.code !== 0) {\n    return {\n      ok: false,\n      message: `Federated verification requires a git repository with a committed HEAD: ${result.stderr || \"git rev-parse failed\"}`,\n    };\n  }\n  const commit = result.stdout.trim();\n  if (!/^[0-9a-f]{40,64}$/i.test(commit)) {\n    return { ok: false, message: `Git returned an invalid HEAD commit '${commit}'.` };\n  }\n  return { ok: true, commit };\n}\n"]}

package/dist/commands/verify/verify.js

@@ -0,0 +1,220 @@
+import { configOrRefuse, fail, repoPath } from "../../core/envelope/json.js";
+import { missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import {} from "../../core/staging/interrupted.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
+import { docsRepoReady } from "../policy/gate.js";
+import { featureChecklist } from "../../core/verify/checklist.js";
+import { readVerificationState } from "../../core/verify/read/file.js";
+import { report } from "./report.js";
+import { reportFrozen } from "./frozen.js";
+import { record } from "./record.js";
+import {} from "./record.js";
+import { diffAnswers } from "./cross/diff.js";
+export function registerVerify(program) {
+    program
+        .command("verify")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("Check a feature against its own promises: derive the claims, record the answers with evidence")
+        .option("--record <file>", "record a JSON answer set against the current checklist")
+        .option("--results <file>", "answer the scenario.tested claims mechanically from a test report: cucumber JSON, or loam's runner-neutral loamScenarioReport JSON for any other runner")
+        .option("--contract-results <file>", "answer the api.exposes claims mechanically from an API contract-test report (loam's generic contract-results JSON)")
+        .option("--diff-answers <files...>", "cross-examine two independent answer sets against the current checklist (reads only, writes nothing)")
+        .option("--service <id>", "record only this service's claims, bound to the current repository commit")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        const { docsDir } = config;
+        const recording = opts.record !== undefined || opts.results !== undefined || opts.contractResults !== undefined;
+        // --diff-answers is a third READ form (see the WRITING/READING split
+        // below): it validates two answer sets against the same checklist and
+        // writes nothing, so combining it with any recording flag is a
+        // contradiction refused up front — before the binding, before the lock —
+        // rather than a mode silently picked between the two.
+        let diffFiles = null;
+        if (opts.diffAnswers !== undefined) {
+            if (recording) {
+                return fail(json, "invalid-option", "--diff-answers is a read-only cross-examination: it validates both files and writes nothing, " +
+                    "so it cannot be combined with --record, --results or --contract-results. " +
+                    "Diff first, then record the answer set you stand behind.");
+            }
+            // Commander's variadic form consumes arguments until the next --flag,
+            // so a featureId placed AFTER the flag arrives here as a third file —
+            // this refusal is what turns that mistake into a sentence instead of a
+            // diff of the wrong files.
+            const [a, b] = opts.diffAnswers;
+            if (opts.diffAnswers.length !== 2 || a === undefined || b === undefined) {
+                return fail(json, "invalid-option", "--diff-answers takes exactly two answer files: --diff-answers a.json b.json");
+            }
+            diffFiles = { a, b };
+        }
+        // WRITING is bound to the repository; READING is not. An attestation
+        // pins claims to this repo's git HEAD and to file:line evidence inside
+        // it, so writing (--record, --results or --contract-results) with
+        // `--service X` may only run where loam.json says this repo IS X —
+        // vouch's and gherkin's refusal, for vouch's reason: from anywhere
+        // else, that repository is somebody else's. Reading takes
+        // `--service` as a pure lens (which claims are checkout-web's, and what
+        // has it said?) and needs no binding at all, because it writes nothing.
+        if (recording && opts.service !== undefined) {
+            if (config.service === undefined) {
+                return fail(json, "repository-unavailable", `Cannot attest for '${opts.service}' from here: this is not a service repo — loam.json declares no \`service\`. ` +
+                    `A federated attestation binds the answers to this repository's git HEAD and to evidence inside it, so the repository has to say which service it is. ` +
+                    `Add "service": "${opts.service}" to loam.json, or record it from that service's own repo.`);
+            }
+            if (config.service !== opts.service) {
+                return fail(json, "service-mismatch", `This repository is configured as service '${config.service}', so it cannot attest claims for '${opts.service}'.`);
+            }
+        }
+        // Before the lock, because the lock is a file INSIDE the docs repo: a
+        // `docsDir` pointing at nothing used to surface as the lock file's own
+        // ENOENT — an `internal` where the read side of this same command names
+        // the misconfiguration. "docs", not "services", in BOTH modes — and that
+        // is a pinned contract, not looseness: the legacy all-at-once form
+        // records against a features-only docs repo with no `services/` at all,
+        // and it has always exited 0 there. The cost is real and accepted: a
+        // typo'd `docsDir` pointing at some existing non-docs directory gets a
+        // `.loam-lock` created and removed inside it. The gate above only
+        // guarantees the directory exists.
+        if (!docsRepoReady(json, docsDir, "docs"))
+            return;
+        // A record is a merge over the docs repo, so recording takes the docs
+        // lock — the same one archive, unarchive and rebase hold — and takes it
+        // HERE, before the feature is even resolved. Behind the lock, an archive
+        // can rename this feature's directory into features/archive/ at any
+        // moment; a feature resolved before the lock could have its record
+        // written into the pre-move path, a file nothing will ever read again.
+        // The waiting form rather than archive's refuse-fast one, because two
+        // recorders for different services of one feature are both supposed to
+        // land: the second waits out the first's sub-second window and merges
+        // over what it left. Reading stays lock-free — it writes nothing.
+        //
+        // A journal under the lock means the last writer never finished. The
+        // record's own authoritative read is about to happen; reading it over
+        // a half-commit would merge against bytes no run ever produced — the
+        // last docs-repo writer that could still silently treat a half-commit
+        // as healthy. That refusal must release the lock like every other path
+        // out, and once did not; `openCommitWindow` releases it before it answers.
+        let releaseLock = null;
+        let recovered = null;
+        if (recording) {
+            const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);
+            if (!opened.ok)
+                return fail(json, opened.code, opened.message);
+            releaseLock = opened.release;
+            recovered = opened.recovered;
+        }
+        try {
+            // Archived features resolve too: a shipped feature's verification is worth
+            // reading back, and it travelled into the archive with everything else.
+            const feature = await resolveFeature(docsDir, featureId, "include");
+            if (!feature) {
+                // repo.ts's sentence, not a second copy of it. Resolving with "include"
+                // means the archived branch inside it cannot fire here — an archived
+                // feature resolves — so the text is exactly what it was; what changes is
+                // that a reworded miss message can no longer leave this one behind.
+                return fail(json, "unknown-target", await missingFeatureMessage(docsDir, featureId));
+            }
+            // The cross-examination lens leaves BEFORE the record is read below:
+            // it never consumes verification.yaml, and the moment a
+            // cross-examination is most needed is exactly when the record on disk
+            // is too damaged to read and somebody is about to re-record over it —
+            // the record-unreadable refusal must not bar the one command that
+            // would inform that re-recording. The archived refusal still applies,
+            // with the recording branch's code and reason: there is no current
+            // checklist to answer, so the wrong thing is the option, not the
+            // answer sets.
+            if (diffFiles !== null) {
+                if (feature.archived) {
+                    return fail(json, "invalid-option", `${feature.id} is archived — there is no current checklist to answer, so there is nothing to cross-examine; its record is frozen history. \`loam unarchive ${feature.id}\` first if the claims really need re-answering.`);
+                }
+                await diffAnswers({ docsDir, featureDir: feature.dir, json }, await featureChecklist(docsDir, feature.dir, feature.id), diffFiles, { lens: opts.service });
+                return;
+            }
+            // Before anything else: a record file that exists but will not read
+            // is a refusal, not an absence. It holds somebody's answers and — in a
+            // fleet — other repositories' attestations; treating it as "not verified"
+            // let the next --record silently overwrite all of it, and made the read
+            // view say "no record" about a file sitting right there.
+            //
+            // The path is the one FILE that failed, and the advice is that file's:
+            // the record is several files now, and the recipe that is safe for a
+            // service's own attestation file (delete it, record that service again)
+            // is the one that erases a fleet's evidence when the file is the shared
+            // one-file record — which is what this refusal used to tell everyone,
+            // and what a miscounted record's "record again" looped back into.
+            //
+            // An in-flight feature's checklist is derived FIRST, because which of
+            // those files count depends on it: a record kept as per-service files
+            // answers the question being asked now, and only the caller knows what
+            // that is (`core/verify/read/union.ts`). Read without it, a service
+            // that recorded the current checklist could lose a same-day tie to one
+            // that recorded an older one, and this view called the whole record
+            // stale. An archived feature derives nothing — see below.
+            const checklist = feature.archived ? null : await featureChecklist(docsDir, feature.dir, feature.id);
+            const existing = await readVerificationState(feature.dir, checklist?.digest);
+            if (existing.state === "unreadable") {
+                return fail(json, "record-unreadable", `${repoPath(docsDir, existing.path)} exists but cannot be read as a verification record: ${existing.reason}. ` +
+                    `${existing.advice} loam will not overwrite a record it could not read.`);
+            }
+            const recorded = existing.state === "ok" ? existing.verification : null;
+            // But an archived feature never gets a re-derived checklist — see the
+            // header. Its record is frozen history, and --record / --results refuse
+            // alike: the code is `invalid-option` rather than `answers-mismatch`
+            // because the answers were never compared to anything — there is no
+            // current checklist to answer, so the wrong thing here is the option,
+            // not the answer set. (`checklist` is null exactly when the feature is
+            // archived — the test is spelled on it so the compiler knows the
+            // in-flight path below has one.)
+            if (checklist === null) {
+                if (recording) {
+                    return fail(json, "invalid-option", `${feature.id} is archived — its verification is history now. \`loam unarchive ${feature.id}\` first if the answers really need to change.`);
+                }
+                reportFrozen({ docsDir, featureDir: feature.dir, json }, feature.id, recorded);
+                return;
+            }
+            if (recording) {
+                // Standing in a service repo, `--service` is what the repo already
+                // says: omitting it must not fall back to the legacy all-at-once form,
+                // which claims the whole fleet's checklist on this one repo's word.
+                //
+                // The repo root, not the cwd — `vouch`'s and `gherkin`'s reason. An
+                // attestation names a commit and rests on evidence resolved inside
+                // "this repository", and `config.root` is the directory loam.json was
+                // actually found in. Off `process.cwd()`, running from a subdirectory
+                // silently changed all three: evidence resolved against the
+                // subdirectory, `--results` had to live in it, and `git rev-parse` ran
+                // there — a submodule or nested checkout under it would have named
+                // somebody else's commit on this repository's attestation.
+                //
+                // `config.service` and not `opts.service ?? config.service`, though
+                // the two are the same value: the binding refusal above lets a
+                // recording `--service` through only when it EQUALS the configured
+                // service. Taking the configured one keeps its brand — loam.json's
+                // reader validated it against the id grammar — and that brand is
+                // what `serviceRecordPath` demands before it joins the id into a
+                // file name. The raw flag never reaches the join.
+                await record({ docsDir, featureDir: feature.dir, json, recovered }, checklist, {
+                    service: config.service,
+                    repoDir: config.root ?? process.cwd(),
+                    previous: existing.state === "ok" ? { verification: existing.verification, files: existing.files } : null,
+                }, opts);
+                return;
+            }
+            report({ docsDir, featureDir: feature.dir, json }, checklist, recorded, {
+                lens: opts.service,
+                bound: config.service,
+            });
+        }
+        finally {
+            // Released on every path out — a refusal that kept the lock would turn
+            // one bad answer set into a wedged docs repo for everyone else.
+            if (releaseLock !== null)
+                await releaseLock();
+        }
+    });
+}
+//# sourceMappingURL=verify.js.map