@ybotok/loam 0.0.0 → 0.1.0-beta.2

package/dist/core/verify.js

@@ -0,0 +1,807 @@
+/**
+ * The done-check: did the code that was built match the feature that was
+ * designed?
+ *
+ * The original plan was to extract C4 from the built code and diff it against
+ * the delta. There is no such extractor and there will not be one — nothing
+ * deterministic reads a service and says what its architecture MEANS, and two
+ * generated models of the same code disagree in wording every run, so the diff
+ * would flap and be switched off inside a week.
+ *
+ * What survives of the idea is the part that was always deterministic: the
+ * QUESTIONS. A feature's own artifacts say exactly what it promised — this
+ * service will exist, it will expose this operation, that service will call it,
+ * this scenario will have a test. loam derives that list mechanically from the
+ * same files `validate` already reads, an agent answers each claim with
+ * evidence, and `--record` writes the answers down beside the feature.
+ *
+ * A scenario claim is answered mechanically wherever it can be: `--results`
+ * reads a cucumber JSON report and matches it by the digest tag `loam gherkin`
+ * stamped, and only a green run confirms one (results.ts). Where it cannot —
+ * a legacy service whose suite is months away, which is the fleet loam exists
+ * for — `--record` may still take an agent's word for it, and the record marks
+ * that answer ATTESTED rather than run: `verified` is reserved for a checklist
+ * whose scenarios a run answered, and `verify.scenario-attested` says so on
+ * every surface that reads the record.
+ *
+ * Two properties make the record worth keeping. The claim ids are a function of
+ * the claim and of nothing else — so two runs are diffable, reordering the delta
+ * renames nothing, and rewording a scenario DOES rename its claim, because an
+ * answer about text nobody wrote must not carry over. And an answer set that
+ * does not correspond to the current checklist is refused rather than merged:
+ * an unchecked claim must never be able to masquerade as checked.
+ *
+ * loam does not judge the answers. It cannot: it never read the code. It only
+ * guarantees that every question was asked and that every answer is on the
+ * record next to the question it answers.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import { elementService, loadFile, serviceOf } from "./likec4.js";
+import { operationIds, operations } from "./openapi.js";
+import { isRecord } from "./records.js";
+import { featurePaths, featureSpecPaths, featureSpecServices, servicePaths } from "./repo.js";
+import { parseRequirements } from "./spec.js";
+/**
+ * What a claim is about. The order is the order the checklist comes back in,
+ * and it reads as the story of the feature: the service exists, it exposes its
+ * operations, the calls into it are wired, the behaviour is tested.
+ */
+export const CLAIM_KINDS = ["service.exists", "api.exposes", "c4.calls", "scenario.tested"];
+/**
+ * How much of the sha256 goes into an id, and into a digest — the checklist's,
+ * and a scenario claim's runner-matching one, which is deliberately the same
+ * 16 hex `loam gherkin` stamps (its GHERKIN_DIGEST_LENGTH): the tag in a
+ * cucumber report and the digest on a claim must be the same string.
+ */
+const ID_LENGTH = 8;
+const DIGEST_LENGTH = 16;
+/** C4 kinds that model people. A person is never a service. (Mirrors validate.ts.) */
+const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+/**
+ * Derive the checklist from a feature's own artifacts. No code is read here and
+ * none should be: the whole design rests on the questions being computed from
+ * documents that do not change between runs.
+ */
+export async function featureChecklist(docsDir, featureDir, featureId) {
+    const seen = new Map();
+    const claim = (kind, subject, parts, text) => ({
+        id: claimId(featureId, kind, parts, seen),
+        kind,
+        subject,
+        claim: text,
+    });
+    const exists = [];
+    const exposes = [];
+    const calls = [];
+    const scenarios = [];
+    // Architecture — what the delta promised the fleet would look like.
+    const deltaPath = featurePaths(featureDir).delta;
+    if (existsSync(deltaPath)) {
+        const res = await loadFile(deltaPath);
+        // A delta nobody can parse promises nothing checkable. `validate` already
+        // reports it; inventing claims out of a broken document would only add noise.
+        if (res.errors.length === 0) {
+            const elements = res.elements;
+            for (const e of elements) {
+                if (!e.tags.includes(featureId))
+                    continue;
+                // A dotted id is a container INSIDE a service, and an actor is nobody's
+                // repository. Neither is a service that has to exist.
+                if (e.id.includes(".") || ACTOR_KINDS.has(e.kind.toLowerCase()))
+                    continue;
+                const svc = elementService(e);
+                exists.push(claim("service.exists", svc, [svc], `service '${svc}' exists`));
+            }
+            for (const r of res.relationships) {
+                // Untagged edges are context for the diagram; an edge with no operation
+                // names nothing specific enough to look for in the code.
+                if (!r.tags.includes(featureId) || r.op === undefined)
+                    continue;
+                const from = serviceOf(elements, r.source);
+                const to = serviceOf(elements, r.target);
+                calls.push(claim("c4.calls", from, [from, to, r.op], `${from} calls '${r.op}' on ${to}`));
+            }
+        }
+    }
+    for (const svc of await featureSpecServices(featureDir)) {
+        const paths = featureSpecPaths(featureDir, svc);
+        // Contract — only what is NEW. A delta's openapi.yaml is a whole document,
+        // not a patch, so authors restate the living API inside it; asking whether a
+        // service still exposes what it already exposed is noise.
+        const featOps = (await operations(paths.openapi))
+            .filter((operation) => !operation.remove)
+            .map((operation) => operation.id);
+        if (featOps.length > 0) {
+            const living = new Set(await operationIds(servicePaths(docsDir, svc).openapi));
+            for (const op of featOps) {
+                if (living.has(op))
+                    continue;
+                exposes.push(claim("api.exposes", svc, [svc, op], `${svc} exposes operationId '${op}'`));
+            }
+        }
+        // Behaviour — the scenarios of the requirements this feature CHANGES. A BASE
+        // requirement is the living state quoted inside the delta, and a REMOVED one
+        // is being retired: neither is work anybody has to have done.
+        if (existsSync(paths.spec)) {
+            for (const r of parseRequirements(await readFile(paths.spec, "utf8"))) {
+                if (r.kind === "BASE" || r.kind === "REMOVED")
+                    continue;
+                for (const s of r.scenarios) {
+                    const body = scenarioBodyHash(svc, s.lines);
+                    scenarios.push({
+                        ...claim("scenario.tested", svc, [svc, r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)], `scenario '${s.name}' of requirement '${r.name}' (${svc}) is covered by a test`),
+                        digest: body.slice(0, DIGEST_LENGTH),
+                    });
+                }
+            }
+        }
+        // The architecture spec axis, same walk: an arch scenario is a promise like
+        // any other — the outbox test nobody was going to write IS the point of the
+        // axis. The source file rides in the id tuple AND in the body hash itself
+        // (two axes are two namespaces: identically-worded scenarios must stay two
+        // questions, and the axis-salted digest is what keeps a business-only test
+        // run from answering the arch claim) and in the claim text, so the
+        // answering agent knows it is being asked for an integration/ops test, not
+        // an acceptance test.
+        if (existsSync(paths.archSpec)) {
+            for (const r of parseRequirements(await readFile(paths.archSpec, "utf8"))) {
+                if (r.kind === "BASE" || r.kind === "REMOVED")
+                    continue;
+                for (const s of r.scenarios) {
+                    const body = scenarioBodyHash(svc, s.lines, "arch");
+                    scenarios.push({
+                        ...claim("scenario.tested", svc, [svc, "arch.spec.md", r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)], `scenario '${s.name}' of arch requirement '${r.name}' (${svc}, arch.spec.md) is covered by a test`),
+                        digest: body.slice(0, DIGEST_LENGTH),
+                    });
+                }
+            }
+        }
+    }
+    const claims = [...exists, ...exposes, ...calls, ...scenarios];
+    return { feature: featureId, claims, digest: checklistDigest(claims) };
+}
+/**
+ * A claim's identity: a hash of what it says, and nothing about how it was
+ * produced.
+ *
+ * The feature id is part of it so an answers file for one feature can never
+ * validate against another. Two claims that really are identical (the same
+ * scenario name twice under one requirement) are distinguished by occurrence, in
+ * document order — they are still two questions, and answering one must not
+ * answer the other.
+ *
+ * The hash is short because the claim text sits next to it everywhere it is
+ * shown; it identifies a question, it does not authenticate one.
+ */
+function claimId(featureId, kind, parts, seen) {
+    // NUL-joined so no claim's own text can spell another claim's tuple by
+    // containing the separator: ['a b','c'] and ['a','b c'] stay two questions.
+    const tuple = [featureId, kind, ...parts].join("\u0000");
+    const n = (seen.get(tuple) ?? 0) + 1;
+    seen.set(tuple, n);
+    const canonical = n === 1 ? tuple : `${tuple}\u0000#${n}`;
+    return `${kind}-${createHash("sha256").update(canonical).digest("hex").slice(0, ID_LENGTH)}`;
+}
+/**
+ * The full sha256 of a scenario's body — its lines joined and edge-trimmed,
+ * exactly as `serializeRequirements` frames them. The BODY, not the title,
+ * because rewriting the Given/When/Then under an unchanged heading is new text
+ * nobody answered for, and the promise — rewording a scenario renames its
+ * claim — has to hold for the words that actually specify the behaviour.
+ *
+ * ONE recipe with three consumers, deliberately in one place:
+ * `scenario.tested` claim ids fold in its first {@link ID_LENGTH} hex
+ * characters, a claim's `digest` and the `@loam-digest-<16hex>` tag `loam
+ * gherkin` stamps both take its first {@link DIGEST_LENGTH} — so the claim,
+ * the stamp and the report `--results` reads can never disagree about what a
+ * scenario says.
+ *
+ * The identity is (SERVICE, AXIS, body), and both salts are there for the same
+ * reason: a digest that spans two namespaces lets one green run answer a
+ * question nobody ran a test for.
+ *
+ * - The AXIS salt keeps `spec.md` and `arch.spec.md` apart. Without it a green
+ *   BUSINESS run answered the arch claim too — an integration test nobody wrote
+ *   read as run.
+ * - The SERVICE salt keeps two repositories apart. "the service returns 404 for
+ *   an unknown id" is worded the same way in nine services of a real fleet;
+ *   unsalted, all nine shared one digest, `loam gherkin` stamped one tag into
+ *   nine repositories, and one repository's green run confirmed the other
+ *   eight's claims — across suites that never ran each other's tests.
+ *
+ * The service salt is what makes that case CORRECT rather than merely refused:
+ * `contestedDigests` could only decline to answer a shared digest, which left a
+ * fleet with ordinary repeated wording holding claims nothing could ever
+ * answer.
+ *
+ * Both salts renamed every claim id and every stamped tag on the day they
+ * landed, and both readings are legible rather than silent: an existing
+ * `verification.yaml` answers a checklist digest that is no longer derived and
+ * reports STALE, and an existing generated `.feature` carries digests the
+ * living spec no longer computes and reports `gherkin.stale` beside the
+ * `gherkin.missing` for the new ones. One `loam gherkin` and one re-record
+ * clear both.
+ */
+export function scenarioBodyHash(service, lines, axis = "business") {
+    // NUL-separated like claimId's tuples, and for its reason: no body can spell
+    // the salt in front of it, so the namespaces stay disjoint. Spelled as an
+    // escape and never as a raw NUL in the literal — a raw one makes this file
+    // read as `data` to `file(1)` and invisible to `grep`.
+    const body = lines.join("\n").trim();
+    const onAxis = axis === "arch" ? `arch.spec.md\u0000${body}` : body;
+    return createHash("sha256").update(`${service}\u0000${onAxis}`).digest("hex");
+}
+/**
+ * A digest of the claim id SET — sorted, so reordering the artifacts does not
+ * make a record look stale. It changes when a claim is added, removed or
+ * reworded, which is exactly when an answer set stops describing the feature.
+ */
+function checklistDigest(claims) {
+    const ids = claims.map((c) => c.id).sort();
+    return createHash("sha256").update(ids.join("\n")).digest("hex").slice(0, DIGEST_LENGTH);
+}
+/* ------------------------------------------------------------------ */
+/* The answers                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Two verdicts, deliberately. Anything an agent cannot show evidence for is
+ * unconfirmed — a third value for "not applicable" would absorb every claim
+ * nobody wanted to answer.
+ */
+export const VERDICTS = ["confirmed", "unconfirmed"];
+/**
+ * Who answered a claim: the `runner` (a cucumber report's digest-tagged
+ * scenarios, matched mechanically by `--results`) or an `agent` (somebody's
+ * word about the code, taken back by `--record`). On the record so a reviewer
+ * can tell a green run from an assertion.
+ */
+export const ANSWERED_BY = ["runner", "agent"];
+/**
+ * Accept an answer set only if it answers THIS checklist: every claim once, no
+ * claim twice, nothing extra, and no "confirmed" that shows nothing.
+ *
+ * The refusals are the point of the command. If a stale or partial answer file
+ * could be recorded, `verification.yaml` would say a claim was checked when
+ * nobody ever asked it — and a record that can lie is worse than no record,
+ * because it looks like evidence.
+ *
+ * `runnerOwned` is the composition rule under `--results`: ids the test runner
+ * answers, which an answers file must therefore not touch. An entry naming one
+ * refuses with its own diagnosis — the id IS on the feature's checklist, so
+ * calling it unknown would send the caller hunting a staleness that is not
+ * there.
+ *
+ * `context` is what turns the last line from a circle into an instruction. In a
+ * fleet the commonest way to "miss" a claim is that it is not yours: the
+ * checklist spans ten repositories and this one can only answer its own. Told
+ * only to "answer the claims it lists", an agent in the payment-service repo
+ * re-runs verify, sees the same checkout-web claims it cannot speak for, and
+ * either loops or invents evidence. So when every unanswered claim belongs to
+ * another service, say THAT, and name the command that records them.
+ */
+export function checkAnswers(claims, raw, runnerOwned, context) {
+    const refuse = (code, message) => ({ ok: false, code, message });
+    const list = Array.isArray(raw)
+        ? raw
+        : isRecord(raw) && Array.isArray(raw["answers"])
+            ? raw["answers"]
+            : null;
+    if (list === null) {
+        return refuse("answers-unreadable", "Expected a JSON array of answers, or an object with an `answers` array: " +
+            `[{ "id": "...", "verdict": "confirmed", "evidence": ["file:line"] }]`);
+    }
+    const answers = [];
+    for (const [i, entry] of list.entries()) {
+        const where = `answer ${i + 1}`;
+        if (!isRecord(entry))
+            return refuse("answers-unreadable", `${where} is not an object`);
+        const id = entry["id"];
+        if (typeof id !== "string" || id.length === 0) {
+            return refuse("answers-unreadable", `${where} has no claim id`);
+        }
+        const verdict = entry["verdict"];
+        if (typeof verdict !== "string" || !VERDICTS.includes(verdict)) {
+            return refuse("answers-unreadable", `${where} ('${id}') has verdict ${JSON.stringify(verdict)} — expected one of ${VERDICTS.join(", ")}`);
+        }
+        const note = typeof entry["note"] === "string" ? entry["note"].trim() : "";
+        answers.push({
+            id,
+            verdict: verdict,
+            evidence: stringList(entry["evidence"]),
+            ...(note.length > 0 ? { note } : {}),
+            answered_by: "agent",
+        });
+    }
+    const byId = new Map();
+    const twice = [];
+    for (const a of answers) {
+        if (byId.has(a.id))
+            twice.push(a.id);
+        else
+            byId.set(a.id, a);
+    }
+    const known = new Set(claims.map((c) => c.id));
+    const strayIds = [...new Set(answers.map((a) => a.id).filter((id) => !known.has(id)))];
+    const runnerHit = strayIds.filter((id) => runnerOwned?.has(id) === true);
+    const unknown = strayIds.filter((id) => runnerOwned?.has(id) !== true);
+    const missingClaims = claims.filter((c) => !byId.has(c.id));
+    const missing = missingClaims.map((c) => c.id);
+    if (runnerHit.length + unknown.length + missing.length + twice.length > 0) {
+        const parts = [
+            runnerHit.length > 0
+                ? `${runnerHit.length} answer(s) name scenario claim(s) the test runner owns under --results: ${runnerHit.join(", ")} — the report answers those; take them out of the answers file`
+                : "",
+            unknown.length > 0 ? `${unknown.length} answer(s) name a claim that is not on the checklist: ${unknown.join(", ")}` : "",
+            missing.length > 0 ? `${missing.length} claim(s) have no answer: ${missing.join(", ")}` : "",
+            twice.length > 0 ? `${twice.length} claim(s) answered more than once: ${[...new Set(twice)].join(", ")}` : "",
+        ].filter((s) => s.length > 0);
+        return refuse("answers-mismatch", `These answers do not match the checklist — ${parts.join("; ")}. ` +
+            missingAdvice(missingClaims, claims.filter((c) => byId.has(c.id)), context));
+    }
+    const unevidenced = claims
+        .map((c) => byId.get(c.id))
+        .filter((a) => a.verdict === "confirmed" && a.evidence.length === 0)
+        .map((a) => a.id);
+    if (unevidenced.length > 0) {
+        return refuse("answers-unevidenced", `${unevidenced.length} claim(s) are confirmed with no evidence: ${unevidenced.join(", ")}. A confirmation with nothing behind it is an assertion — give a file:line, or answer 'unconfirmed'.`);
+    }
+    // Checklist order, not the order they were written in: the record reads in the
+    // order the questions were asked, whatever the agent did.
+    return { ok: true, answers: claims.map((c) => byId.get(c.id)) };
+}
+/**
+ * The last sentence of an `answers-mismatch`. "Re-run and answer the claims it
+ * lists" is sound advice only when the caller CAN answer them. In a fleet the
+ * checklist is federated — a feature's claims are filed under the service whose
+ * code answers them — so the honest diagnosis for a repo that answered
+ * everything it owns is "the rest is not yours", together with the form that
+ * records the rest. Anything else sends the caller round the same loop.
+ */
+function missingAdvice(missing, answered, context) {
+    const generic = "Re-run `loam verify` and answer the claims it lists.";
+    if (context === undefined || missing.length === 0 || answered.length === 0)
+        return generic;
+    // The signature of "I answered mine and the rest is not mine": the services
+    // that own the unanswered claims and the services that own the answered ones
+    // do not overlap. A single-service checklist with one claim forgotten fails
+    // this test and keeps the generic advice, which is the right advice there —
+    // that claim really is the caller's to answer.
+    const owners = [...new Set(missing.map((c) => c.subject))].sort();
+    const covered = new Set(answered.map((c) => c.subject));
+    if (owners.some((s) => covered.has(s)))
+        return generic;
+    const form = `\`loam verify ${context.feature} --record answers.json --service <svc>\``;
+    const mine = context.service;
+    return mine === undefined
+        ? `Those claims are owned by ${owners.join(", ")} — each service attests its own from its own repository (${form}); ` +
+            "this all-at-once form has to answer the whole checklist in one file."
+        : `Every unanswered claim belongs to a different service (${owners.join(", ")}) and this repository can only attest '${mine}' — ` +
+            `run ${form} in each of those repositories instead.`;
+}
+function stringList(v) {
+    if (typeof v === "string")
+        return v.trim().length > 0 ? [v.trim()] : [];
+    if (!Array.isArray(v))
+        return [];
+    return v.map((x) => String(x).trim()).filter((s) => s.length > 0);
+}
+/**
+ * The confirmed `scenario.tested` claims that no test run answered.
+ *
+ * A scenario claim's whole premise is that a run answers it — its digest IS the
+ * tag `loam gherkin` stamps, and `--results` matches the two mechanically. An
+ * agent may still answer one, because a legacy service has no runnable suite
+ * for months and that fleet is who loam is for; but the answer is somebody's
+ * word about a test, and it must not read as the run. A record written before
+ * `--results` existed carries no `answered_by` at all: unknown counts as agent
+ * here, because the alternative is to credit a run nobody can point at.
+ */
+export function attestedClaims(claims) {
+    return claims
+        .filter((c) => c.kind === "scenario.tested" && c.verdict === "confirmed" && c.answered_by !== "runner")
+        .map((c) => c.id);
+}
+/**
+ * `unanswered` is the count the answers themselves cannot show: a federated
+ * record holds only what somebody answered, and the claims still owed to other
+ * repositories exist on the checklist, not in `claims[]`. Read views that carry
+ * an `unanswered` status inside the list pass 0 and are counted in place.
+ */
+export function tallyAnswers(claims, unanswered = 0) {
+    const of = (verdict) => claims.filter((c) => c.verdict === verdict).length;
+    return {
+        claims: claims.length + unanswered,
+        confirmed: of("confirmed"),
+        unconfirmed: of("unconfirmed"),
+        unanswered: of("unanswered") + unanswered,
+        attested: attestedClaims(claims).length,
+    };
+}
+/**
+ * The record's own answers, recounted. Never `v.summary`: the summary is what
+ * whoever wrote the file said the answers add up to, and every reader that
+ * believed it reported a record full of unconfirmed claims as fully confirmed.
+ * `readVerificationState` refuses a record whose summary contradicts this, so a
+ * caller holding a Verification may use either — and should use this one.
+ */
+export function tallyRecord(v) {
+    return tallyAnswers(v.claims, v.summary.unanswered ?? 0);
+}
+/**
+ * Three states, because two were a lie. `verified` is the strong claim — every
+ * question answered, every answer confirmed, and every scenario answered by a
+ * digest-matched green run. `attested` is the same completeness resting, for at
+ * least one scenario, on an agent's word. `unverified` is everything else:
+ * nothing recorded, a record gone stale, a claim unanswered or unconfirmed, or
+ * a checklist that asks nothing at all.
+ */
+export const VERIFICATION_VERDICTS = ["verified", "attested", "unverified"];
+export function verificationVerdict(t, stale = false) {
+    if (stale || t.claims === 0 || t.confirmed !== t.claims)
+        return "unverified";
+    return t.attested > 0 ? "attested" : "verified";
+}
+/**
+ * The one notice `verify`, `list` and `status` all show: this record's scenario
+ * claims were confirmed without a run.
+ *
+ * It is a warning and it gates nothing — verify has never gated, and a service
+ * with no suite yet has to be able to ship. What it must never do is read the
+ * same as a green run.
+ */
+export function attestedNotice(claims, feature) {
+    const ids = attestedClaims(claims);
+    if (ids.length === 0)
+        return null;
+    return {
+        code: "verify.scenario-attested",
+        severity: "warn",
+        message: `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(", ")}. ` +
+            `Answer them mechanically once the suite runs: \`loam verify ${feature} --results <cucumber.json>\`.`,
+        claims: ids,
+    };
+}
+/**
+ * Where the record lives: inside the feature, so `archive` carries it into
+ * `features/archive/` with everything else and a reviewer finds it next to the
+ * delta it is about. YAML rather than frontmatter or JSON — it is data, it has
+ * to survive without loam, and one claim per block is a diff a person can read.
+ */
+export function verificationPath(featureDir) {
+    return join(featureDir, "verification.yaml");
+}
+export function buildVerification(checklist, answers, today, report) {
+    const byId = new Map(answers.map((a) => [a.id, a]));
+    const claims = checklist.claims.map((c) => {
+        // Callers hand in an answer per claim — `runnerAnswers` is total over the
+        // checklist, and both other callers map the checklist to build theirs. The
+        // branch is here because the alternative to a diagnosis is a `TypeError` on
+        // `a.verdict`, which cli.ts reports as `internal` with a stack about a
+        // property of `undefined` and no word about which claim went missing.
+        const a = byId.get(c.id);
+        if (a === undefined)
+            throw new Error(`buildVerification: no answer for claim ${c.id}`);
+        return {
+            id: c.id,
+            kind: c.kind,
+            claim: c.claim,
+            verdict: a.verdict,
+            answered_by: a.answered_by,
+            evidence: a.evidence,
+            ...(a.note === undefined ? {} : { note: a.note }),
+        };
+    });
+    const confirmed = claims.filter((c) => c.verdict === "confirmed").length;
+    return {
+        feature: checklist.feature,
+        recorded: today,
+        checklist: checklist.digest,
+        summary: { claims: claims.length, confirmed, unconfirmed: claims.length - confirmed },
+        claims,
+        ...(report === undefined ? {} : { report }),
+    };
+}
+/**
+ * Replace one service's contribution while retaining current contributions
+ * from other repositories. Claim ids removed from the live checklist are
+ * pruned from both the answers and their attestations, so a changed feature can
+ * never keep a green answer to a question it no longer asks.
+ */
+export function buildFederatedVerification(checklist, service, answers, previous, recorded, commit, report) {
+    const currentById = new Map(checklist.claims.map((claim) => [claim.id, claim]));
+    const localIds = new Set(checklist.claims.filter((claim) => claim.subject === service).map((claim) => claim.id));
+    // An old all-at-once record remains readable, but its answers have no commit
+    // attestation and therefore cannot silently become somebody else's
+    // federated contribution. The first schema-2 write starts a clean federation.
+    const previouslyAttested = new Set((previous?.attestations ?? []).flatMap((a) => a.claims));
+    const retained = (previous?.schema === 2 ? previous.claims : []).filter((claim) => {
+        const current = currentById.get(claim.id);
+        return current !== undefined && current.subject !== service && previouslyAttested.has(claim.id);
+    });
+    const local = answers.map((answer) => {
+        // Same contract as `buildVerification`: an answer is built from the live
+        // checklist, so it always names a current claim. Off-checklist answers do
+        // NOT belong here — `discarded` means "an answer the PREVIOUS record held",
+        // and routing an incoming stray into it would change what the printed
+        // notice tells an operator. A caller that reaches this gets told which
+        // answer it was rather than a `TypeError` on `claim.kind`.
+        const claim = currentById.get(answer.id);
+        if (claim === undefined) {
+            throw new Error(`buildFederatedVerification: answer ${answer.id} names no current claim`);
+        }
+        return {
+            id: claim.id,
+            kind: claim.kind,
+            subject: claim.subject,
+            claim: claim.claim,
+            verdict: answer.verdict,
+            answered_by: answer.answered_by,
+            evidence: answer.evidence,
+            ...(answer.note === undefined ? {} : { note: answer.note }),
+        };
+    });
+    const byId = new Map([...retained, ...local].map((claim) => [claim.id, claim]));
+    const claims = checklist.claims.flatMap((claim) => {
+        const answer = byId.get(claim.id);
+        if (answer === undefined)
+            return [];
+        // Normalize retained legacy entries to the current question text and add
+        // the subject schema 2 needs for future independent replacement.
+        return [{ ...answer, kind: claim.kind, subject: claim.subject, claim: claim.claim }];
+    });
+    const retainedAttestations = (previous?.attestations ?? []).flatMap((attestation) => {
+        if (attestation.service === service)
+            return [];
+        const ids = attestation.claims.filter((id) => currentById.get(id)?.subject === attestation.service && byId.has(id));
+        return ids.length === 0 ? [] : [{ ...attestation, claims: ids }];
+    });
+    const attestations = [
+        ...retainedAttestations,
+        {
+            service,
+            commit,
+            recorded,
+            claims: checklist.claims.filter((c) => localIds.has(c.id)).map((c) => c.id),
+            // Filed with the attestation, not the record: the report is one
+            // repository's run, and it is pruned or retained with that repository's
+            // answers rather than outliving them.
+            ...(report === undefined ? {} : { report }),
+        },
+    ].sort((a, b) => a.service.localeCompare(b.service));
+    const confirmed = claims.filter((claim) => claim.verdict === "confirmed").length;
+    const unconfirmed = claims.length - confirmed;
+    const unanswered = checklist.claims.length - claims.length;
+    // Everything the old record answered that the new one does not. The caller
+    // prints it; nothing here decides it is acceptable.
+    const discarded = (previous?.claims ?? [])
+        .filter((claim) => !byId.has(claim.id))
+        .map((claim) => ({
+        id: claim.id,
+        claim: claim.claim,
+        ...(claim.subject === undefined ? {} : { subject: claim.subject }),
+        reason: currentById.has(claim.id) ? "unattested" : "off-checklist",
+    }));
+    return {
+        verification: {
+            schema: 2,
+            feature: checklist.feature,
+            recorded,
+            checklist: checklist.digest,
+            summary: { claims: checklist.claims.length, confirmed, unconfirmed, unanswered },
+            claims,
+            attestations,
+        },
+        discarded,
+    };
+}
+/**
+ * The record as a file. The header explains what the reader is looking at,
+ * because the whole point is that this is legible to someone who has never run
+ * loam — including the part loam cannot vouch for.
+ */
+export function renderVerification(v) {
+    const header = [
+        `# Verification record for ${v.feature} — written by \`loam verify ${v.feature}\` (--results / --record).`,
+        "#",
+        "# Every claim below was derived mechanically from this feature's own artifacts:",
+        "# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/",
+        "# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a",
+        "# cucumber JSON report's digest-tagged scenarios answered it mechanically;",
+        "# `answered_by: agent` means somebody's word about the code, which loam did not",
+        "# check. Nothing gates on either.",
+        "#",
+        "# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam",
+        "# reports it as `verify.scenario-attested` and the feature does not count as",
+        "# verified until a report answers it. `report:` records the file a --results run",
+        "# read — its sha256 and mtime say WHICH file, not that it came from that commit;",
+        "# no digest can say that.",
+        "#",
+        "# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same",
+        "# one, the feature changed after this was recorded and these answers are stale.",
+        ...(v.schema === 2
+            ? [
+                "#",
+                "# Schema 2 is federated: each service entry under `attestations` binds its claim ids",
+                "# and file:line evidence to that repository's git commit. Missing claims are honestly",
+                "# unanswered; another service run may add them without rewriting existing attestations.",
+            ]
+            : []),
+        "",
+    ].join("\n");
+    // lineWidth 0: never fold a claim onto a second line — these are grepped and diffed.
+    return header + stringify(v, { lineWidth: 0 });
+}
+export async function readVerificationState(featureDir) {
+    const path = verificationPath(featureDir);
+    if (!existsSync(path))
+        return { state: "absent" };
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (err) {
+        return { state: "unreadable", reason: err instanceof Error ? err.message : String(err) };
+    }
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    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 };
+    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 = [];
+    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;
+    }
+    if (doc["schema"] !== undefined && doc["schema"] !== 2)
+        return null;
+    if (!isConsumedReport(doc["report"]))
+        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;
+        }
+    }
+    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"]));
+}
+/** A summary count: a finite number. YAML hands back strings for anything quoted. */
+function isCount(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+export async function writeVerification(featureDir, v) {
+    const path = verificationPath(featureDir);
+    await writeFile(path, renderVerification(v), "utf8");
+    return path;
+}
+//# sourceMappingURL=verify.js.map