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

package/dist/commands/verify/results.js

@@ -0,0 +1,246 @@
+/**
+ * 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 { 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 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");
+    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`. Legacy global mode deliberately keeps its original, looser
+ * evidence contract for backward compatibility.
+ *
+ * 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 match = /^(.+):([1-9]\d*)$/.exec(evidence);
+            if (match === null) {
+                return err(`Claim ${answer.id} has evidence '${evidence}' — service 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 ${answer.id}`);
+            }
+            catch (cause) {
+                return err(`Claim ${answer.id} has unsafe evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            try {
+                const info = await stat(absolutePath);
+                if (!info.isFile()) {
+                    return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' is not a regular file.`);
+                }
+                const source = await readFile(absolutePath, "utf8");
+                const lines = sourceLines(source).length;
+                if (line > lines) {
+                    return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' has only ${lines} line(s).`);
+                }
+                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 };
+}
+/** 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 mirrors
+ * `core/provenance/git.ts`; 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.
+ */
+const GIT_TIMEOUT_MS = 10_000;
+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 { 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 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\");\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`. Legacy global mode deliberately keeps its original, looser\n * evidence contract for backward compatibility.\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 match = /^(.+):([1-9]\\d*)$/.exec(evidence);\n      if (match === null) {\n        return err(`Claim ${answer.id} has evidence '${evidence}' — service 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 ${answer.id}`);\n      } catch (cause) {\n        return err(`Claim ${answer.id} has unsafe evidence '${evidence}': ${cause instanceof Error ? cause.message : String(cause)}`);\n      }\n      try {\n        const info = await stat(absolutePath);\n        if (!info.isFile()) {\n          return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' is not a regular file.`);\n        }\n        const source = await readFile(absolutePath, \"utf8\");\n        const lines = sourceLines(source).length;\n        if (line > lines) {\n          return err(`Claim ${answer.id} has evidence '${evidence}', but '${relativePath}' has only ${lines} line(s).`);\n        }\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 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 mirrors\n * `core/provenance/git.ts`; the cap is sized for `git show` of a source file\n * an attestation cites (the default 1 MiB refused sound evidence the moment a\n * generated client crossed it), not for arbitrary blobs.\n */\nconst GIT_TIMEOUT_MS = 10_000;\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,217 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { fail, repoPath, reportNoConfig } from "../../core/envelope/json.js";
+import { missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { InterruptedCommitError } from "../../core/staging/interrupted.js";
+import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { docsRepoReady } from "../policy/gate.js";
+import { featureChecklist } from "../../core/verify/checklist.js";
+import { readVerificationState } from "../../core/verify/file.js";
+import { verificationPath } from "../../core/verify/record.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 shipped feature against its own promises: derive the claims, record the answers")
+        .option("--record <file>", "record a JSON answer set against the current checklist")
+        .option("--results <file>", "answer the scenario.tested claims mechanically from a cucumber JSON test report")
+        .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 loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const config = loaded.config;
+        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.
+        let releaseLock = null;
+        let recovered = null;
+        if (recording) {
+            try {
+                releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
+            }
+            catch (err) {
+                if (err instanceof DocsBusyError)
+                    return fail(json, "docs-busy", err.message);
+                throw err;
+            }
+        }
+        try {
+            // 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. INSIDE the try: this refusal must release the lock like
+            // every other path out, and once did not.
+            if (recording) {
+                try {
+                    recovered = await recoverInterruptedCommit(docsDir);
+                }
+                catch (err) {
+                    if (!(err instanceof InterruptedCommitError))
+                        throw err;
+                    return fail(json, "commit-interrupted", err.message);
+                }
+            }
+            // 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 verification.yaml 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.
+            const existing = await readVerificationState(feature.dir);
+            if (existing.state === "unreadable") {
+                return fail(json, "record-unreadable", `${repoPath(docsDir, verificationPath(feature.dir))} exists but cannot be read as a verification record: ${existing.reason}. ` +
+                    (existing.code === "verify.record-miscounted"
+                        ? "Record the answers again rather than editing the counts: a summary made to agree by hand still says nothing about what was checked."
+                        : "It is plain YAML — repair it by hand, or delete it and record again. 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.
+            if (feature.archived) {
+                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;
+            }
+            const checklist = await featureChecklist(docsDir, feature.dir, feature.id);
+            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.
+                await record({ docsDir, featureDir: feature.dir, json, recovered }, checklist, {
+                    service: opts.service ?? config.service,
+                    repoDir: config.root ?? process.cwd(),
+                    previous: existing.state === "ok" ? { verification: existing.verification, raw: existing.raw } : 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();
+        }
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Reading                                                             */
+/* ------------------------------------------------------------------ */
+//# sourceMappingURL=verify.js.map

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

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

package/dist/commands/vouch/contract.js

@@ -0,0 +1,11 @@
+/**
+ * What a vouch IS: the request, the stamp it writes, and every way it can
+ * refuse.
+ *
+ * The outcome is a union rather than a result plus an error field because the
+ * command prints a different shape for each arm, and the stamp only exists on
+ * the arm that wrote one. A flat record would have every reader assert what the
+ * writer already knew.
+ */
+import {} from "../../core/envelope/json.js";
+//# sourceMappingURL=contract.js.map

package/dist/commands/vouch/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/commands/vouch/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAkB,MAAM,6BAA6B,CAAC","sourcesContent":["/**\n * What a vouch IS: the request, the stamp it writes, and every way it can\n * refuse.\n *\n * The outcome is a union rather than a result plus an error field because the\n * command prints a different shape for each arm, and the stamp only exists on\n * the arm that wrote one. A flat record would have every reader assert what the\n * writer already knew.\n */\nimport { type ErrorCode } from \"../../core/envelope/json.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../core/kernel/ids/service.js\";\nimport type { CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport type { VouchScope } from \"../../core/provenance/sample/scope.js\";\nimport type { SkippedSource } from \"../../core/provenance/walk.js\";\n// The plan's shapes live with the pass that derives them (`sample/plan.ts`),\n// the way pack's `SectionDelta` lives with `pack/sections.ts`. The import\n// direction is parent-from-child, which is the only one the package graph\n// allows here: a sub-package that reached back up into this file would close\n// the cycle `vet/verify.ts` was moved down to avoid.\nimport type { SamplePlan } from \"./sample/plan.js\";\n\nexport interface VouchRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what `sources` resolve against. */\n  repoDir: string;\n  /** The date to stamp. Injected rather than read off the clock, so it can be pinned. */\n  today: string;\n  /**\n   * Who is vouching, as `vouched_by` is stamped — git's identity for `repoDir`.\n   * Injected for the same reason `today` is: this function must be reproducible\n   * from its arguments, and the resolution (and its refusal) belongs to the\n   * command that can talk to a person about it.\n   */\n  vouchedBy: string;\n  /**\n   * The sample a person was shown before they answered, under `--sample <n>`.\n   * Absent for an ordinary vouch — and its absence is what CLEARS a prior\n   * sampled stamp, since a full run deletes `vouch_scope` from every file it\n   * writes.\n   */\n  sample?: SamplePlan;\n}\n\n/** One spec-axis file's share of a successful vouch. */\nexport interface StampedSpec {\n  /** Absolute path of the file that was stamped. */\n  path: string;\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". */\n  file: string;\n  /** Digest of the sources, as stamped into `sources_digest`. */\n  digest: string;\n  /** Digest of the document's own body, as stamped into `content_digest`. */\n  contentDigest: string;\n  /** The `sources` entries, as written in the frontmatter. */\n  sources: string[];\n  /** How many files those entries expanded to. */\n  files: number;\n  /**\n   * Paths under those entries the digest would not hash. A vouch over a spec\n   * with a skipped path is still a vouch — the person read what they read — but\n   * they are told, because the stamp cannot go stale over bytes it never saw.\n   */\n  skipped: SkippedSource[];\n  /**\n   * What was written into `vouch_scope`, or null when the file was read in\n   * full and the field was deleted. The report describes what the stamp\n   * ACTUALLY says rather than what the plan asked for: a file whose section\n   * count was at or under `--sample <n>` is stamped as a full vouch, and the\n   * screen the person is looking at has to say so.\n   */\n  vouchScope: VouchScope | null;\n}\n\nexport type VouchOutcome =\n  | {\n      ok: true;\n      status: \"verified\";\n      lastVerified: string;\n      /** The identity stamped into every file this vouch touched. */\n      vouchedBy: string;\n      /**\n       * Non-null when this run first rolled a predecessor's interrupted\n       * commit forward — the caller reports it, because docs changing beyond\n       * the stamp would otherwise read as this vouch's doing.\n       */\n      recovered: CommitRecovery | null;\n      /**\n       * Every spec-axis file stamped. Named, not ordered: spec.md is required\n       * for a vouch to happen at all, and arch.spec.md is the only other file\n       * one can touch, so the type is what says which is which. An array said it\n       * in a comment instead, and every reader had to assert non-emptiness to\n       * reach the file that comment promised was there.\n       */\n      stamped: { spec: StampedSpec; archSpec: StampedSpec | null };\n    }\n  | {\n      ok: false;\n      // The last three are the commit phase failing: `vouch-raced` says the\n      // document moved under the run and nothing was written at all,\n      // `merge-failed` says the rollback held (nothing was stamped, re-running\n      // can work), `rollback-incomplete` says it did not and the message lists\n      // the files.\n      code: Extract<\n        ErrorCode,\n        | \"unknown-target\"\n        | \"sources-absent\"\n        | \"sources-path-missing\"\n        // The spec is there but is not UTF-8 text: a diagnosable state, not the\n        // unexpected throw `internal` is for.\n        | \"repository-unavailable\"\n        | \"vouch-raced\"\n        | \"merge-failed\"\n        | \"rollback-incomplete\"\n        // The commit window now takes the docs lock and reads the journal:\n        // another writer can hold the one, a predecessor's crash can leave\n        // the other. Both are the codes every other journaled writer answers.\n        | \"docs-busy\"\n        | \"commit-interrupted\"\n      >;\n      message: string;\n    };\n"]}

package/dist/commands/vouch/pack/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/commands/vouch/pack/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/commands/vouch/pack/contract.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * What a reading pack IS: the request, the per-axis verdicts, and the one way\n * it can refuse. The same seam as `../contract.ts` one level up — the shapes\n * live apart from the derivation so the printer can name what it renders\n * without importing how it was computed.\n *\n * Every verdict is a discriminated union rather than optional-field soup, and\n * the arms are exactly the honest answers: a body is unchanged, or diffable\n * from a NAMED ancestor, or a full read with the reason — never a guessed\n * diff; sources are unchanged, a named delta, a counted-but-nameless move, a\n * state the re-vouch itself would refuse over, or simply unvouched.\n */\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport type { SkippedSource } from \"../../../core/provenance/walk.js\";\nimport type { LandscapeEdge } from \"../../../core/vocabulary/maturity.js\";\nimport type { PackSample, PackVouchScope, SectionDelta } from \"./sections.js\";\n\nexport interface PackRequest {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo — what the source delta resolves `sources` against. */\n  repoDir: string;\n  /**\n   * `--sample <n>`, when the pack is being read as the reading list for a\n   * SAMPLED vouch. The pack then prescribes exactly the sections that\n   * `loam vouch --sample <n>` will stamp for, through the same seeded\n   * derivation — a pack and a stamp that disagreed about which sections were\n   * read would make the record worse than no record.\n   */\n  sample?: number;\n}\n\n/** The body half of one axis's pack: what to read of the document itself. */\nexport type PackBody =\n  | { kind: \"unchanged\" }\n  | { kind: \"diff\"; ancestorCommit: string; diff: string; sections: SectionDelta }\n  | { kind: \"full-read\"; reason: string };\n\n/** The source half: what moved under the code the document was written from. */\nexport type PackSources =\n  | { kind: \"unchanged\" }\n  | { kind: \"delta\"; added: string[]; changed: string[]; removed: string[] }\n  /**\n   * The digest moved but the stamp cannot name the paths — the count-only\n   * >100-file fallback (`countThen` known) or an index that contradicts its\n   * own digest (`countThen` null when even the count is unreadable).\n   */\n  | { kind: \"uncounted\"; countThen: number | null; countNow: number }\n  /** The re-vouch itself would refuse over these sources; the reason IS the worklist. */\n  | { kind: \"unavailable\"; reason: string }\n  /** Sources resolve but carry no stamp — nothing to diff against yet. */\n  | { kind: \"unvouched\" };\n\nexport interface PackAxis {\n  /** Docs-relative, `/`-separated — the contract's path spelling. */\n  path: string;\n  /** The axis's filename — \"spec.md\" or \"arch.spec.md\". */\n  file: string;\n  /** The stamp's own fields, read back for the \"already covered\" listing. */\n  vouchedBy?: string;\n  lastVerified?: string;\n  body: PackBody;\n  sources: PackSources;\n  /**\n   * Paths under the listed sources the digest recompute would not hash —\n   * walk.ts's skip record, carried on the axis because it is orthogonal to\n   * the sources verdict (it can accompany unchanged, delta and unvouched\n   * alike). Never dropped: these are the parts of the tree the re-vouch's\n   * promise will NOT cover, and the pack is now the screen a person reads\n   * BEFORE staking that promise. Empty when the vetting itself refused —\n   * nobody walked, so nobody can name what a walk would skip.\n   */\n  skipped: SkippedSource[];\n  /**\n   * Every H2 heading of the current body — set whenever the whole file is the\n   * read (`body.kind === \"full-read\"`: a first vouch, a never-vouched axis, a\n   * body whose vouched ancestor cannot be reached), because a full read is\n   * exactly where the listing IS the reading plan. Per axis, not per mode:\n   * an arch.spec.md created after the last vouch gets its plan inside a\n   * re-vouch pack.\n   */\n  headings?: string[];\n  /**\n   * The LAST vouch's scope, when that vouch was sampled — present-but-\n   * undecodable included, because an unreadable scope on a verified document\n   * must never read as a full vouch. Its presence withdraws the \"already\n   * covered\" licence for this axis: `unchanged` says the text did not move,\n   * and after a sampled vouch that is not the same fact as \"somebody read it\".\n   */\n  vouchScope?: PackVouchScope;\n  /**\n   * What a `--sample <n>` vouch would cover, under `--pack --sample <n>`. The\n   * forward direction, where `vouchScope` above is the backward one: one says\n   * what the next stamp will claim, the other what the last one did.\n   */\n  sample?: PackSample;\n}\n\n/** What the fleet map says about the service — the first read of a first vouch. */\nexport type PackLandscape =\n  | { kind: \"edges\"; inbound: LandscapeEdge[]; outbound: LandscapeEdge[] }\n  | { kind: \"silent\"; reason: string };\n\nexport interface PackReport {\n  service: string;\n  /** \"first-vouch\" when spec.md carries neither digest — nothing exists to diff against. */\n  packMode: \"re-vouch\" | \"first-vouch\";\n  /**\n   * A predecessor's interrupted docs-repo commit journal exists, so what is\n   * on disk may predate the write it was killed inside — including the very\n   * stamps this pack read. The pack cannot roll the journal forward (recovery\n   * is itself a write, and this command may not write), so it says so instead\n   * of silently describing a state the next journaled writer will replace.\n   */\n  pendingCommit: boolean;\n  spec: PackAxis;\n  archSpec: PackAxis | null;\n  /** First-vouch only (null otherwise): landscape claims come first in the reading order. */\n  landscape: PackLandscape | null;\n}\n\nexport type PackOutcome =\n  | { ok: true; report: PackReport }\n  | { ok: false; code: \"unknown-target\"; message: string };\n"]}