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

package/dist/core/verify/build.js

@@ -0,0 +1,150 @@
+/**
+ * Checklist plus answers becomes a record — once for a feature answered all at
+ * once, once for a fleet answering service by service.
+ *
+ * The federated form is separate from `buildVerification` and not a flag on it
+ * because the two disagree about what an unanswered claim means: answering
+ * everything at once, a missing answer is a gap in this run, while a federated
+ * record is assembled from attestations that each covered one service and were
+ * never expected to cover the rest.
+ */
+import {} from "./checklist.js";
+import {} from "./answers.js";
+import {} from "./record.js";
+export function buildVerification(checklist, answers, today, reports = {}) {
+    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}`);
+        // Deliberately no `evidence_pins` here: the legacy all-at-once form binds
+        // to no commit, so there is no attested blob to pin — and none is ever
+        // handed in, because pins are computed inside the federated evidence
+        // validation this form never runs.
+        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,
+        ...(reports.results === undefined ? {} : { report: reports.results }),
+        ...(reports.contract === undefined ? {} : { contractReport: reports.contract }),
+    };
+}
+export function buildFederatedVerification(checklist, attestation, answers, previous) {
+    const { service, recorded, commit, reports, docsCommit } = attestation;
+    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 }),
+            // The pins the evidence validation stamped onto this repository's
+            // answers ride into the record here; retained other-service claims are
+            // spread whole below, so THEIR pins survive a re-record untouched.
+            ...(answer.evidence_pins === undefined ? {} : { evidence_pins: answer.evidence_pins }),
+        };
+    });
+    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),
+            // What THIS repository answered, and what it answered it against. Both
+            // ride with the attestation rather than the record for the reason the
+            // reports do: they are one repository's facts, pruned and retained with
+            // that repository's answers.
+            checklist: checklist.digest,
+            ...(docsCommit === undefined ? {} : { docsCommit }),
+            // Filed with the attestation, not the record: each report is one
+            // repository's run, and it is pruned or retained with that repository's
+            // answers rather than outliving them — the contract report under the
+            // same rule as the cucumber one.
+            ...(reports.results === undefined ? {} : { report: reports.results }),
+            ...(reports.contract === undefined ? {} : { contractReport: reports.contract }),
+        },
+    ].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,
+    };
+}
+//# sourceMappingURL=build.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/core/verify/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAkB,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAe,MAAM,cAAc,CAAC;AAC3C,OAAO,EAKN,MAAM,aAAa,CAAC;AAErB,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,OAAiB,EACjB,KAAa,EACb,OAAO,GAAoB,EAAE;IAE7B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,MAAM,GAAoB,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACzD,0EAA0E;QAC1E,2EAA2E;QAC3E,4EAA4E;QAC5E,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvF,0EAA0E;QAC1E,uEAAuE;QACvE,qEAAqE;QACrE,mCAAmC;QACnC,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC;IACzE,OAAO;QACL,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,QAAQ,EAAE,KAAK;QACf,SAAS,EAAE,SAAS,CAAC,MAAM;QAC3B,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,GAAG,SAAS,EAAE;QACrF,MAAM;QACN,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACrE,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC;AA8CD,MAAM,UAAU,0BAA0B,CACxC,SAAoB,EACpB,WAAwB,EACxB,OAAiB,EACjB,QAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,WAAW,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAEjH,6EAA6E;IAC7E,mEAAmE;IACnE,8EAA8E;IAC9E,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QAChF,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAiB,EAAE;QAClD,yEAAyE;QACzE,0EAA0E;QAC1E,4EAA4E;QAC5E,sEAAsE;QACtE,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,CAAC,EAAE,yBAAyB,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YAC3D,kEAAkE;YAClE,uEAAuE;YACvE,mEAAmE;YACnE,GAAG,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;SACvF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACpC,yEAAyE;QACzE,iEAAiE;QACjE,OAAO,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;IAEH,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,YAAY,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE;QAClF,IAAI,WAAW,CAAC,OAAO,KAAK,OAAO;YAAE,OAAO,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CACnC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,WAAW,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAC7E,CAAC;QACF,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IACH,MAAM,YAAY,GAAyB;QACzC,GAAG,oBAAoB;QACvB;YACE,OAAO;YACP,MAAM;YACN,QAAQ;YACR,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,uEAAuE;YACvE,sEAAsE;YACtE,wEAAwE;YACxE,6BAA6B;YAC7B,SAAS,EAAE,SAAS,CAAC,MAAM;YAC3B,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;YACnD,iEAAiE;YACjE,wEAAwE;YACxE,qEAAqE;YACrE,iCAAiC;YACjC,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACrE,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;SAChF;KACF,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAErD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,MAAM,CAAC;IACjF,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC;IAC9C,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAE3D,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;SACvC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,CAAC;QAChC,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,eAAe;KACnE,CAAC,CAAC,CAAC;IAEN,OAAO;QACL,YAAY,EAAE;YACZ,MAAM,EAAE,CAAC;YACT,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,QAAQ;YACR,SAAS,EAAE,SAAS,CAAC,MAAM;YAC3B,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE;YAChF,MAAM;YACN,YAAY;SACb;QACD,SAAS;KACV,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Checklist plus answers becomes a record — once for a feature answered all at\n * once, once for a fleet answering service by service.\n *\n * The federated form is separate from `buildVerification` and not a flag on it\n * because the two disagree about what an unanswered claim means: answering\n * everything at once, a missing answer is a gap in this run, while a federated\n * record is assembled from attestations that each covered one service and were\n * never expected to cover the rest.\n */\nimport { type Checklist } from \"./checklist.js\";\nimport { type Answer } from \"./answers.js\";\nimport {\n  type ConsumedReports,\n  type RecordedClaim,\n  type ServiceAttestation,\n  type Verification,\n} from \"./record.js\";\n\nexport function buildVerification(\n  checklist: Checklist,\n  answers: Answer[],\n  today: string,\n  reports: ConsumedReports = {},\n): Verification {\n  const byId = new Map(answers.map((a) => [a.id, a]));\n  const claims: RecordedClaim[] = checklist.claims.map((c) => {\n    // Callers hand in an answer per claim — `runnerAnswers` is total over the\n    // checklist, and both other callers map the checklist to build theirs. The\n    // branch is here because the alternative to a diagnosis is a `TypeError` on\n    // `a.verdict`, which cli.ts reports as `internal` with a stack about a\n    // property of `undefined` and no word about which claim went missing.\n    const a = byId.get(c.id);\n    if (a === undefined) throw new Error(`buildVerification: no answer for claim ${c.id}`);\n    // Deliberately no `evidence_pins` here: the legacy all-at-once form binds\n    // to no commit, so there is no attested blob to pin — and none is ever\n    // handed in, because pins are computed inside the federated evidence\n    // validation this form never runs.\n    return {\n      id: c.id,\n      kind: c.kind,\n      claim: c.claim,\n      verdict: a.verdict,\n      answered_by: a.answered_by,\n      evidence: a.evidence,\n      ...(a.note === undefined ? {} : { note: a.note }),\n    };\n  });\n  const confirmed = claims.filter((c) => c.verdict === \"confirmed\").length;\n  return {\n    feature: checklist.feature,\n    recorded: today,\n    checklist: checklist.digest,\n    summary: { claims: claims.length, confirmed, unconfirmed: claims.length - confirmed },\n    claims,\n    ...(reports.results === undefined ? {} : { report: reports.results }),\n    ...(reports.contract === undefined ? {} : { contractReport: reports.contract }),\n  };\n}\n\n/**\n * An answer the previous record held that the new one does not carry.\n *\n * Dropping these is correct — see `buildFederatedVerification` — but doing it\n * silently is not: a schema-1 record answers the WHOLE checklist, so the first\n * federated write turns a green record into a partial one, and an operator who\n * is not told which answers went missing reads the drop as loam losing data.\n */\nexport interface DiscardedAnswer {\n  id: string;\n  claim: string;\n  /** The service the record filed it under, when it said. Absent in schema-1 records. */\n  subject?: string;\n  /**\n   * `off-checklist` — the feature changed and nobody asks this question any\n   * more. `unattested` — the question still stands, but no service attestation\n   * binds the answer to a commit, so it cannot be carried into a federated\n   * record; the owning repository has to record it again.\n   */\n  reason: \"off-checklist\" | \"unattested\";\n}\n\nexport interface FederatedBuild {\n  verification: Verification;\n  /** In checklist-independent record order — see {@link DiscardedAnswer}. */\n  discarded: DiscardedAnswer[];\n}\n\n/**\n * Replace one service's contribution while retaining current contributions\n * from other repositories. Claim ids removed from the live checklist are\n * pruned from both the answers and their attestations, so a changed feature can\n * never keep a green answer to a question it no longer asks.\n */\n/** One service's attestation: whose word it is, when, and against which commit. */\nexport interface Attestation {\n  service: string;\n  recorded: string;\n  commit: string;\n  reports: ConsumedReports;\n  /** The docs-repo HEAD the checklist was derived from, when git could answer. */\n  docsCommit?: string;\n}\n\nexport function buildFederatedVerification(\n  checklist: Checklist,\n  attestation: Attestation,\n  answers: Answer[],\n  previous: Verification | null,\n): FederatedBuild {\n  const { service, recorded, commit, reports, docsCommit } = attestation;\n  const currentById = new Map(checklist.claims.map((claim) => [claim.id, claim]));\n  const localIds = new Set(checklist.claims.filter((claim) => claim.subject === service).map((claim) => claim.id));\n\n  // An old all-at-once record remains readable, but its answers have no commit\n  // attestation and therefore cannot silently become somebody else's\n  // federated contribution. The first schema-2 write starts a clean federation.\n  const previouslyAttested = new Set((previous?.attestations ?? []).flatMap((a) => a.claims));\n  const retained = (previous?.schema === 2 ? previous.claims : []).filter((claim) => {\n    const current = currentById.get(claim.id);\n    return current !== undefined && current.subject !== service && previouslyAttested.has(claim.id);\n  });\n  const local = answers.map((answer): RecordedClaim => {\n    // Same contract as `buildVerification`: an answer is built from the live\n    // checklist, so it always names a current claim. Off-checklist answers do\n    // NOT belong here — `discarded` means \"an answer the PREVIOUS record held\",\n    // and routing an incoming stray into it would change what the printed\n    // notice tells an operator. A caller that reaches this gets told which\n    // answer it was rather than a `TypeError` on `claim.kind`.\n    const claim = currentById.get(answer.id);\n    if (claim === undefined) {\n      throw new Error(`buildFederatedVerification: answer ${answer.id} names no current claim`);\n    }\n    return {\n      id: claim.id,\n      kind: claim.kind,\n      subject: claim.subject,\n      claim: claim.claim,\n      verdict: answer.verdict,\n      answered_by: answer.answered_by,\n      evidence: answer.evidence,\n      ...(answer.note === undefined ? {} : { note: answer.note }),\n      // The pins the evidence validation stamped onto this repository's\n      // answers ride into the record here; retained other-service claims are\n      // spread whole below, so THEIR pins survive a re-record untouched.\n      ...(answer.evidence_pins === undefined ? {} : { evidence_pins: answer.evidence_pins }),\n    };\n  });\n  const byId = new Map([...retained, ...local].map((claim) => [claim.id, claim]));\n  const claims = checklist.claims.flatMap((claim) => {\n    const answer = byId.get(claim.id);\n    if (answer === undefined) return [];\n    // Normalize retained legacy entries to the current question text and add\n    // the subject schema 2 needs for future independent replacement.\n    return [{ ...answer, kind: claim.kind, subject: claim.subject, claim: claim.claim }];\n  });\n\n  const retainedAttestations = (previous?.attestations ?? []).flatMap((attestation) => {\n    if (attestation.service === service) return [];\n    const ids = attestation.claims.filter(\n      (id) => currentById.get(id)?.subject === attestation.service && byId.has(id),\n    );\n    return ids.length === 0 ? [] : [{ ...attestation, claims: ids }];\n  });\n  const attestations: ServiceAttestation[] = [\n    ...retainedAttestations,\n    {\n      service,\n      commit,\n      recorded,\n      claims: checklist.claims.filter((c) => localIds.has(c.id)).map((c) => c.id),\n      // What THIS repository answered, and what it answered it against. Both\n      // ride with the attestation rather than the record for the reason the\n      // reports do: they are one repository's facts, pruned and retained with\n      // that repository's answers.\n      checklist: checklist.digest,\n      ...(docsCommit === undefined ? {} : { docsCommit }),\n      // Filed with the attestation, not the record: each report is one\n      // repository's run, and it is pruned or retained with that repository's\n      // answers rather than outliving them — the contract report under the\n      // same rule as the cucumber one.\n      ...(reports.results === undefined ? {} : { report: reports.results }),\n      ...(reports.contract === undefined ? {} : { contractReport: reports.contract }),\n    },\n  ].sort((a, b) => a.service.localeCompare(b.service));\n\n  const confirmed = claims.filter((claim) => claim.verdict === \"confirmed\").length;\n  const unconfirmed = claims.length - confirmed;\n  const unanswered = checklist.claims.length - claims.length;\n\n  // Everything the old record answered that the new one does not. The caller\n  // prints it; nothing here decides it is acceptable.\n  const discarded = (previous?.claims ?? [])\n    .filter((claim) => !byId.has(claim.id))\n    .map((claim): DiscardedAnswer => ({\n      id: claim.id,\n      claim: claim.claim,\n      ...(claim.subject === undefined ? {} : { subject: claim.subject }),\n      reason: currentById.has(claim.id) ? \"unattested\" : \"off-checklist\",\n    }));\n\n  return {\n    verification: {\n      schema: 2,\n      feature: checklist.feature,\n      recorded,\n      checklist: checklist.digest,\n      summary: { claims: checklist.claims.length, confirmed, unconfirmed, unanswered },\n      claims,\n      attestations,\n    },\n    discarded,\n  };\n}\n"]}

package/dist/core/verify/checklist.js

@@ -0,0 +1,201 @@
+/**
+ * The questions: what a feature's own artifacts promised, derived mechanically.
+ *
+ * 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, and it
+ * is this module: a feature says this service will exist, it will expose this
+ * operation, that service will call it, this scenario will have a test. The
+ * list comes from the same files `validate` already reads.
+ *
+ * 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.
+ *
+ * `scenarioBodyHash` lives in `core/gherkin/digest.ts` — one recipe shared
+ * with `core/gherkin/stamp.ts`, which stamps the same digest as a tag on every
+ * generated scenario so `--results` can match a cucumber report back to a
+ * claim. A second spelling of the hash would silently stop every scenario
+ * claim from being answerable by a run.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { readAsyncapi } from "../asyncapi/read.js";
+import {} from "../c4/likec4.js";
+import { elementService, serviceResolver } from "../c4/resolve/service.js";
+import { ACTOR_KINDS } from "../vocabulary/maturity.js";
+import { operationIds, operations } from "../openapi/doc.js";
+import { featurePaths, featureSpecPaths } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { featureSpecServices } from "../repo/repo.js";
+import { enumeratedServiceIds } from "../repo/service-target.js";
+import { FleetContext } from "../fleet-context.js";
+import { parseRequirements } from "../document/parse.js";
+import { scenarioBodyHash } from "../gherkin/digest.js";
+// The kind vocabulary and both hash recipes live in ./claims/identity.ts —
+// one module for everything that decides whether two runs ask the same
+// question, and this one for how the questions are derived.
+import { checklistDigest, claimId, DIGEST_LENGTH, ID_LENGTH, } from "./claims/identity.js";
+/**
+ * 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, fleet) {
+    // The per-service loop below resolves living contracts through the
+    // enumeration twice per service; without a shared context each of those is
+    // a full fleet walk, so deriving one checklist cost O(services²) reads. A
+    // caller-supplied context is used when given; otherwise one is created for
+    // this derivation alone — the loop still pays a single walk either way.
+    const ctx = fleet ?? new FleetContext();
+    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 declares = [];
+    const calls = [];
+    const scenarios = [];
+    const specServices = await featureSpecServices(featureDir, ctx);
+    // Architecture — what the delta promised the fleet would look like. Loaded
+    // through the context rather than a bare parse, so a caller that derives
+    // several checklists in one invocation (`loam gate`'s verification check,
+    // the fleet forms) shares one parse per delta — and a batch prefetch
+    // (`FleetContext.prefetchLikeC4`) genuinely seeds this load.
+    const deltaPath = featurePaths(featureDir).delta;
+    if (existsSync(deltaPath)) {
+        const res = await ctx.loadLikeC4(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`));
+            }
+            // The enumerated fleet — `services/` plus this feature's own `specs/`
+            // directories, the only place a service the feature INTRODUCES has a
+            // directory at all — rides into the resolver so a claim about an edge
+            // drawn into a modelled container names the service that owns it. A
+            // claim against a service called "api" that has never existed is one no
+            // evidence in any repository could ever answer, and the fleet half alone
+            // still derived exactly that claim for an introduced service's own
+            // container. Unenumerable services/ degrades to the feature's names.
+            const svcOf = serviceResolver(elements, new Set([...(await enumeratedServiceIds(docsDir, ctx)), ...specServices]));
+            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 = svcOf(r.source);
+                const to = svcOf(r.target);
+                calls.push({
+                    ...claim("c4.calls", from, [from, to, r.op], `${from} calls '${r.op}' on ${to}`),
+                    // The same string as the provider's api.exposes token, scanned in the
+                    // CALLER's cited file — a call site plausibly spells the operationId.
+                    token: r.op,
+                });
+            }
+        }
+    }
+    for (const svc of specServices) {
+        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((await locateServicePaths(docsDir, svc, ctx)).openapi));
+            for (const op of featOps) {
+                if (living.has(op))
+                    continue;
+                exposes.push({
+                    ...claim("api.exposes", svc, [svc, op], `${svc} exposes operationId '${op}'`),
+                    operation: op,
+                    token: op,
+                });
+            }
+        }
+        // Events — the same NEW-only discipline on the async axis: a delta's
+        // asyncapi.yaml is a complete document too, so what the living contract
+        // already sends or receives is restatement, not a promise. Removals are
+        // not questions either — the reader already keeps marked declarations out
+        // of the sent/received sets — and an unreadable delta promises nothing
+        // checkable, exactly like the broken C4 delta above.
+        const events = await readAsyncapi(paths.asyncapi);
+        if (events.sent.length > 0 || events.received.length > 0) {
+            const living = await readAsyncapi((await locateServicePaths(docsDir, svc, ctx)).asyncapi);
+            const directions = [
+                { direction: "sends", feat: events.sent, known: new Set(living.sent) },
+                { direction: "receives", feat: events.received, known: new Set(living.received) },
+            ];
+            for (const d of directions) {
+                for (const name of d.feat) {
+                    if (d.known.has(name))
+                        continue;
+                    declares.push({
+                        ...claim("event.declares", svc, [svc, d.direction, name], `${svc} declares it ${d.direction} message '${name}'`),
+                        token: name,
+                    });
+                }
+            }
+        }
+        // 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, ...declares, ...calls, ...scenarios];
+    return { feature: featureId, claims, digest: checklistDigest(claims.map((c) => c.id)) };
+}
+//# sourceMappingURL=checklist.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checklist.js","sourceRoot":"","sources":["../../../src/core/verify/checklist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,2EAA2E;AAC3E,uEAAuE;AACvE,4DAA4D;AAC5D,OAAO,EACL,eAAe,EACf,OAAO,EACP,aAAa,EACb,SAAS,GAEV,MAAM,sBAAsB,CAAC;AA4C9B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,UAAsB,EACtB,SAAiB,EACjB,KAAoB;IAEpB,mEAAmE;IACnE,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,wEAAwE;IACxE,MAAM,GAAG,GAAG,KAAK,IAAI,IAAI,YAAY,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,IAAe,EAAE,OAAe,EAAE,KAAe,EAAE,IAAY,EAAS,EAAE,CAAC,CAAC;QACzF,EAAE,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC;QACzC,IAAI;QACJ,OAAO;QACP,KAAK,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAY,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAY,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAY,EAAE,CAAC;IAC1B,MAAM,SAAS,GAAY,EAAE,CAAC;IAE9B,MAAM,YAAY,GAAG,MAAM,mBAAmB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAEhE,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACrE,6DAA6D;IAC7D,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC;IACjD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC5C,0EAA0E;QAC1E,8EAA8E;QAC9E,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAW,GAAG,CAAC,QAAQ,CAAC;YACtC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;oBAAE,SAAS;gBAC1C,wEAAwE;gBACxE,sDAAsD;gBACtD,IAAI,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;oBAAE,SAAS;gBAC1E,MAAM,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC,CAAC,CAAC;YAC9E,CAAC;YACD,sEAAsE;YACtE,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,wEAAwE;YACxE,yEAAyE;YACzE,mEAAmE;YACnE,qEAAqE;YACrE,MAAM,KAAK,GAAG,eAAe,CAC3B,QAAQ,EACR,IAAI,GAAG,CAAS,CAAC,GAAG,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,YAAY,CAAC,CAAC,CAClF,CAAC;YACF,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;gBAClC,wEAAwE;gBACxE,yDAAyD;gBACzD,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS;oBAAE,SAAS;gBAChE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC;oBACT,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC;oBAChF,sEAAsE;oBACtE,sEAAsE;oBACtE,KAAK,EAAE,CAAC,CAAC,EAAE;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,gBAAgB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QAEhD,2EAA2E;QAC3E,6EAA6E;QAC7E,0DAA0D;QAC1D,MAAM,OAAO,GAAG,CAAC,MAAM,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;aAC9C,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC;aACxC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC,CAAC,MAAM,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;YAClG,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;gBACzB,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;oBAAE,SAAS;gBAC7B,OAAO,CAAC,IAAI,CAAC;oBACX,GAAG,KAAK,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,yBAAyB,EAAE,GAAG,CAAC;oBAC7E,SAAS,EAAE,EAAE;oBACb,KAAK,EAAE,EAAE;iBACV,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,qEAAqE;QACrE,wEAAwE;QACxE,wEAAwE;QACxE,0EAA0E;QAC1E,uEAAuE;QACvE,qDAAqD;QACrD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,CAAC,MAAM,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAC1F,MAAM,UAAU,GAAG;gBACjB,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;gBACtE,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE;aACzE,CAAC;YACX,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;gBAC3B,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;oBAC1B,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;wBAAE,SAAS;oBAChC,QAAQ,CAAC,IAAI,CAAC;wBACZ,GAAG,KAAK,CACN,gBAAgB,EAChB,GAAG,EACH,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,EACxB,GAAG,GAAG,gBAAgB,CAAC,CAAC,SAAS,aAAa,IAAI,GAAG,CACtD;wBACD,KAAK,EAAE,IAAI;qBACZ,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,6EAA6E;QAC7E,6EAA6E;QAC7E,8DAA8D;QAC9D,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;gBACtE,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;oBAAE,SAAS;gBACxD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC5B,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;oBAC5C,SAAS,CAAC,IAAI,CAAC;wBACb,GAAG,KAAK,CACN,iBAAiB,EACjB,GAAG,EACH,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,EACvD,aAAa,CAAC,CAAC,IAAI,qBAAqB,CAAC,CAAC,IAAI,MAAM,GAAG,wBAAwB,CAChF;wBACD,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC;qBACrC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,4EAA4E;QAC5E,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,mEAAmE;QACnE,2EAA2E;QAC3E,sBAAsB;QACtB,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;gBAC1E,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;oBAAE,SAAS;gBACxD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC5B,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;oBACpD,SAAS,CAAC,IAAI,CAAC;wBACb,GAAG,KAAK,CACN,iBAAiB,EACjB,GAAG,EACH,CAAC,GAAG,EAAE,cAAc,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,EACvE,aAAa,CAAC,CAAC,IAAI,0BAA0B,CAAC,CAAC,IAAI,MAAM,GAAG,sCAAsC,CACnG;wBACD,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC;qBACrC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,GAAG,QAAQ,EAAE,GAAG,KAAK,EAAE,GAAG,SAAS,CAAC,CAAC;IAC5E,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AAC1F,CAAC","sourcesContent":["/**\n * The questions: what a feature's own artifacts promised, derived mechanically.\n *\n * The original plan was to extract C4 from the built code and diff it against\n * the delta. There is no such extractor and there will not be one — nothing\n * deterministic reads a service and says what its architecture MEANS, and two\n * generated models of the same code disagree in wording every run, so the diff\n * would flap and be switched off inside a week.\n *\n * What survives of the idea is the part that was always deterministic, and it\n * is this module: a feature says this service will exist, it will expose this\n * operation, that service will call it, this scenario will have a test. The\n * list comes from the same files `validate` already reads.\n *\n * The claim ids are a function of the claim and of nothing else — so two runs\n * are diffable, reordering the delta renames nothing, and rewording a scenario\n * DOES rename its claim, because an answer about text nobody wrote must not\n * carry over.\n *\n * `scenarioBodyHash` lives in `core/gherkin/digest.ts` — one recipe shared\n * with `core/gherkin/stamp.ts`, which stamps the same digest as a tag on every\n * generated scenario so `--results` can match a cucumber report back to a\n * claim. A second spelling of the hash would silently stop every scenario\n * claim from being answerable by a run.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { readAsyncapi } from \"../asyncapi/read.js\";\nimport { type Elem } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { ACTOR_KINDS } from \"../vocabulary/maturity.js\";\nimport { operationIds, operations } from \"../openapi/doc.js\";\nimport { featurePaths, featureSpecPaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { featureSpecServices } from \"../repo/repo.js\";\nimport { enumeratedServiceIds } from \"../repo/service-target.js\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { parseRequirements } from \"../document/parse.js\";\nimport { scenarioBodyHash } from \"../gherkin/digest.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\n// The kind vocabulary and both hash recipes live in ./claims/identity.ts —\n// one module for everything that decides whether two runs ask the same\n// question, and this one for how the questions are derived.\nimport {\n  checklistDigest,\n  claimId,\n  DIGEST_LENGTH,\n  ID_LENGTH,\n  type ClaimKind,\n} from \"./claims/identity.js\";\n\nexport interface Claim {\n  /** `<kind>-<8 hex>` — stable for the life of the claim. See `claimId`. */\n  id: string;\n  kind: ClaimKind;\n  /** The service whose code answers this. A caller's claim is filed under the caller. */\n  subject: string;\n  /** The claim in one line, answerable without reading the feature's files. */\n  claim: string;\n  /**\n   * `scenario.tested` only: the first {@link DIGEST_LENGTH} hex of the\n   * scenario's body hash — the exact digest `loam gherkin` stamps as\n   * `@loam-digest-…`, which is what a cucumber report scenario carries and\n   * what `--results` matches on. Absent on every other kind.\n   */\n  digest?: string;\n  /**\n   * `api.exposes` only: the operationId the claim asserts, structurally — the\n   * join key `--contract-results` matches a contract report's entries on,\n   * exactly as `digest` is `--results`'s. Never parsed back out of the claim\n   * text, which is prose and may be reworded. Absent on every other kind.\n   */\n  operation?: string;\n  /**\n   * The literal string the claim asserts of the cited artifact — the\n   * operationId for `api.exposes`, the message name for `event.declares`, the\n   * edge's op for `c4.calls` — carried structurally so evidence pins\n   * (`./pins/pin.ts`) can stamp it at record time and the read side never\n   * parses it back out of claim prose. A separate field from `operation` on\n   * purpose: `contestedOperations` filters on `operation !== undefined` and\n   * must not start seeing `c4.calls` claims. Absent where a claim asserts no\n   * literal (`service.exists`, `scenario.tested`).\n   */\n  token?: string;\n}\n\nexport interface Checklist {\n  feature: string;\n  claims: Claim[];\n  /** A digest of the claim id SET — what says a record still answers this feature. */\n  digest: string;\n}\n\n/**\n * Derive the checklist from a feature's own artifacts. No code is read here and\n * none should be: the whole design rests on the questions being computed from\n * documents that do not change between runs.\n */\nexport async function featureChecklist(\n  docsDir: DocsDir,\n  featureDir: FeatureDir,\n  featureId: string,\n  fleet?: FleetContext,\n): Promise<Checklist> {\n  // The per-service loop below resolves living contracts through the\n  // enumeration twice per service; without a shared context each of those is\n  // a full fleet walk, so deriving one checklist cost O(services²) reads. A\n  // caller-supplied context is used when given; otherwise one is created for\n  // this derivation alone — the loop still pays a single walk either way.\n  const ctx = fleet ?? new FleetContext();\n  const seen = new Map<string, number>();\n  const claim = (kind: ClaimKind, subject: string, parts: string[], text: string): Claim => ({\n    id: claimId(featureId, kind, parts, seen),\n    kind,\n    subject,\n    claim: text,\n  });\n\n  const exists: Claim[] = [];\n  const exposes: Claim[] = [];\n  const declares: Claim[] = [];\n  const calls: Claim[] = [];\n  const scenarios: Claim[] = [];\n\n  const specServices = await featureSpecServices(featureDir, ctx);\n\n  // Architecture — what the delta promised the fleet would look like. Loaded\n  // through the context rather than a bare parse, so a caller that derives\n  // several checklists in one invocation (`loam gate`'s verification check,\n  // the fleet forms) shares one parse per delta — and a batch prefetch\n  // (`FleetContext.prefetchLikeC4`) genuinely seeds this load.\n  const deltaPath = featurePaths(featureDir).delta;\n  if (existsSync(deltaPath)) {\n    const res = await ctx.loadLikeC4(deltaPath);\n    // A delta nobody can parse promises nothing checkable. `validate` already\n    // reports it; inventing claims out of a broken document would only add noise.\n    if (res.errors.length === 0) {\n      const elements: Elem[] = res.elements;\n      for (const e of elements) {\n        if (!e.tags.includes(featureId)) continue;\n        // A dotted id is a container INSIDE a service, and an actor is nobody's\n        // repository. Neither is a service that has to exist.\n        if (e.id.includes(\".\") || ACTOR_KINDS.has(e.kind.toLowerCase())) continue;\n        const svc = elementService(e);\n        exists.push(claim(\"service.exists\", svc, [svc], `service '${svc}' exists`));\n      }\n      // The enumerated fleet — `services/` plus this feature's own `specs/`\n      // directories, the only place a service the feature INTRODUCES has a\n      // directory at all — rides into the resolver so a claim about an edge\n      // drawn into a modelled container names the service that owns it. A\n      // claim against a service called \"api\" that has never existed is one no\n      // evidence in any repository could ever answer, and the fleet half alone\n      // still derived exactly that claim for an introduced service's own\n      // container. Unenumerable services/ degrades to the feature's names.\n      const svcOf = serviceResolver(\n        elements,\n        new Set<string>([...(await enumeratedServiceIds(docsDir, ctx)), ...specServices]),\n      );\n      for (const r of res.relationships) {\n        // Untagged edges are context for the diagram; an edge with no operation\n        // names nothing specific enough to look for in the code.\n        if (!r.tags.includes(featureId) || r.op === undefined) continue;\n        const from = svcOf(r.source);\n        const to = svcOf(r.target);\n        calls.push({\n          ...claim(\"c4.calls\", from, [from, to, r.op], `${from} calls '${r.op}' on ${to}`),\n          // The same string as the provider's api.exposes token, scanned in the\n          // CALLER's cited file — a call site plausibly spells the operationId.\n          token: r.op,\n        });\n      }\n    }\n  }\n\n  for (const svc of specServices) {\n    const paths = featureSpecPaths(featureDir, svc);\n\n    // Contract — only what is NEW. A delta's openapi.yaml is a whole document,\n    // not a patch, so authors restate the living API inside it; asking whether a\n    // service still exposes what it already exposed is noise.\n    const featOps = (await operations(paths.openapi))\n      .filter((operation) => !operation.remove)\n      .map((operation) => operation.id);\n    if (featOps.length > 0) {\n      const living = new Set(await operationIds((await locateServicePaths(docsDir, svc, ctx)).openapi));\n      for (const op of featOps) {\n        if (living.has(op)) continue;\n        exposes.push({\n          ...claim(\"api.exposes\", svc, [svc, op], `${svc} exposes operationId '${op}'`),\n          operation: op,\n          token: op,\n        });\n      }\n    }\n\n    // Events — the same NEW-only discipline on the async axis: a delta's\n    // asyncapi.yaml is a complete document too, so what the living contract\n    // already sends or receives is restatement, not a promise. Removals are\n    // not questions either — the reader already keeps marked declarations out\n    // of the sent/received sets — and an unreadable delta promises nothing\n    // checkable, exactly like the broken C4 delta above.\n    const events = await readAsyncapi(paths.asyncapi);\n    if (events.sent.length > 0 || events.received.length > 0) {\n      const living = await readAsyncapi((await locateServicePaths(docsDir, svc, ctx)).asyncapi);\n      const directions = [\n        { direction: \"sends\", feat: events.sent, known: new Set(living.sent) },\n        { direction: \"receives\", feat: events.received, known: new Set(living.received) },\n      ] as const;\n      for (const d of directions) {\n        for (const name of d.feat) {\n          if (d.known.has(name)) continue;\n          declares.push({\n            ...claim(\n              \"event.declares\",\n              svc,\n              [svc, d.direction, name],\n              `${svc} declares it ${d.direction} message '${name}'`,\n            ),\n            token: name,\n          });\n        }\n      }\n    }\n\n    // Behaviour — the scenarios of the requirements this feature CHANGES. A BASE\n    // requirement is the living state quoted inside the delta, and a REMOVED one\n    // is being retired: neither is work anybody has to have done.\n    if (existsSync(paths.spec)) {\n      for (const r of parseRequirements(await readFile(paths.spec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines);\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of requirement '${r.name}' (${svc}) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n          });\n        }\n      }\n    }\n\n    // The architecture spec axis, same walk: an arch scenario is a promise like\n    // any other — the outbox test nobody was going to write IS the point of the\n    // axis. The source file rides in the id tuple AND in the body hash itself\n    // (two axes are two namespaces: identically-worded scenarios must stay two\n    // questions, and the axis-salted digest is what keeps a business-only test\n    // run from answering the arch claim) and in the claim text, so the\n    // answering agent knows it is being asked for an integration/ops test, not\n    // an acceptance test.\n    if (existsSync(paths.archSpec)) {\n      for (const r of parseRequirements(await readFile(paths.archSpec, \"utf8\"))) {\n        if (r.kind === \"BASE\" || r.kind === \"REMOVED\") continue;\n        for (const s of r.scenarios) {\n          const body = scenarioBodyHash(svc, s.lines, \"arch\");\n          scenarios.push({\n            ...claim(\n              \"scenario.tested\",\n              svc,\n              [svc, \"arch.spec.md\", r.id ?? r.name, s.name, body.slice(0, ID_LENGTH)],\n              `scenario '${s.name}' of arch requirement '${r.name}' (${svc}, arch.spec.md) is covered by a test`,\n            ),\n            digest: body.slice(0, DIGEST_LENGTH),\n          });\n        }\n      }\n    }\n  }\n\n  const claims = [...exists, ...exposes, ...declares, ...calls, ...scenarios];\n  return { feature: featureId, claims, digest: checklistDigest(claims.map((c) => c.id)) };\n}\n"]}

package/dist/core/verify/claims/identity.js

@@ -0,0 +1,61 @@
+/**
+ * What a claim is about, and what makes it the same claim next run: the kind
+ * vocabulary and the two hash recipes. Moved out of `../checklist.ts` when the
+ * `operation` join key pushed the derivation module over the line limit — the
+ * seam was already in that file's own header, which discusses what a claim's
+ * id is a function of apart from how the questions are derived. The kinds live
+ * beside the id recipe rather than beside the derivation because the id STARTS
+ * with the kind: the two are one identity, and a diff to this module is a diff
+ * to every record in the fleet, which is exactly why it holds nothing else.
+ */
+import { createHash } from "node:crypto";
+/**
+ * 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, it declares its messages, the calls into it are wired, the
+ * behaviour is tested.
+ */
+export const CLAIM_KINDS = ["service.exists", "api.exposes", "event.declares", "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.
+ */
+export const ID_LENGTH = 8;
+export const DIGEST_LENGTH = 16;
+/**
+ * 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.
+ */
+export 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)}`;
+}
+/**
+ * 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.
+ * Takes the ids rather than the claims so this module never has to import the
+ * `Claim` shape the derivation declares — the recipe is over ids and nothing
+ * else, and the signature now says so.
+ */
+export function checklistDigest(ids) {
+    const sorted = [...ids].sort();
+    return createHash("sha256").update(sorted.join("\n")).digest("hex").slice(0, DIGEST_LENGTH);
+}
+//# sourceMappingURL=identity.js.map

package/dist/core/verify/claims/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../../src/core/verify/claims/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,gBAAgB,EAAE,aAAa,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,CAAU,CAAC;AAGvH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAC3B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO,CACrB,SAAiB,EACjB,IAAe,EACf,KAAe,EACf,IAAyB;IAEzB,uEAAuE;IACvE,4EAA4E;IAC5E,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnB,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,UAAU,CAAC,EAAE,CAAC;IAC1D,OAAO,GAAG,IAAI,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAsB;IACpD,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AAC9F,CAAC","sourcesContent":["/**\n * What a claim is about, and what makes it the same claim next run: the kind\n * vocabulary and the two hash recipes. Moved out of `../checklist.ts` when the\n * `operation` join key pushed the derivation module over the line limit — the\n * seam was already in that file's own header, which discusses what a claim's\n * id is a function of apart from how the questions are derived. The kinds live\n * beside the id recipe rather than beside the derivation because the id STARTS\n * with the kind: the two are one identity, and a diff to this module is a diff\n * to every record in the fleet, which is exactly why it holds nothing else.\n */\nimport { createHash } from \"node:crypto\";\n\n/**\n * What a claim is about. The order is the order the checklist comes back in,\n * and it reads as the story of the feature: the service exists, it exposes its\n * operations, it declares its messages, the calls into it are wired, the\n * behaviour is tested.\n */\nexport const CLAIM_KINDS = [\"service.exists\", \"api.exposes\", \"event.declares\", \"c4.calls\", \"scenario.tested\"] as const;\nexport type ClaimKind = (typeof CLAIM_KINDS)[number];\n\n/**\n * How much of the sha256 goes into an id, and into a digest — the checklist's,\n * and a scenario claim's runner-matching one, which is deliberately the same\n * 16 hex `loam gherkin` stamps (its GHERKIN_DIGEST_LENGTH): the tag in a\n * cucumber report and the digest on a claim must be the same string.\n */\nexport const ID_LENGTH = 8;\nexport const DIGEST_LENGTH = 16;\n\n/**\n * A claim's identity: a hash of what it says, and nothing about how it was\n * produced.\n *\n * The feature id is part of it so an answers file for one feature can never\n * validate against another. Two claims that really are identical (the same\n * scenario name twice under one requirement) are distinguished by occurrence, in\n * document order — they are still two questions, and answering one must not\n * answer the other.\n *\n * The hash is short because the claim text sits next to it everywhere it is\n * shown; it identifies a question, it does not authenticate one.\n */\nexport function claimId(\n  featureId: string,\n  kind: ClaimKind,\n  parts: string[],\n  seen: Map<string, number>,\n): string {\n  // NUL-joined so no claim's own text can spell another claim's tuple by\n  // containing the separator: ['a b','c'] and ['a','b c'] stay two questions.\n  const tuple = [featureId, kind, ...parts].join(\"\\u0000\");\n  const n = (seen.get(tuple) ?? 0) + 1;\n  seen.set(tuple, n);\n  const canonical = n === 1 ? tuple : `${tuple}\\u0000#${n}`;\n  return `${kind}-${createHash(\"sha256\").update(canonical).digest(\"hex\").slice(0, ID_LENGTH)}`;\n}\n\n/**\n * A digest of the claim id SET — sorted, so reordering the artifacts does not\n * make a record look stale. It changes when a claim is added, removed or\n * reworded, which is exactly when an answer set stops describing the feature.\n * Takes the ids rather than the claims so this module never has to import the\n * `Claim` shape the derivation declares — the recipe is over ids and nothing\n * else, and the signature now says so.\n */\nexport function checklistDigest(ids: readonly string[]): string {\n  const sorted = [...ids].sort();\n  return createHash(\"sha256\").update(sorted.join(\"\\n\")).digest(\"hex\").slice(0, DIGEST_LENGTH);\n}\n"]}

package/dist/core/verify/cross/diff.js

@@ -0,0 +1,97 @@
+/**
+ * The FILE a piece of evidence cites: one trailing `:<line>` or
+ * `:<line>-<line>` suffix stripped, nothing else judged. Mechanical string
+ * surgery on purpose — evidence is prose the answerer wrote, and any deeper
+ * reading (resolving against a tree, normalizing separators) would turn the
+ * disjointness signal into an opinion about paths instead of a fact about
+ * citations.
+ */
+function citedFile(evidence) {
+    return evidence.replace(/:\d+(-\d+)?$/, "");
+}
+function side(answer) {
+    return {
+        verdict: answer.verdict,
+        evidence: answer.evidence,
+        ...(answer.note === undefined ? {} : { note: answer.note }),
+    };
+}
+function crossRow(claim, a, b) {
+    const base = {
+        id: claim.id,
+        kind: claim.kind,
+        subject: claim.subject,
+        claim: claim.claim,
+        a: side(a),
+        b: side(b),
+    };
+    if (a.verdict !== b.verdict)
+        return { ...base, code: "cross.disagree" };
+    if (a.verdict === "confirmed") {
+        // Both confirmed, so both cite at least one entry (`checkAnswers` refuses
+        // an evidenced-nothing confirmation) — disjoint therefore means "looked in
+        // different places and agreed anyway", never "nobody cited anything".
+        const files = new Set(a.evidence.map(citedFile));
+        const disjoint = !b.evidence.some((entry) => files.has(citedFile(entry)));
+        return { ...base, code: "cross.agree-confirmed", ...(disjoint ? { evidenceDisjoint: true } : {}) };
+    }
+    return { ...base, code: "cross.agree-unconfirmed" };
+}
+/**
+ * Join two validated answer sets over the claims they both answered.
+ *
+ * Both sets must have come out of `checkAnswers` over THIS `claims` array,
+ * which refuses any set that does not answer every claim exactly once — so
+ * there is deliberately no missing-answer branch in the result shape. The
+ * guard below still fails closed on a caller that skipped validation: a
+ * silent skip would report "no disagreement" about a claim nobody compared,
+ * which is the one lie this module exists to prevent.
+ */
+export function crossExamine(claims, a, b) {
+    const byIdA = new Map(a.map((answer) => [answer.id, answer]));
+    const byIdB = new Map(b.map((answer) => [answer.id, answer]));
+    const rows = claims.map((claim) => {
+        const answerA = byIdA.get(claim.id);
+        const answerB = byIdB.get(claim.id);
+        if (answerA === undefined || answerB === undefined) {
+            throw new Error(`crossExamine: claim ${claim.id} has no answer in the ${answerA === undefined ? "first" : "second"} set — ` +
+                "validate both sets with checkAnswers over the same claims before joining them");
+        }
+        return crossRow(claim, answerA, answerB);
+    });
+    const of = (code) => rows.filter((row) => row.code === code).length;
+    const disagreements = rows.filter((row) => row.code === "cross.disagree");
+    return {
+        rows,
+        summary: {
+            claims: rows.length,
+            agreeConfirmed: of("cross.agree-confirmed"),
+            agreeUnconfirmed: of("cross.agree-unconfirmed"),
+            disagree: disagreements.length,
+            evidenceDisjoint: rows.filter((row) => row.code === "cross.agree-confirmed" && row.evidenceDisjoint === true)
+                .length,
+        },
+        disagreements,
+    };
+}
+/**
+ * The one notice this lens raises: agreements whose cited file sets share no
+ * path. Second in the reading order after the disagreements, because it is
+ * the shape correlated agreement takes when both agents guessed — each found
+ * something plausible somewhere, and nothing says they found the same thing.
+ */
+export function disjointNotice(rows) {
+    const ids = rows
+        .filter((row) => row.code === "cross.agree-confirmed" && row.evidenceDisjoint === true)
+        .map((row) => row.id);
+    if (ids.length === 0)
+        return null;
+    return {
+        code: "cross.evidence-disjoint",
+        severity: "warn",
+        message: `${ids.length} agreed-confirmed claim(s) cite non-overlapping files: ${ids.join(", ")}. ` +
+            "Two agents agreeing from different evidence is the second thing to read, after the disagreements.",
+        claims: ids,
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/core/verify/cross/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../../src/core/verify/cross/diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Mechanical cross-examination of two blind answer sets over one checklist.\n *\n * The doctrine lives here because every surface reads it from this module:\n * agreement is a review-ranking signal, never a verdict. The two sets almost\n * always come from two contexts of the same model, so their agreeing is\n * correlated evidence — which is why this module deliberately imports nothing\n * from `../record.ts`'s verdict machinery (`verificationVerdict`,\n * `tallyRecord`): a cross-examination has no `verified`, no `attested`, and\n * can never upgrade either. What it ranks is where a human reads first — the\n * disagreements, then the agreements whose cited files do not overlap.\n *\n * The join is by claim id ONLY. The ids are deterministic functions of the\n * claims (`../claims/identity.ts`), which is the whole mechanism: two agents\n * who never saw each other's work still answered the same question under the\n * same key, so their answers are mechanically joinable — where fuzzy-matching\n * claim TEXT would make \"the same question\" an opinion about wording.\n */\nimport type { Answer, Verdict } from \"../answers.js\";\nimport type { Claim } from \"../checklist.js\";\nimport type { ClaimKind } from \"../claims/identity.js\";\nimport type { VerifyNotice } from \"../record.js\";\n\n/**\n * One side's answer, as the cross-examination reports it. Deliberately\n * narrower than {@link Answer}: `answered_by` is always `agent` under a diff\n * (both sets validate through `checkAnswers`' agent path, no report in\n * sight), and `evidence_pins` never rides through — a pin is loam's own\n * stamp, absent from `checkAnswers`' output by construction, and a diff of\n * caller-written files must not launder one into a payload.\n */\nexport interface CrossAnswer {\n  verdict: Verdict;\n  evidence: string[];\n  note?: string;\n}\n\ninterface CrossBase {\n  id: string;\n  kind: ClaimKind;\n  subject: string;\n  claim: string;\n  a: CrossAnswer;\n  b: CrossAnswer;\n}\n\n/**\n * One claim, both answers, and what their comparison is. A union rather than\n * an optional-field record so `evidenceDisjoint` is not constructible on the\n * arms it means nothing for: two agents disagreeing cite different things by\n * definition, and two unconfirmed answers cite nothing.\n */\nexport type CrossClaim =\n  | (CrossBase & { code: \"cross.agree-confirmed\"; evidenceDisjoint?: true })\n  | (CrossBase & { code: \"cross.agree-unconfirmed\" })\n  | (CrossBase & { code: \"cross.disagree\" });\n\nexport type CrossCode = CrossClaim[\"code\"];\n\nexport interface CrossExamination {\n  /** Checklist order — the order the questions were asked, whatever either agent did. */\n  rows: CrossClaim[];\n  summary: {\n    claims: number;\n    agreeConfirmed: number;\n    agreeUnconfirmed: number;\n    disagree: number;\n    evidenceDisjoint: number;\n  };\n  /** The `cross.disagree` rows again, first-class: they are what a reader is for. */\n  disagreements: CrossClaim[];\n}\n\n/**\n * The FILE a piece of evidence cites: one trailing `:<line>` or\n * `:<line>-<line>` suffix stripped, nothing else judged. Mechanical string\n * surgery on purpose — evidence is prose the answerer wrote, and any deeper\n * reading (resolving against a tree, normalizing separators) would turn the\n * disjointness signal into an opinion about paths instead of a fact about\n * citations.\n */\nfunction citedFile(evidence: string): string {\n  return evidence.replace(/:\\d+(-\\d+)?$/, \"\");\n}\n\nfunction side(answer: Answer): CrossAnswer {\n  return {\n    verdict: answer.verdict,\n    evidence: answer.evidence,\n    ...(answer.note === undefined ? {} : { note: answer.note }),\n  };\n}\n\nfunction crossRow(claim: Claim, a: Answer, b: Answer): CrossClaim {\n  const base: CrossBase = {\n    id: claim.id,\n    kind: claim.kind,\n    subject: claim.subject,\n    claim: claim.claim,\n    a: side(a),\n    b: side(b),\n  };\n  if (a.verdict !== b.verdict) return { ...base, code: \"cross.disagree\" };\n  if (a.verdict === \"confirmed\") {\n    // Both confirmed, so both cite at least one entry (`checkAnswers` refuses\n    // an evidenced-nothing confirmation) — disjoint therefore means \"looked in\n    // different places and agreed anyway\", never \"nobody cited anything\".\n    const files = new Set(a.evidence.map(citedFile));\n    const disjoint = !b.evidence.some((entry) => files.has(citedFile(entry)));\n    return { ...base, code: \"cross.agree-confirmed\", ...(disjoint ? { evidenceDisjoint: true as const } : {}) };\n  }\n  return { ...base, code: \"cross.agree-unconfirmed\" };\n}\n\n/**\n * Join two validated answer sets over the claims they both answered.\n *\n * Both sets must have come out of `checkAnswers` over THIS `claims` array,\n * which refuses any set that does not answer every claim exactly once — so\n * there is deliberately no missing-answer branch in the result shape. The\n * guard below still fails closed on a caller that skipped validation: a\n * silent skip would report \"no disagreement\" about a claim nobody compared,\n * which is the one lie this module exists to prevent.\n */\nexport function crossExamine(claims: Claim[], a: Answer[], b: Answer[]): CrossExamination {\n  const byIdA = new Map(a.map((answer) => [answer.id, answer]));\n  const byIdB = new Map(b.map((answer) => [answer.id, answer]));\n  const rows = claims.map((claim) => {\n    const answerA = byIdA.get(claim.id);\n    const answerB = byIdB.get(claim.id);\n    if (answerA === undefined || answerB === undefined) {\n      throw new Error(\n        `crossExamine: claim ${claim.id} has no answer in the ${answerA === undefined ? \"first\" : \"second\"} set — ` +\n          \"validate both sets with checkAnswers over the same claims before joining them\",\n      );\n    }\n    return crossRow(claim, answerA, answerB);\n  });\n  const of = (code: CrossCode): number => rows.filter((row) => row.code === code).length;\n  const disagreements = rows.filter((row) => row.code === \"cross.disagree\");\n  return {\n    rows,\n    summary: {\n      claims: rows.length,\n      agreeConfirmed: of(\"cross.agree-confirmed\"),\n      agreeUnconfirmed: of(\"cross.agree-unconfirmed\"),\n      disagree: disagreements.length,\n      evidenceDisjoint: rows.filter((row) => row.code === \"cross.agree-confirmed\" && row.evidenceDisjoint === true)\n        .length,\n    },\n    disagreements,\n  };\n}\n\n/**\n * The one notice this lens raises: agreements whose cited file sets share no\n * path. Second in the reading order after the disagreements, because it is\n * the shape correlated agreement takes when both agents guessed — each found\n * something plausible somewhere, and nothing says they found the same thing.\n */\nexport function disjointNotice(rows: readonly CrossClaim[]): VerifyNotice | null {\n  const ids = rows\n    .filter((row) => row.code === \"cross.agree-confirmed\" && row.evidenceDisjoint === true)\n    .map((row) => row.id);\n  if (ids.length === 0) return null;\n  return {\n    code: \"cross.evidence-disjoint\",\n    severity: \"warn\",\n    message:\n      `${ids.length} agreed-confirmed claim(s) cite non-overlapping files: ${ids.join(\", \")}. ` +\n      \"Two agents agreeing from different evidence is the second thing to read, after the disagreements.\",\n    claims: ids,\n  };\n}\n"]}