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

package/dist/core/verify/evidence/contract.js

@@ -0,0 +1,169 @@
+/**
+ * `loam verify --contract-results` — an API contract-test report as the answer
+ * sheet for `api.exposes` claims.
+ *
+ * The accepted shape is loam's own documented one (SCHEMA.md, "Contract-test
+ * reports"): `{"loamContractReport": 1, "results": [{"operationId": "…",
+ * "status": "passed"}]}`. It is deliberately a shape tools EMIT INTO rather
+ * than a vendor format loam parses, because no surveyed vendor format carries
+ * both halves of what confirming needs — an unambiguous executed-AND-passed
+ * status and a deterministic operation join key. Specmatic's JSON coverage
+ * report was the v1 candidate and is declined by name: its `coverageStatus:
+ * "covered"` means exercised, not passed (a red run still writes "covered"),
+ * so an adapter over it would confirm exactly what a failing suite refuted.
+ *
+ * The operationId is the ONLY identity, matched against the structured
+ * `operation` a claim carries (`../checklist.ts`). It is half an identity, and
+ * the design leans on the missing half being supplied by scope: an operationId
+ * is unique within ONE contract document, not across a fleet, and a report
+ * entry names no service — so when more than one service on the handed-in
+ * checklist exposes the same operationId, the claims are refused rather than
+ * answered ({@link contestedOperations}), and `--service` is what gives a
+ * contract report an owner, exactly as it is for a contested scenario digest.
+ * Within one service's claims the match is exact, and renaming an operation
+ * renames its claim, so rewording cannot carry an answer over. Names and free
+ * text match nothing.
+ *
+ * Parsing is strict where the cucumber reader is tolerant, and the asymmetry
+ * is deliberate: a cucumber report is another tool's file full of legitimate
+ * entries loam has no business judging, while this shape exists for exactly
+ * one purpose, so an entry that cannot be matched is a malformed report, not
+ * scenery. A file that is recognizably not this shape refuses rather than
+ * quietly answering every claim "not exercised" — an unparseable report never
+ * silently answers zero claims as if none matched.
+ */
+import { isRecord } from "../../kernel/records.js";
+import {} from "../answers.js";
+import {} from "../checklist.js";
+/** The marker key that makes a JSON document this shape, and the version this loam reads. */
+export const CONTRACT_REPORT_MARKER = "loamContractReport";
+export const CONTRACT_REPORT_VERSION = 1;
+/**
+ * Read a parsed JSON document down to its runs. `reportName` is how the caller
+ * spelled the file, for the refusal message; core never prints, so a refusal
+ * is data for the command to fail with (`answers-unreadable`).
+ */
+export function readContractReport(doc, reportName) {
+    const shape = `{"${CONTRACT_REPORT_MARKER}": ${CONTRACT_REPORT_VERSION}, "results": [{"operationId": "…", "status": "passed"}]}`;
+    if (!isRecord(doc) || !(CONTRACT_REPORT_MARKER in doc)) {
+        return {
+            ok: false,
+            message: `${reportName} is not a contract-results report — expected loam's generic shape ${shape} ` +
+                "(see SCHEMA.md's contract-test reports section; Specmatic, Pact, Dredd and property harnesses emit it with a one-line transform).",
+        };
+    }
+    if (doc[CONTRACT_REPORT_MARKER] !== CONTRACT_REPORT_VERSION) {
+        // A later version may redefine what an entry means; reading it with this
+        // parser could confirm something the report never said. Fail closed.
+        return {
+            ok: false,
+            message: `${reportName} declares ${CONTRACT_REPORT_MARKER}: ${JSON.stringify(doc[CONTRACT_REPORT_MARKER])} — ` +
+                `this loam reads version ${CONTRACT_REPORT_VERSION} only.`,
+        };
+    }
+    const results = doc["results"];
+    if (!Array.isArray(results)) {
+        return { ok: false, message: `${reportName} has no \`results\` array — expected ${shape}.` };
+    }
+    const runs = [];
+    for (const [i, entry] of results.entries()) {
+        const where = `${reportName} entry ${i + 1}`;
+        if (!isRecord(entry))
+            return { ok: false, message: `${where} is not an object — expected ${shape}.` };
+        const operationId = entry["operationId"];
+        if (typeof operationId !== "string" || operationId.length === 0) {
+            return { ok: false, message: `${where} has no operationId — every entry must name the operation it exercised.` };
+        }
+        const status = entry["status"];
+        if (typeof status !== "string" || status.length === 0) {
+            return {
+                ok: false,
+                message: `${where} ('${operationId}') has no status — expected "passed", "failed", or the tool's own word for anything else.`,
+            };
+        }
+        const test = entry["test"];
+        runs.push({
+            operationId,
+            status,
+            ...(typeof test === "string" && test.trim().length > 0 ? { test: test.trim() } : {}),
+        });
+    }
+    return { ok: true, runs };
+}
+/**
+ * The operationIds that more than one service on this checklist exposes, with
+ * the services that expose them — `contestedDigests`' (core/results.ts) exact
+ * shape, for this axis's join key.
+ *
+ * An operationId is unique within one contract document, not across a fleet:
+ * two services may each expose a 'createSplit', and a report entry carries no
+ * service half, so a single contract report matches both services' claims and
+ * cannot say whose suite it describes. The all-at-once form once confirmed a
+ * service from a suite that never touched it exactly this way. loam does not
+ * choose: those claims are refused rather than answered, and `--service` is
+ * what gives a report an owner — it narrows the checklist to one subject
+ * before the matching starts, so nothing handed in here is contested.
+ */
+export function contestedOperations(claims) {
+    const owners = new Map();
+    for (const c of claims) {
+        if (c.operation === undefined)
+            continue;
+        const seen = owners.get(c.operation) ?? new Set();
+        seen.add(c.subject);
+        owners.set(c.operation, seen);
+    }
+    const contested = new Map();
+    for (const [operation, services] of owners) {
+        if (services.size > 1)
+            contested.set(operation, [...services].sort());
+    }
+    return contested;
+}
+/**
+ * Answer every claim from the report — the contract runner's half of the
+ * record. Total over the claims handed in, like `runnerAnswers`: a claim the
+ * report does not exercise is answered `unconfirmed`, never skipped, because
+ * silence must never read as checked. Report entries matching no claim are
+ * skipped silently — a real contract suite exercises the whole living API,
+ * and the claims only ever cover what the feature ADDS.
+ *
+ * Confirmation is strict on purpose: every matching entry (an operationId the
+ * report holds twice is two test cases, and all of them count) has status
+ * exactly `"passed"`. One non-passed entry wins as failure, and an unknown
+ * status is named in the note rather than rounded to either verdict. An
+ * operationId two services expose is refused before any of that: see
+ * {@link contestedOperations}.
+ */
+export function contractAnswers(claims, runs, reportName) {
+    const contested = contestedOperations(claims);
+    return claims.map((c) => {
+        const rivals = c.operation === undefined ? undefined : contested.get(c.operation);
+        if (rivals !== undefined) {
+            return answer(c.id, "unconfirmed", [], `operationId '${c.operation}' is exposed by more than one service on this checklist (${rivals.join(", ")}), ` +
+                `so ${reportName} cannot say whose suite exercised it. Record each service's claims from its own repo with --service.`);
+        }
+        if (c.operation === undefined) {
+            // Unreachable for the api.exposes claims this loam derives, which always
+            // carry one — but the function is total, and a claim without a join key
+            // must fail closed rather than throw or silently confirm.
+            return answer(c.id, "unconfirmed", [], "claim carries no operationId for a contract report to match on");
+        }
+        const matching = runs.filter((r) => r.operationId === c.operation);
+        if (matching.length === 0) {
+            return answer(c.id, "unconfirmed", [], `not exercised — no entry in ${reportName} names operationId '${c.operation}'`);
+        }
+        const failing = matching.filter((r) => r.status !== "passed");
+        if (failing.length === 0) {
+            return answer(c.id, "confirmed", matching.map((r) => `${reportName}: ${r.test ?? `operationId '${c.operation}' passed`}`));
+        }
+        const first = failing[0];
+        const why = first.status === "failed" ? "failed" : `status '${first.status}' is not 'passed'`;
+        const rerun = matching.length > 1 ? ` — ${failing.length} of ${matching.length} matching entries did not pass` : "";
+        return answer(c.id, "unconfirmed", [], `${why} (${reportName}${first.test === undefined ? "" : `: ${first.test}`})${rerun}`);
+    });
+}
+function answer(id, verdict, evidence, note) {
+    return { id, verdict, evidence, ...(note === undefined ? {} : { note }), answered_by: "external-runner" };
+}
+//# sourceMappingURL=contract.js.map

package/dist/core/verify/evidence/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../../src/core/verify/evidence/contract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam verify --contract-results` — an API contract-test report as the answer\n * sheet for `api.exposes` claims.\n *\n * The accepted shape is loam's own documented one (SCHEMA.md, \"Contract-test\n * reports\"): `{\"loamContractReport\": 1, \"results\": [{\"operationId\": \"…\",\n * \"status\": \"passed\"}]}`. It is deliberately a shape tools EMIT INTO rather\n * than a vendor format loam parses, because no surveyed vendor format carries\n * both halves of what confirming needs — an unambiguous executed-AND-passed\n * status and a deterministic operation join key. Specmatic's JSON coverage\n * report was the v1 candidate and is declined by name: its `coverageStatus:\n * \"covered\"` means exercised, not passed (a red run still writes \"covered\"),\n * so an adapter over it would confirm exactly what a failing suite refuted.\n *\n * The operationId is the ONLY identity, matched against the structured\n * `operation` a claim carries (`../checklist.ts`). It is half an identity, and\n * the design leans on the missing half being supplied by scope: an operationId\n * is unique within ONE contract document, not across a fleet, and a report\n * entry names no service — so when more than one service on the handed-in\n * checklist exposes the same operationId, the claims are refused rather than\n * answered ({@link contestedOperations}), and `--service` is what gives a\n * contract report an owner, exactly as it is for a contested scenario digest.\n * Within one service's claims the match is exact, and renaming an operation\n * renames its claim, so rewording cannot carry an answer over. Names and free\n * text match nothing.\n *\n * Parsing is strict where the cucumber reader is tolerant, and the asymmetry\n * is deliberate: a cucumber report is another tool's file full of legitimate\n * entries loam has no business judging, while this shape exists for exactly\n * one purpose, so an entry that cannot be matched is a malformed report, not\n * scenery. A file that is recognizably not this shape refuses rather than\n * quietly answering every claim \"not exercised\" — an unparseable report never\n * silently answers zero claims as if none matched.\n */\nimport { isRecord } from \"../../kernel/records.js\";\nimport { type Answer } from \"../answers.js\";\nimport { type Claim } from \"../checklist.js\";\n\n/** The marker key that makes a JSON document this shape, and the version this loam reads. */\nexport const CONTRACT_REPORT_MARKER = \"loamContractReport\";\nexport const CONTRACT_REPORT_VERSION = 1;\n\n/** One report entry, reduced to what matching needs. Extra keys pass untouched. */\nexport interface ContractRun {\n  operationId: string;\n  /** Exactly `\"passed\"` confirms; `\"failed\"` and every other string do not. */\n  status: string;\n  /** Optional free text naming the test — it rides into the evidence line. */\n  test?: string;\n}\n\nexport type ContractReportRead =\n  | { ok: true; runs: ContractRun[] }\n  | { ok: false; message: string };\n\n/**\n * Read a parsed JSON document down to its runs. `reportName` is how the caller\n * spelled the file, for the refusal message; core never prints, so a refusal\n * is data for the command to fail with (`answers-unreadable`).\n */\nexport function readContractReport(doc: unknown, reportName: string): ContractReportRead {\n  const shape =\n    `{\"${CONTRACT_REPORT_MARKER}\": ${CONTRACT_REPORT_VERSION}, \"results\": [{\"operationId\": \"…\", \"status\": \"passed\"}]}`;\n  if (!isRecord(doc) || !(CONTRACT_REPORT_MARKER in doc)) {\n    return {\n      ok: false,\n      message:\n        `${reportName} is not a contract-results report — expected loam's generic shape ${shape} ` +\n        \"(see SCHEMA.md's contract-test reports section; Specmatic, Pact, Dredd and property harnesses emit it with a one-line transform).\",\n    };\n  }\n  if (doc[CONTRACT_REPORT_MARKER] !== CONTRACT_REPORT_VERSION) {\n    // A later version may redefine what an entry means; reading it with this\n    // parser could confirm something the report never said. Fail closed.\n    return {\n      ok: false,\n      message:\n        `${reportName} declares ${CONTRACT_REPORT_MARKER}: ${JSON.stringify(doc[CONTRACT_REPORT_MARKER])} — ` +\n        `this loam reads version ${CONTRACT_REPORT_VERSION} only.`,\n    };\n  }\n  const results = doc[\"results\"];\n  if (!Array.isArray(results)) {\n    return { ok: false, message: `${reportName} has no \\`results\\` array — expected ${shape}.` };\n  }\n  const runs: ContractRun[] = [];\n  for (const [i, entry] of results.entries()) {\n    const where = `${reportName} entry ${i + 1}`;\n    if (!isRecord(entry)) return { ok: false, message: `${where} is not an object — expected ${shape}.` };\n    const operationId = entry[\"operationId\"];\n    if (typeof operationId !== \"string\" || operationId.length === 0) {\n      return { ok: false, message: `${where} has no operationId — every entry must name the operation it exercised.` };\n    }\n    const status = entry[\"status\"];\n    if (typeof status !== \"string\" || status.length === 0) {\n      return {\n        ok: false,\n        message: `${where} ('${operationId}') has no status — expected \"passed\", \"failed\", or the tool's own word for anything else.`,\n      };\n    }\n    const test = entry[\"test\"];\n    runs.push({\n      operationId,\n      status,\n      ...(typeof test === \"string\" && test.trim().length > 0 ? { test: test.trim() } : {}),\n    });\n  }\n  return { ok: true, runs };\n}\n\n/**\n * The operationIds that more than one service on this checklist exposes, with\n * the services that expose them — `contestedDigests`' (core/results.ts) exact\n * shape, for this axis's join key.\n *\n * An operationId is unique within one contract document, not across a fleet:\n * two services may each expose a 'createSplit', and a report entry carries no\n * service half, so a single contract report matches both services' claims and\n * cannot say whose suite it describes. The all-at-once form once confirmed a\n * service from a suite that never touched it exactly this way. loam does not\n * choose: those claims are refused rather than answered, and `--service` is\n * what gives a report an owner — it narrows the checklist to one subject\n * before the matching starts, so nothing handed in here is contested.\n */\nexport function contestedOperations(claims: readonly Claim[]): Map<string, string[]> {\n  const owners = new Map<string, Set<string>>();\n  for (const c of claims) {\n    if (c.operation === undefined) continue;\n    const seen = owners.get(c.operation) ?? new Set<string>();\n    seen.add(c.subject);\n    owners.set(c.operation, seen);\n  }\n  const contested = new Map<string, string[]>();\n  for (const [operation, services] of owners) {\n    if (services.size > 1) contested.set(operation, [...services].sort());\n  }\n  return contested;\n}\n\n/**\n * Answer every claim from the report — the contract runner's half of the\n * record. Total over the claims handed in, like `runnerAnswers`: a claim the\n * report does not exercise is answered `unconfirmed`, never skipped, because\n * silence must never read as checked. Report entries matching no claim are\n * skipped silently — a real contract suite exercises the whole living API,\n * and the claims only ever cover what the feature ADDS.\n *\n * Confirmation is strict on purpose: every matching entry (an operationId the\n * report holds twice is two test cases, and all of them count) has status\n * exactly `\"passed\"`. One non-passed entry wins as failure, and an unknown\n * status is named in the note rather than rounded to either verdict. An\n * operationId two services expose is refused before any of that: see\n * {@link contestedOperations}.\n */\nexport function contractAnswers(claims: Claim[], runs: ContractRun[], reportName: string): Answer[] {\n  const contested = contestedOperations(claims);\n  return claims.map((c) => {\n    const rivals = c.operation === undefined ? undefined : contested.get(c.operation);\n    if (rivals !== undefined) {\n      return answer(\n        c.id,\n        \"unconfirmed\",\n        [],\n        `operationId '${c.operation}' is exposed by more than one service on this checklist (${rivals.join(\", \")}), ` +\n          `so ${reportName} cannot say whose suite exercised it. Record each service's claims from its own repo with --service.`,\n      );\n    }\n    if (c.operation === undefined) {\n      // Unreachable for the api.exposes claims this loam derives, which always\n      // carry one — but the function is total, and a claim without a join key\n      // must fail closed rather than throw or silently confirm.\n      return answer(c.id, \"unconfirmed\", [], \"claim carries no operationId for a contract report to match on\");\n    }\n    const matching = runs.filter((r) => r.operationId === c.operation);\n    if (matching.length === 0) {\n      return answer(\n        c.id,\n        \"unconfirmed\",\n        [],\n        `not exercised — no entry in ${reportName} names operationId '${c.operation}'`,\n      );\n    }\n    const failing = matching.filter((r) => r.status !== \"passed\");\n    if (failing.length === 0) {\n      return answer(\n        c.id,\n        \"confirmed\",\n        matching.map((r) => `${reportName}: ${r.test ?? `operationId '${c.operation}' passed`}`),\n      );\n    }\n    const first = failing[0]!;\n    const why = first.status === \"failed\" ? \"failed\" : `status '${first.status}' is not 'passed'`;\n    const rerun =\n      matching.length > 1 ? ` — ${failing.length} of ${matching.length} matching entries did not pass` : \"\";\n    return answer(\n      c.id,\n      \"unconfirmed\",\n      [],\n      `${why} (${reportName}${first.test === undefined ? \"\" : `: ${first.test}`})${rerun}`,\n    );\n  });\n}\n\nfunction answer(id: string, verdict: Answer[\"verdict\"], evidence: string[], note?: string): Answer {\n  return { id, verdict, evidence, ...(note === undefined ? {} : { note }), answered_by: \"external-runner\" };\n}\n"]}

package/dist/core/verify/file.js

@@ -0,0 +1,257 @@
+/**
+ * `verification.yaml` read back, and refused when it cannot be trusted.
+ *
+ * Reading is deliberately not the inverse of rendering. A record loam wrote is
+ * re-graded on the way in — unreadable YAML, a shape that is not a
+ * verification, a `summary` that disagrees with the claims below it — because
+ * the file is data meant to survive without loam, and anything may have edited
+ * it since. The render lives with the writer it feeds (`store/render.ts`
+ * produces exactly the bytes `store/commit.ts` swaps into place; races and
+ * kills mid-write live there too), and the lock that serialises writers is
+ * taken by `commands/verify/verify.ts` before this module's authoritative
+ * read. Nothing here touches the filesystem except to read.
+ */
+import { lstat, readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { isRecord } from "../kernel/records.js";
+import { VERDICTS } from "./answers.js";
+import { isEvidencePinList } from "./pins/pin.js";
+import { tallyAnswers, verificationPath } from "./record.js";
+export async function readVerificationState(featureDir) {
+    const path = verificationPath(featureDir);
+    let raw;
+    try {
+        raw = await readFile(path);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            // ENOENT is "absent" — except from a symlink whose target is gone, which
+            // `existsSync` used to fold into the same answer. That mislabel was a
+            // trap: the read said "no record" while the commit's exclusive link(2)
+            // saw the link itself and refused EEXIST, so every `--record` answered
+            // `record-raced` with advice (re-run) that could never work. The lstat
+            // must CONFIRM the link before the message asserts one: a real file can
+            // also appear between the two calls, and telling its owner to "remove
+            // the link" would delete a valid record.
+            let entry;
+            try {
+                entry = await lstat(path);
+            }
+            catch {
+                return { state: "absent" };
+            }
+            if (entry.isSymbolicLink()) {
+                return {
+                    state: "unreadable",
+                    reason: "it is a symlink whose target does not exist — replace the link with a real record, or remove it",
+                };
+            }
+            return {
+                state: "unreadable",
+                reason: "it appeared while being read — another writer is landing; re-run",
+            };
+        }
+        return { state: "unreadable", reason: err instanceof Error ? err.message : String(err) };
+    }
+    let doc;
+    try {
+        doc = parse(raw.toString("utf8"));
+    }
+    catch (err) {
+        return { state: "unreadable", reason: yamlReason(err) };
+    }
+    const verification = asVerification(doc);
+    if (verification === null) {
+        return {
+            state: "unreadable",
+            reason: "it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)",
+        };
+    }
+    const miscount = summaryDisagreement(verification);
+    if (miscount === null)
+        return { state: "ok", verification, raw };
+    return {
+        state: "unreadable",
+        // Spelled twice on purpose: the field is what a caller branches on, the
+        // prose is what a terminal prints and what somebody greps for.
+        code: "verify.record-miscounted",
+        reason: `verify.record-miscounted: ${miscount}`,
+    };
+}
+/**
+ * Does the record's `summary` add up from its own `claims[]`?
+ *
+ * The summary is what wrote the file; the claims are what it answered. Nothing
+ * ever compared them, so every reader that took the shortcut — verify's frozen
+ * verdict for a shipped feature, list's column, status's block — reported a
+ * record full of unconfirmed claims as fully confirmed. Believing either side
+ * over the other would be a guess about which half was tampered with, so a
+ * record that contradicts itself is refused like any other file loam cannot
+ * use. The code is in the reason: it travels wherever the reason is printed.
+ */
+function summaryDisagreement(v) {
+    const t = tallyAnswers(v.claims);
+    const unanswered = v.summary.unanswered ?? 0;
+    const says = [];
+    // Before the arithmetic, because a negative count defeats it: `unanswered:
+    // -2` is never something loam wrote, and it is the one value that lets a
+    // hand-edited summary balance its own books — every comparison below then
+    // agrees, and a record contradicting its claims reported `verified`.
+    for (const [field, value] of Object.entries(v.summary)) {
+        if (typeof value === "number" && value < 0)
+            says.push(`carries a negative count (${field}: ${value})`);
+    }
+    if (v.summary.confirmed !== t.confirmed) {
+        says.push(`says ${v.summary.confirmed} confirmed where claims[] holds ${t.confirmed}`);
+    }
+    if (v.summary.unconfirmed !== t.unconfirmed) {
+        says.push(`says ${v.summary.unconfirmed} unconfirmed where claims[] holds ${t.unconfirmed}`);
+    }
+    if (v.summary.claims !== v.claims.length + unanswered) {
+        says.push(`says ${v.summary.claims} claim(s)${unanswered === 0 ? "" : ` including ${unanswered} unanswered`} where claims[] holds ${v.claims.length}`);
+    }
+    return says.length === 0
+        ? null
+        : `its summary ${says.join(", ")} — the record contradicts itself, so neither half can be believed`;
+}
+/** A YAML failure with its line, when the parser located one: that line is the fix. */
+function yamlReason(err) {
+    const message = err instanceof Error ? err.message.split("\n")[0].trim() : String(err);
+    const pos = err?.linePos;
+    const line = Array.isArray(pos) ? pos[0]?.line : undefined;
+    return line === undefined ? `YAML error: ${message}` : `YAML error at line ${line}: ${message}`;
+}
+/**
+ * The record beside a feature, or null when there is none loam can use. Kept
+ * for readers that have nothing to say about the difference (`loam list`'s
+ * verification column shows one glyph either way); anything that WRITES must
+ * use {@link readVerificationState} instead, or it overwrites what it could not
+ * read.
+ *
+ * A record whose summary contradicts its own claims is one of the nulls now, so
+ * no reader can print its counts as fact. Reading it as ABSENT is the safe half
+ * of the truth and not the whole of it: a reader that can say why should take
+ * {@link readVerificationState} and its `code`.
+ */
+export async function readVerification(featureDir) {
+    const read = await readVerificationState(featureDir);
+    return read.state === "ok" ? read.verification : null;
+}
+/**
+ * The shape check `readVerification` stands behind: everything its readers
+ * dereference (verify's report/frozen views, list's verification column) must
+ * be present and typed, or the cast would manufacture a Verification that
+ * crashes them. Deliberately no tighter than the readers need: extra keys pass
+ * (a human may annotate), `answered_by` stays optional (absent in records that
+ * predate `--results`) and is any string, like `kind` — the readers only ever
+ * compare them, and a record written by a newer loam must not read as absent.
+ */
+function asVerification(doc) {
+    if (!isRecord(doc))
+        return null;
+    const summary = doc["summary"];
+    if (typeof doc["feature"] !== "string" ||
+        typeof doc["recorded"] !== "string" ||
+        typeof doc["checklist"] !== "string" ||
+        !isRecord(summary) ||
+        !isCount(summary["claims"]) ||
+        !isCount(summary["confirmed"]) ||
+        !isCount(summary["unconfirmed"]) ||
+        (summary["unanswered"] !== undefined && !isCount(summary["unanswered"])) ||
+        !Array.isArray(doc["claims"])) {
+        return null;
+    }
+    for (const c of doc["claims"]) {
+        if (!isRecord(c))
+            return null;
+        if (typeof c["id"] !== "string" || typeof c["kind"] !== "string" || typeof c["claim"] !== "string")
+            return null;
+        if (c["subject"] !== undefined && typeof c["subject"] !== "string")
+            return null;
+        if (typeof c["verdict"] !== "string" || !VERDICTS.includes(c["verdict"]))
+            return null;
+        // The frozen view iterates evidence per claim — a scalar here would crash it.
+        if (!Array.isArray(c["evidence"]) || c["evidence"].some((e) => typeof e !== "string"))
+            return null;
+        if (c["note"] !== undefined && typeof c["note"] !== "string")
+            return null;
+        if (c["answered_by"] !== undefined && typeof c["answered_by"] !== "string")
+            return null;
+        // Absent fine, present whole — the isConsumedContractReport precedent, and
+        // the guard body lives with the pin shape it vouches for (pins/pin.ts). A
+        // broken pins block makes the whole record unreadable and therefore never
+        // overwritten: skipping it instead would read a hand-damaged record as
+        // drift-free.
+        if (!isEvidencePinList(c["evidence_pins"]))
+            return null;
+    }
+    if (doc["schema"] !== undefined && doc["schema"] !== 2)
+        return null;
+    if (!isConsumedReport(doc["report"]))
+        return null;
+    if (!isConsumedContractReport(doc["contractReport"]))
+        return null;
+    if (doc["attestations"] !== undefined) {
+        if (!Array.isArray(doc["attestations"]))
+            return null;
+        for (const a of doc["attestations"]) {
+            if (!isRecord(a))
+                return null;
+            if (typeof a["service"] !== "string" || typeof a["commit"] !== "string" || typeof a["recorded"] !== "string")
+                return null;
+            if (!/^[0-9a-f]{40,64}$/i.test(a["commit"]))
+                return null;
+            if (!Array.isArray(a["claims"]) || a["claims"].some((id) => typeof id !== "string"))
+                return null;
+            if (!isConsumedReport(a["report"]))
+                return null;
+            if (!isConsumedContractReport(a["contractReport"]))
+                return null;
+        }
+    }
+    return doc;
+}
+/** Absent is fine — most records answer nothing from a report. Present must be whole: it is printed. */
+function isConsumedReport(v) {
+    if (v === undefined)
+        return true;
+    return (isRecord(v) &&
+        typeof v["path"] === "string" &&
+        typeof v["digest"] === "string" &&
+        typeof v["mtime"] === "string" &&
+        isCount(v["scenarios"]));
+}
+/**
+ * The contract report's pin, exactly as loose as {@link isConsumedReport}:
+ * absent fine, present whole — for the fields the readers dereference.
+ * `format` is OPTIONAL here even though loam always writes it: nothing in the
+ * readers dereferences it (it is provenance for a person, echoed only inside
+ * whole-object payloads), and the generated AGENTS.md teaches the pin as
+ * path/sha256/mtime/operation-count — so a hand-written block faithful to that
+ * teaching must not make the WHOLE record unreadable over a field no reader
+ * uses. When present it must be a string, and any string: a record written by
+ * a newer loam that learned a second report format must not read as
+ * unreadable here.
+ */
+function isConsumedContractReport(v) {
+    if (v === undefined)
+        return true;
+    return (isRecord(v) &&
+        typeof v["path"] === "string" &&
+        typeof v["digest"] === "string" &&
+        typeof v["mtime"] === "string" &&
+        isCount(v["operations"]) &&
+        (v["format"] === undefined || typeof v["format"] === "string"));
+}
+/**
+ * A summary count: an integer. YAML hands back strings for anything quoted.
+ * Negativity is deliberately NOT checked here: a negative count is a summary
+ * that disagrees with the claims below it, and `summaryDisagreement` owns that
+ * refusal — failing the SHAPE check instead made the message list five keys
+ * that were all present, while the miscount branch one call away holds the
+ * advice the case actually needs.
+ */
+function isCount(v) {
+    return typeof v === "number" && Number.isInteger(v);
+}
+//# sourceMappingURL=file.js.map

package/dist/core/verify/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/core/verify/file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `verification.yaml` read back, and refused when it cannot be trusted.\n *\n * Reading is deliberately not the inverse of rendering. A record loam wrote is\n * re-graded on the way in — unreadable YAML, a shape that is not a\n * verification, a `summary` that disagrees with the claims below it — because\n * the file is data meant to survive without loam, and anything may have edited\n * it since. The render lives with the writer it feeds (`store/render.ts`\n * produces exactly the bytes `store/commit.ts` swaps into place; races and\n * kills mid-write live there too), and the lock that serialises writers is\n * taken by `commands/verify/verify.ts` before this module's authoritative\n * read. Nothing here touches the filesystem except to read.\n */\nimport { lstat, readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport { isRecord } from \"../kernel/records.js\";\nimport { VERDICTS } from \"./answers.js\";\nimport { isEvidencePinList } from \"./pins/pin.js\";\nimport { tallyAnswers, verificationPath, type Verification } from \"./record.js\";\n\n/**\n * What is on disk beside a feature: nothing, something unreadable, or a record.\n *\n * The three are kept apart because they call for opposite handling. \"Absent\" is\n * a feature nobody has verified — verify starts a fresh record over it without\n * a second thought. \"Unreadable\" is a file that IS somebody's record: it parses\n * as garbage, or its shape is not a record's, and every answer and attestation\n * it holds is unaccounted for. Collapsing the two (which this function used to\n * do, returning null for both) meant a hand-edited or half-written\n * verification.yaml read as \"not verified\" and the next `--record` overwrote a\n * whole fleet's attestations without a word.\n */\nexport type VerificationRead =\n  | { state: \"absent\" }\n  /**\n   * `reason` names the YAML line when the parser gave one — the file is the\n   * thing to fix. `code` is set for the one unreadable that parses perfectly: a\n   * record whose `summary` contradicts its own `claims[]`. That lives here\n   * rather than in a state of its own so every reader which already refuses an\n   * unreadable record refuses this one too, without a line of new code.\n   */\n  | { state: \"unreadable\"; reason: string; code?: \"verify.record-miscounted\" }\n  /**\n   * `raw` is the exact bytes `verification` was parsed from. A writer merges\n   * over the PARSE, but commits over the BYTES: `commitVerification` compares\n   * these against the file immediately before its swap, so an edit that landed\n   * between this read and that write — an editor, a writer that ignored the\n   * docs lock — is refused and preserved instead of silently buried.\n   */\n  | { state: \"ok\"; verification: Verification; raw: Buffer };\n\nexport async function readVerificationState(featureDir: string): Promise<VerificationRead> {\n  const path = verificationPath(featureDir);\n  let raw: Buffer;\n  try {\n    raw = await readFile(path);\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n      // ENOENT is \"absent\" — except from a symlink whose target is gone, which\n      // `existsSync` used to fold into the same answer. That mislabel was a\n      // trap: the read said \"no record\" while the commit's exclusive link(2)\n      // saw the link itself and refused EEXIST, so every `--record` answered\n      // `record-raced` with advice (re-run) that could never work. The lstat\n      // must CONFIRM the link before the message asserts one: a real file can\n      // also appear between the two calls, and telling its owner to \"remove\n      // the link\" would delete a valid record.\n      let entry;\n      try {\n        entry = await lstat(path);\n      } catch {\n        return { state: \"absent\" };\n      }\n      if (entry.isSymbolicLink()) {\n        return {\n          state: \"unreadable\",\n          reason: \"it is a symlink whose target does not exist — replace the link with a real record, or remove it\",\n        };\n      }\n      return {\n        state: \"unreadable\",\n        reason: \"it appeared while being read — another writer is landing; re-run\",\n      };\n    }\n    return { state: \"unreadable\", reason: err instanceof Error ? err.message : String(err) };\n  }\n  let doc: unknown;\n  try {\n    doc = parse(raw.toString(\"utf8\"));\n  } catch (err) {\n    return { state: \"unreadable\", reason: yamlReason(err) };\n  }\n  const verification = asVerification(doc);\n  if (verification === null) {\n    return {\n      state: \"unreadable\",\n      reason:\n        \"it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)\",\n    };\n  }\n  const miscount = summaryDisagreement(verification);\n  if (miscount === null) return { state: \"ok\", verification, raw };\n  return {\n    state: \"unreadable\",\n    // Spelled twice on purpose: the field is what a caller branches on, the\n    // prose is what a terminal prints and what somebody greps for.\n    code: \"verify.record-miscounted\",\n    reason: `verify.record-miscounted: ${miscount}`,\n  };\n}\n\n/**\n * Does the record's `summary` add up from its own `claims[]`?\n *\n * The summary is what wrote the file; the claims are what it answered. Nothing\n * ever compared them, so every reader that took the shortcut — verify's frozen\n * verdict for a shipped feature, list's column, status's block — reported a\n * record full of unconfirmed claims as fully confirmed. Believing either side\n * over the other would be a guess about which half was tampered with, so a\n * record that contradicts itself is refused like any other file loam cannot\n * use. The code is in the reason: it travels wherever the reason is printed.\n */\nfunction summaryDisagreement(v: Verification): string | null {\n  const t = tallyAnswers(v.claims);\n  const unanswered = v.summary.unanswered ?? 0;\n  const says: string[] = [];\n  // Before the arithmetic, because a negative count defeats it: `unanswered:\n  // -2` is never something loam wrote, and it is the one value that lets a\n  // hand-edited summary balance its own books — every comparison below then\n  // agrees, and a record contradicting its claims reported `verified`.\n  for (const [field, value] of Object.entries(v.summary)) {\n    if (typeof value === \"number\" && value < 0) says.push(`carries a negative count (${field}: ${value})`);\n  }\n  if (v.summary.confirmed !== t.confirmed) {\n    says.push(`says ${v.summary.confirmed} confirmed where claims[] holds ${t.confirmed}`);\n  }\n  if (v.summary.unconfirmed !== t.unconfirmed) {\n    says.push(`says ${v.summary.unconfirmed} unconfirmed where claims[] holds ${t.unconfirmed}`);\n  }\n  if (v.summary.claims !== v.claims.length + unanswered) {\n    says.push(\n      `says ${v.summary.claims} claim(s)${unanswered === 0 ? \"\" : ` including ${unanswered} unanswered`} where claims[] holds ${v.claims.length}`,\n    );\n  }\n  return says.length === 0\n    ? null\n    : `its summary ${says.join(\", \")} — the record contradicts itself, so neither half can be believed`;\n}\n\n/** A YAML failure with its line, when the parser located one: that line is the fix. */\nfunction yamlReason(err: unknown): string {\n  const message = err instanceof Error ? err.message.split(\"\\n\")[0]!.trim() : String(err);\n  const pos = (err as { linePos?: Array<{ line: number; col: number }> } | null)?.linePos;\n  const line = Array.isArray(pos) ? pos[0]?.line : undefined;\n  return line === undefined ? `YAML error: ${message}` : `YAML error at line ${line}: ${message}`;\n}\n\n/**\n * The record beside a feature, or null when there is none loam can use. Kept\n * for readers that have nothing to say about the difference (`loam list`'s\n * verification column shows one glyph either way); anything that WRITES must\n * use {@link readVerificationState} instead, or it overwrites what it could not\n * read.\n *\n * A record whose summary contradicts its own claims is one of the nulls now, so\n * no reader can print its counts as fact. Reading it as ABSENT is the safe half\n * of the truth and not the whole of it: a reader that can say why should take\n * {@link readVerificationState} and its `code`.\n */\nexport async function readVerification(featureDir: string): Promise<Verification | null> {\n  const read = await readVerificationState(featureDir);\n  return read.state === \"ok\" ? read.verification : null;\n}\n\n/**\n * The shape check `readVerification` stands behind: everything its readers\n * dereference (verify's report/frozen views, list's verification column) must\n * be present and typed, or the cast would manufacture a Verification that\n * crashes them. Deliberately no tighter than the readers need: extra keys pass\n * (a human may annotate), `answered_by` stays optional (absent in records that\n * predate `--results`) and is any string, like `kind` — the readers only ever\n * compare them, and a record written by a newer loam must not read as absent.\n */\nfunction asVerification(doc: unknown): Verification | null {\n  if (!isRecord(doc)) return null;\n  const summary = doc[\"summary\"];\n  if (\n    typeof doc[\"feature\"] !== \"string\" ||\n    typeof doc[\"recorded\"] !== \"string\" ||\n    typeof doc[\"checklist\"] !== \"string\" ||\n    !isRecord(summary) ||\n    !isCount(summary[\"claims\"]) ||\n    !isCount(summary[\"confirmed\"]) ||\n    !isCount(summary[\"unconfirmed\"]) ||\n    (summary[\"unanswered\"] !== undefined && !isCount(summary[\"unanswered\"])) ||\n    !Array.isArray(doc[\"claims\"])\n  ) {\n    return null;\n  }\n  for (const c of doc[\"claims\"]) {\n    if (!isRecord(c)) return null;\n    if (typeof c[\"id\"] !== \"string\" || typeof c[\"kind\"] !== \"string\" || typeof c[\"claim\"] !== \"string\") return null;\n    if (c[\"subject\"] !== undefined && typeof c[\"subject\"] !== \"string\") return null;\n    if (typeof c[\"verdict\"] !== \"string\" || !(VERDICTS as readonly string[]).includes(c[\"verdict\"])) return null;\n    // The frozen view iterates evidence per claim — a scalar here would crash it.\n    if (!Array.isArray(c[\"evidence\"]) || c[\"evidence\"].some((e) => typeof e !== \"string\")) return null;\n    if (c[\"note\"] !== undefined && typeof c[\"note\"] !== \"string\") return null;\n    if (c[\"answered_by\"] !== undefined && typeof c[\"answered_by\"] !== \"string\") return null;\n    // Absent fine, present whole — the isConsumedContractReport precedent, and\n    // the guard body lives with the pin shape it vouches for (pins/pin.ts). A\n    // broken pins block makes the whole record unreadable and therefore never\n    // overwritten: skipping it instead would read a hand-damaged record as\n    // drift-free.\n    if (!isEvidencePinList(c[\"evidence_pins\"])) return null;\n  }\n  if (doc[\"schema\"] !== undefined && doc[\"schema\"] !== 2) return null;\n  if (!isConsumedReport(doc[\"report\"])) return null;\n  if (!isConsumedContractReport(doc[\"contractReport\"])) return null;\n  if (doc[\"attestations\"] !== undefined) {\n    if (!Array.isArray(doc[\"attestations\"])) return null;\n    for (const a of doc[\"attestations\"]) {\n      if (!isRecord(a)) return null;\n      if (typeof a[\"service\"] !== \"string\" || typeof a[\"commit\"] !== \"string\" || typeof a[\"recorded\"] !== \"string\") return null;\n      if (!/^[0-9a-f]{40,64}$/i.test(a[\"commit\"])) return null;\n      if (!Array.isArray(a[\"claims\"]) || a[\"claims\"].some((id) => typeof id !== \"string\")) return null;\n      if (!isConsumedReport(a[\"report\"])) return null;\n      if (!isConsumedContractReport(a[\"contractReport\"])) return null;\n    }\n  }\n  return doc as unknown as Verification;\n}\n\n/** Absent is fine — most records answer nothing from a report. Present must be whole: it is printed. */\nfunction isConsumedReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"scenarios\"])\n  );\n}\n\n/**\n * The contract report's pin, exactly as loose as {@link isConsumedReport}:\n * absent fine, present whole — for the fields the readers dereference.\n * `format` is OPTIONAL here even though loam always writes it: nothing in the\n * readers dereferences it (it is provenance for a person, echoed only inside\n * whole-object payloads), and the generated AGENTS.md teaches the pin as\n * path/sha256/mtime/operation-count — so a hand-written block faithful to that\n * teaching must not make the WHOLE record unreadable over a field no reader\n * uses. When present it must be a string, and any string: a record written by\n * a newer loam that learned a second report format must not read as\n * unreadable here.\n */\nfunction isConsumedContractReport(v: unknown): boolean {\n  if (v === undefined) return true;\n  return (\n    isRecord(v) &&\n    typeof v[\"path\"] === \"string\" &&\n    typeof v[\"digest\"] === \"string\" &&\n    typeof v[\"mtime\"] === \"string\" &&\n    isCount(v[\"operations\"]) &&\n    (v[\"format\"] === undefined || typeof v[\"format\"] === \"string\")\n  );\n}\n\n/**\n * A summary count: an integer. YAML hands back strings for anything quoted.\n * Negativity is deliberately NOT checked here: a negative count is a summary\n * that disagrees with the claims below it, and `summaryDisagreement` owns that\n * refusal — failing the SHAPE check instead made the message list five keys\n * that were all present, while the miscount branch one call away holds the\n * advice the case actually needs.\n */\nfunction isCount(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v);\n}\n\n"]}