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

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

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

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

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

package/dist/core/verify/location.js

@@ -0,0 +1,67 @@
+/**
+ * Where the verification record lives on disk — the one-file form, the
+ * per-service directory, and which of the two a reader is pointed at.
+ *
+ * Split out of `./record.ts`, which keeps what gets written down and how a set
+ * of answers counts up to a verdict: the addresses are a different subject from
+ * the shapes and the arithmetic, and the per-service directory pushed that
+ * module over the line limit. The readers (`./read/file.ts`), the writers
+ * (`loam verify`'s record step) and `status`'s artifact row all ask where the
+ * record is; none of them needs the record's shape to ask it.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 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.
+ *
+ * This is the ONE-FILE form: what the all-at-once `--record` (no `--service`)
+ * writes, and what every federated record written before the per-service
+ * directory existed still is. It is read forever, active and archived alike.
+ * A federated attestation no longer goes here — see {@link serviceRecordPath}.
+ */
+export function verificationPath(featureDir) {
+    return join(featureDir, "verification.yaml");
+}
+/**
+ * The federated record: one file per attesting service, and the DIRECTORY is
+ * the list — the `glossary/` and `capabilities/` rule.
+ *
+ * One shared file was the wrong shape for a fleet. Every service's attestation
+ * rewrote the same `summary`, `recorded` and checklist-ordered `claims`, so two
+ * docs-repo branches recording two DIFFERENT services always conflicted in git
+ * — add/add from an empty start, content conflicts on the summary once one
+ * attestation had merged — and sorting the attestations did not help, because
+ * two insertions at one anchor are a conflict whatever the order. The lock that
+ * serialises writers covers one checkout; a fleet records from many. With one
+ * file per service, two teams' records touch two different paths and merge
+ * cleanly, and the verdict is computed from the union at read time — which it
+ * always was: nothing ever trusted the stored `summary`.
+ */
+export function verificationDir(featureDir) {
+    return join(featureDir, "verification");
+}
+/**
+ * One service's attestation file. The service id grammar admits no `/`, so this
+ * never leaves the directory — and the parameter type is what makes that a
+ * guarantee rather than a hope: a `PathableService` is a name whose provenance
+ * is the repository (a validated id, or a directory that exists), so a name a
+ * document merely asserts, or a raw flag nobody checked, does not compile here.
+ */
+export function serviceRecordPath(featureDir, service) {
+    return join(verificationDir(featureDir), `${service}.yaml`);
+}
+/**
+ * Where a reader should look: the directory once it exists, the one file
+ * otherwise. A single path is lossy on purpose — a record mid-migration is
+ * both — and what a reader is pointed at is where the next attestation will
+ * land. A legacy file beside the directory is still read (see `./read/file.ts`);
+ * it is simply no longer where anything is written for a service.
+ */
+export function recordLocation(featureDir) {
+    const dir = verificationDir(featureDir);
+    return existsSync(dir) ? dir : verificationPath(featureDir);
+}
+//# sourceMappingURL=location.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../../src/core/verify/location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,OAAwB;IAC5E,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,MAAM,GAAG,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * Where the verification record lives on disk — the one-file form, the\n * per-service directory, and which of the two a reader is pointed at.\n *\n * Split out of `./record.ts`, which keeps what gets written down and how a set\n * of answers counts up to a verdict: the addresses are a different subject from\n * the shapes and the arithmetic, and the per-service directory pushed that\n * module over the line limit. The readers (`./read/file.ts`), the writers\n * (`loam verify`'s record step) and `status`'s artifact row all ask where the\n * record is; none of them needs the record's shape to ask it.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\n\n/**\n * Where the record lives: inside the feature, so `archive` carries it into\n * `features/archive/` with everything else and a reviewer finds it next to the\n * delta it is about. YAML rather than frontmatter or JSON — it is data, it has\n * to survive without loam, and one claim per block is a diff a person can read.\n *\n * This is the ONE-FILE form: what the all-at-once `--record` (no `--service`)\n * writes, and what every federated record written before the per-service\n * directory existed still is. It is read forever, active and archived alike.\n * A federated attestation no longer goes here — see {@link serviceRecordPath}.\n */\nexport function verificationPath(featureDir: string): string {\n  return join(featureDir, \"verification.yaml\");\n}\n\n/**\n * The federated record: one file per attesting service, and the DIRECTORY is\n * the list — the `glossary/` and `capabilities/` rule.\n *\n * One shared file was the wrong shape for a fleet. Every service's attestation\n * rewrote the same `summary`, `recorded` and checklist-ordered `claims`, so two\n * docs-repo branches recording two DIFFERENT services always conflicted in git\n * — add/add from an empty start, content conflicts on the summary once one\n * attestation had merged — and sorting the attestations did not help, because\n * two insertions at one anchor are a conflict whatever the order. The lock that\n * serialises writers covers one checkout; a fleet records from many. With one\n * file per service, two teams' records touch two different paths and merge\n * cleanly, and the verdict is computed from the union at read time — which it\n * always was: nothing ever trusted the stored `summary`.\n */\nexport function verificationDir(featureDir: string): string {\n  return join(featureDir, \"verification\");\n}\n\n/**\n * One service's attestation file. The service id grammar admits no `/`, so this\n * never leaves the directory — and the parameter type is what makes that a\n * guarantee rather than a hope: a `PathableService` is a name whose provenance\n * is the repository (a validated id, or a directory that exists), so a name a\n * document merely asserts, or a raw flag nobody checked, does not compile here.\n */\nexport function serviceRecordPath(featureDir: string, service: PathableService): string {\n  return join(verificationDir(featureDir), `${service}.yaml`);\n}\n\n/**\n * Where a reader should look: the directory once it exists, the one file\n * otherwise. A single path is lossy on purpose — a record mid-migration is\n * both — and what a reader is pointed at is where the next attestation will\n * land. A legacy file beside the directory is still read (see `./read/file.ts`);\n * it is simply no longer where anything is written for a service.\n */\nexport function recordLocation(featureDir: string): string {\n  const dir = verificationDir(featureDir);\n  return existsSync(dir) ? dir : verificationPath(featureDir);\n}\n"]}

package/dist/core/verify/pins/lint.js

@@ -0,0 +1,158 @@
+/**
+ * Re-checking evidence pins against a working tree: pure data out, one grade
+ * per pin, and no verdict anywhere in the result on purpose — the lint demotes
+ * reviewer confidence, it never promotes or demotes a claim. Prints nothing;
+ * the validate command turns the grades into findings.
+ *
+ * The claim shape is structural rather than an import of `../record.js`'s
+ * `RecordedClaim`, and not only for the smallest-parameter rule: this package
+ * is imported BY `core/verify` and its `read/` sibling (`../read/shape.ts` asks
+ * `./pin.ts` for the read guard, `../answers.ts` for the shape), so importing
+ * the parent back would
+ * put a cycle in the package graph that `import/no-cycle` cannot see.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { inOrder } from "../../kernel/concurrency.js";
+import { resolvePortableFileInside, UnsafePathError } from "../../kernel/path-safety.js";
+import { pinnedDigest, pinnedText, sourceLines } from "./pin.js";
+/**
+ * Grade one record's pins for one service against that service's working tree.
+ *
+ * Only agent-confirmed claims of `service` are graded: a runner's or contract
+ * runner's evidence names a report entry, not a file, so there is nothing to
+ * re-check, and an unconfirmed claim pinned nothing. Absent `answered_by`
+ * counts as agent — the `attestedClaims` rule.
+ *
+ * Containment is per citation: one unreadable cited file degrades exactly the
+ * pins that cite it (graded `unresolved`), never the sibling pins and never
+ * the whole record. And "could not look" is never "looks fine": every failure
+ * to read is a drift entry, not a skip — fail closed at the validator.
+ */
+export async function lintEvidencePins(claims, service, repoDir) {
+    // The closed side of the answerer test, on purpose: `answered_by` is an open
+    // string here (a record is hand-editable YAML, and a newer loam may add
+    // answerers), so excluding the known mechanical values would sweep every
+    // FUTURE mechanical answerer's report-entry citations into the `unpinned`
+    // tally with false "recorded before pins existed" advice. Only what is
+    // positively an agent's word is graded; absent counts as agent — the
+    // `attestedClaims` rule for records that predate `--results`.
+    const mine = claims.filter((c) => c.subject === service &&
+        c.verdict === "confirmed" &&
+        (c.answered_by === undefined || c.answered_by === "agent"));
+    // Join pins to evidence entries by the `path:line` key, never by position:
+    // a record is hand-editable YAML, and a positional join would let a deleted
+    // evidence line silently shift every later pin onto the wrong citation.
+    const joined = [];
+    let unpinned = 0;
+    for (const claim of mine) {
+        const pins = new Map((claim.evidence_pins ?? []).map((pin) => [`${pin.path}:${pin.line}`, pin]));
+        // A pin no evidence entry names pins nothing this claim cites (a hand
+        // edit); grading it would report drift about a citation the claim does not
+        // make, so only the joined pairs are graded. The reverse direction — a
+        // citation without a pin — is the `unpinned` tally.
+        for (const evidence of claim.evidence) {
+            const pin = pins.get(evidence);
+            if (pin === undefined)
+                unpinned += 1;
+            else
+                joined.push({ claim: claim.id, evidence, pin });
+        }
+    }
+    // Each distinct cited file is read and hashed once per call — a local map,
+    // per invocation, because module-level state leaks across tests and hosts.
+    // The reads are independent, so they go through the bounded pool; grading
+    // stays sequential below so `drifts` keeps record order.
+    const paths = [...new Set(joined.map((j) => j.pin.path))];
+    const states = new Map(await inOrder(paths, async (path) => [path, await readCited(repoDir, path)]));
+    let checked = 0;
+    const drifts = [];
+    for (const { claim, evidence, pin } of joined) {
+        const file = states.get(pin.path);
+        if (file === undefined || file.state === "unreadable") {
+            drifts.push({ claim, evidence, grade: "unresolved", what: file?.what ?? "the cited file was not read" });
+            continue;
+        }
+        const cited = file.lines[pin.line - 1];
+        if (cited === undefined) {
+            drifts.push({
+                claim,
+                evidence,
+                grade: "unresolved",
+                // `continue`, like the unreadable-file arm: an unresolvable CITATION
+                // is one finding, and a token scan on top would report the same
+                // damaged citation twice under two codes.
+                what: `the cited line is past the end — the file now has ${file.lines.length} line(s)`,
+            });
+            continue;
+        }
+        if (file.digest === pin.file_sha256) {
+            checked += 1;
+        }
+        else if (pinnedText(cited) === pin.text) {
+            // The mildest drift: the file changed around the cited line, which
+            // still reads as pinned — "reads as", not "is": both sides of the
+            // comparison are capped at PIN_TEXT_CAP, so a change past the cap on a
+            // pathological line is invisible to this grade (and visible to the
+            // digest, which is why this is a drift and not a clean pin).
+            drifts.push({
+                claim,
+                evidence,
+                grade: "moved",
+                what: "the file changed around the cited line, which still reads as pinned",
+            });
+        }
+        else {
+            drifts.push({
+                claim,
+                evidence,
+                grade: "line-changed",
+                what: `the cited line now reads '${pinnedText(cited)}' where the record pinned '${pin.text}'`,
+            });
+        }
+        // Independent of the grades above, clean pins included — a digest match
+        // must not read as "the token is still there", because content identical
+        // to record time says nothing once the file drifts back. "No longer" is
+        // the honest word here: the write side stamps `token` only when the
+        // attested blob contained it (EvidencePin.token), so this grade always
+        // convicts a disappearance, never re-litigates an absence the record-time
+        // notice already reported.
+        if (pin.token !== undefined && !file.text.includes(pin.token)) {
+            drifts.push({
+                claim,
+                evidence,
+                grade: "token-missing",
+                what: `the cited file no longer contains '${pin.token}' — the literal string the claim asserts`,
+            });
+        }
+    }
+    return { checked, drifts, unpinned };
+}
+/** One cited file against the working tree, every failure named rather than thrown. */
+async function readCited(repoDir, path) {
+    let absolute;
+    try {
+        absolute = resolvePortableFileInside(repoDir, path, "pinned evidence");
+    }
+    catch (err) {
+        if (!(err instanceof UnsafePathError))
+            throw err;
+        return { state: "unreadable", what: `the pinned path is unsafe: ${err.message}` };
+    }
+    try {
+        const info = await stat(absolute);
+        if (!info.isFile())
+            return { state: "unreadable", what: "the cited path is not a regular file" };
+        const text = await readFile(absolute, "utf8");
+        return { state: "ok", digest: pinnedDigest(text), lines: sourceLines(text), text };
+    }
+    catch (err) {
+        // ENOENT is the common drift — the cited file is gone from the tree; any
+        // other errno (EACCES, EISDIR racing the stat) is named as itself, because
+        // "could not read" and "does not exist" call for different repairs.
+        if (err.code === "ENOENT") {
+            return { state: "unreadable", what: "the cited file does not exist in this working tree" };
+        }
+        return { state: "unreadable", what: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/core/verify/pins/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/lint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Re-checking evidence pins against a working tree: pure data out, one grade\n * per pin, and no verdict anywhere in the result on purpose — the lint demotes\n * reviewer confidence, it never promotes or demotes a claim. Prints nothing;\n * the validate command turns the grades into findings.\n *\n * The claim shape is structural rather than an import of `../record.js`'s\n * `RecordedClaim`, and not only for the smallest-parameter rule: this package\n * is imported BY `core/verify` and its `read/` sibling (`../read/shape.ts` asks\n * `./pin.ts` for the read guard, `../answers.ts` for the shape), so importing\n * the parent back would\n * put a cycle in the package graph that `import/no-cycle` cannot see.\n */\nimport { readFile, stat } from \"node:fs/promises\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { resolvePortableFileInside, UnsafePathError } from \"../../kernel/path-safety.js\";\nimport { pinnedDigest, pinnedText, sourceLines, type EvidencePin } from \"./pin.js\";\n\n/** What the lint reads off a recorded claim — structurally, see the header. */\nexport interface PinnedClaim {\n  id: string;\n  /** Present in federated (schema 2) records — the service whose code answers it. */\n  subject?: string;\n  verdict: string;\n  /** Absent counts as agent — the `attestedClaims` rule for records that predate `--results`. */\n  answered_by?: string;\n  evidence: string[];\n  evidence_pins?: EvidencePin[];\n}\n\n/** One pin's disagreement with the working tree. `grade` is what a finding code is made from. */\nexport interface PinDrift {\n  claim: string;\n  /** The `path:line` citation the pin belongs to. */\n  evidence: string;\n  grade: \"unresolved\" | \"moved\" | \"line-changed\" | \"token-missing\";\n  /** What changed, in one clause — rendered into a finding's detail line. */\n  what: string;\n}\n\nexport interface PinLint {\n  /** Pins that resolved clean: file digest unchanged against the working tree. */\n  checked: number;\n  /** In record order — claim by claim, citation by citation — so two runs diff. */\n  drifts: PinDrift[];\n  /** Agent-confirmed citations carrying no pin, plus claims with no pins at all. */\n  unpinned: number;\n}\n\n/** What one cited file turned out to be, read and hashed once per lint call. */\ntype FileState =\n  | { state: \"unreadable\"; what: string }\n  | { state: \"ok\"; digest: string; lines: string[]; text: string };\n\n/**\n * Grade one record's pins for one service against that service's working tree.\n *\n * Only agent-confirmed claims of `service` are graded: a runner's or contract\n * runner's evidence names a report entry, not a file, so there is nothing to\n * re-check, and an unconfirmed claim pinned nothing. Absent `answered_by`\n * counts as agent — the `attestedClaims` rule.\n *\n * Containment is per citation: one unreadable cited file degrades exactly the\n * pins that cite it (graded `unresolved`), never the sibling pins and never\n * the whole record. And \"could not look\" is never \"looks fine\": every failure\n * to read is a drift entry, not a skip — fail closed at the validator.\n */\nexport async function lintEvidencePins(\n  claims: readonly PinnedClaim[],\n  service: string,\n  repoDir: string,\n): Promise<PinLint> {\n  // The closed side of the answerer test, on purpose: `answered_by` is an open\n  // string here (a record is hand-editable YAML, and a newer loam may add\n  // answerers), so excluding the known mechanical values would sweep every\n  // FUTURE mechanical answerer's report-entry citations into the `unpinned`\n  // tally with false \"recorded before pins existed\" advice. Only what is\n  // positively an agent's word is graded; absent counts as agent — the\n  // `attestedClaims` rule for records that predate `--results`.\n  const mine = claims.filter(\n    (c) =>\n      c.subject === service &&\n      c.verdict === \"confirmed\" &&\n      (c.answered_by === undefined || c.answered_by === \"agent\"),\n  );\n\n  // Join pins to evidence entries by the `path:line` key, never by position:\n  // a record is hand-editable YAML, and a positional join would let a deleted\n  // evidence line silently shift every later pin onto the wrong citation.\n  const joined: Array<{ claim: string; evidence: string; pin: EvidencePin }> = [];\n  let unpinned = 0;\n  for (const claim of mine) {\n    const pins = new Map((claim.evidence_pins ?? []).map((pin) => [`${pin.path}:${pin.line}`, pin]));\n    // A pin no evidence entry names pins nothing this claim cites (a hand\n    // edit); grading it would report drift about a citation the claim does not\n    // make, so only the joined pairs are graded. The reverse direction — a\n    // citation without a pin — is the `unpinned` tally.\n    for (const evidence of claim.evidence) {\n      const pin = pins.get(evidence);\n      if (pin === undefined) unpinned += 1;\n      else joined.push({ claim: claim.id, evidence, pin });\n    }\n  }\n\n  // Each distinct cited file is read and hashed once per call — a local map,\n  // per invocation, because module-level state leaks across tests and hosts.\n  // The reads are independent, so they go through the bounded pool; grading\n  // stays sequential below so `drifts` keeps record order.\n  const paths = [...new Set(joined.map((j) => j.pin.path))];\n  const states = new Map(\n    await inOrder(paths, async (path): Promise<[string, FileState]> => [path, await readCited(repoDir, path)]),\n  );\n\n  let checked = 0;\n  const drifts: PinDrift[] = [];\n  for (const { claim, evidence, pin } of joined) {\n    const file = states.get(pin.path);\n    if (file === undefined || file.state === \"unreadable\") {\n      drifts.push({ claim, evidence, grade: \"unresolved\", what: file?.what ?? \"the cited file was not read\" });\n      continue;\n    }\n    const cited = file.lines[pin.line - 1];\n    if (cited === undefined) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"unresolved\",\n        // `continue`, like the unreadable-file arm: an unresolvable CITATION\n        // is one finding, and a token scan on top would report the same\n        // damaged citation twice under two codes.\n        what: `the cited line is past the end — the file now has ${file.lines.length} line(s)`,\n      });\n      continue;\n    }\n    if (file.digest === pin.file_sha256) {\n      checked += 1;\n    } else if (pinnedText(cited) === pin.text) {\n      // The mildest drift: the file changed around the cited line, which\n      // still reads as pinned — \"reads as\", not \"is\": both sides of the\n      // comparison are capped at PIN_TEXT_CAP, so a change past the cap on a\n      // pathological line is invisible to this grade (and visible to the\n      // digest, which is why this is a drift and not a clean pin).\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"moved\",\n        what: \"the file changed around the cited line, which still reads as pinned\",\n      });\n    } else {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"line-changed\",\n        what: `the cited line now reads '${pinnedText(cited)}' where the record pinned '${pin.text}'`,\n      });\n    }\n    // Independent of the grades above, clean pins included — a digest match\n    // must not read as \"the token is still there\", because content identical\n    // to record time says nothing once the file drifts back. \"No longer\" is\n    // the honest word here: the write side stamps `token` only when the\n    // attested blob contained it (EvidencePin.token), so this grade always\n    // convicts a disappearance, never re-litigates an absence the record-time\n    // notice already reported.\n    if (pin.token !== undefined && !file.text.includes(pin.token)) {\n      drifts.push({\n        claim,\n        evidence,\n        grade: \"token-missing\",\n        what: `the cited file no longer contains '${pin.token}' — the literal string the claim asserts`,\n      });\n    }\n  }\n  return { checked, drifts, unpinned };\n}\n\n/** One cited file against the working tree, every failure named rather than thrown. */\nasync function readCited(repoDir: string, path: string): Promise<FileState> {\n  let absolute: string;\n  try {\n    absolute = resolvePortableFileInside(repoDir, path, \"pinned evidence\");\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return { state: \"unreadable\", what: `the pinned path is unsafe: ${err.message}` };\n  }\n  try {\n    const info = await stat(absolute);\n    if (!info.isFile()) return { state: \"unreadable\", what: \"the cited path is not a regular file\" };\n    const text = await readFile(absolute, \"utf8\");\n    return { state: \"ok\", digest: pinnedDigest(text), lines: sourceLines(text), text };\n  } catch (err) {\n    // ENOENT is the common drift — the cited file is gone from the tree; any\n    // other errno (EACCES, EISDIR racing the stat) is named as itself, because\n    // \"could not read\" and \"does not exist\" call for different repairs.\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return { state: \"unreadable\", what: \"the cited file does not exist in this working tree\" };\n    }\n    return { state: \"unreadable\", what: err instanceof Error ? err.message : String(err) };\n  }\n}\n"]}

package/dist/core/verify/pins/pin.js

@@ -0,0 +1,95 @@
+/**
+ * The evidence pin's identity: what `verify --service --record` stamps beside a
+ * confirmed agent answer so a later `loam validate`, standing in the same
+ * service repository, can re-check the citation against the working tree.
+ *
+ * Be precise about what a pin proves, because the record travels without loam:
+ * a pin identifies WHAT was cited at the attested commit — the cited file's
+ * normalized sha256, the cited line's text, the literal token the claim
+ * asserts. It does not prove the claim true; an agent that cited the wrong
+ * line gets a faithful pin of the wrong line. That is why the read side
+ * (`./lint.ts`) only ever demotes reviewer confidence: no pin state moves a
+ * verdict in either direction.
+ */
+import { createHash } from "node:crypto";
+import { isRecord } from "../../kernel/records.js";
+/**
+ * How much of the cited line a pin carries. Enough to recognize a line of
+ * source by eye and by equality; a cap because evidence may cite a line of a
+ * generated client or a minified bundle, and the record is a YAML file people
+ * read and diff — one pathological line must not turn it into one.
+ */
+export const PIN_TEXT_CAP = 200;
+/** The pin's line recipe: trimmed (indentation is formatting), capped at {@link PIN_TEXT_CAP}. */
+export function pinnedText(line) {
+    const trimmed = line.trim();
+    return trimmed.length > PIN_TEXT_CAP ? trimmed.slice(0, PIN_TEXT_CAP) : trimmed;
+}
+/**
+ * The one spelling of where lines fall. Both sides of the pin — the write
+ * side's bounds checks and the read side's re-grade — must number lines
+ * identically, or a pin recorded at line 12 gets graded against a different
+ * line 12; four call sites each spelling the regex themselves is how that
+ * divergence would arrive, so the recipe has exactly one home.
+ */
+export function sourceLines(source) {
+    return source.split(/\r\n|\n|\r/);
+}
+/**
+ * The cited line of a source text, through the pin recipe — or undefined when
+ * the line is past the end, which the caller grades (a refusal on the write
+ * side, `unresolved` on the read side).
+ */
+export function citedLine(source, line) {
+    const raw = sourceLines(source)[line - 1];
+    return raw === undefined ? undefined : pinnedText(raw);
+}
+/**
+ * The pin's file digest: sha256 hex over the text with CRLF/CR normalized to
+ * LF.
+ *
+ * Normalized because git's eol config makes blob bytes and working-tree bytes
+ * legally differ: on a Windows checkout with `core.autocrlf=true`, the blob
+ * the attested commit holds is LF while every file on disk is CRLF, so an
+ * unnormalized digest would grade every pin `evidence.moved` forever on the
+ * checkout config alone. The pin must convict content change, never checkout
+ * config. The recipe is over TEXT by construction — the write side digests
+ * `git show` output already decoded as utf8 — and the symmetric cost is
+ * accepted and documented in SCHEMA.md: a pure line-ending change is invisible
+ * to the lint.
+ */
+export function pinnedDigest(source) {
+    return createHash("sha256").update(source.replace(/\r\n|\r/g, "\n")).digest("hex");
+}
+/**
+ * The read-shape guard `asVerification` (../read/shape.ts) asks per claim, on the
+ * `isConsumedContractReport` model to the letter: absent is fine — every
+ * record written before pins existed, and every runner-answered claim, has
+ * none — but present must be whole for the four fields the lint dereferences.
+ * A broken pins block makes the WHOLE record unreadable and therefore never
+ * overwritten, exactly the contract-report rule: it is somebody's record, and
+ * a lint that silently skipped a malformed pin would read a hand-damaged
+ * record as drift-free. `token` stays optional-and-any-string for `format`'s
+ * reason — a field a newer loam learned to stamp must not brick the record
+ * here.
+ */
+export function isEvidencePinList(v) {
+    if (v === undefined)
+        return true;
+    if (!Array.isArray(v))
+        return false;
+    for (const pin of v) {
+        if (!isRecord(pin))
+            return false;
+        if (typeof pin["path"] !== "string")
+            return false;
+        if (typeof pin["line"] !== "number" || !Number.isInteger(pin["line"]) || pin["line"] < 1)
+            return false;
+        if (typeof pin["file_sha256"] !== "string" || typeof pin["text"] !== "string")
+            return false;
+        if (pin["token"] !== undefined && typeof pin["token"] !== "string")
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=pin.js.map

package/dist/core/verify/pins/pin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/verify/pins/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AA4BnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,kGAAkG;AAClG,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAClF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,IAAY;IACpD,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClD,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvG,IAAI,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5F,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The evidence pin's identity: what `verify --service --record` stamps beside a\n * confirmed agent answer so a later `loam validate`, standing in the same\n * service repository, can re-check the citation against the working tree.\n *\n * Be precise about what a pin proves, because the record travels without loam:\n * a pin identifies WHAT was cited at the attested commit — the cited file's\n * normalized sha256, the cited line's text, the literal token the claim\n * asserts. It does not prove the claim true; an agent that cited the wrong\n * line gets a faithful pin of the wrong line. That is why the read side\n * (`./lint.ts`) only ever demotes reviewer confidence: no pin state moves a\n * verdict in either direction.\n */\nimport { createHash } from \"node:crypto\";\nimport { isRecord } from \"../../kernel/records.js\";\n\nexport interface EvidencePin {\n  /** The cited file, repo-relative in the portable spelling evidence entries use. */\n  path: string;\n  /** The cited line, 1-based — the `:N` of the evidence entry this pins. */\n  line: number;\n  /** sha256 hex of the whole file at the attested commit, normalized — see {@link pinnedDigest}. */\n  file_sha256: string;\n  /** The cited line at the attested commit, trimmed and capped — see {@link pinnedText}. */\n  text: 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` (`Claim.token`, stamped at record time). Carried\n   * on the pin so the read side scans the file for it and never has to\n   * re-derive a checklist or parse claim prose. Absent for the kinds that\n   * assert no token (`service.exists`, `scenario.tested`) — and absent when\n   * the attested blob did not CONTAIN the token: that fact is warned once, at\n   * record time, where the answerer can still act on it; a pin carrying it\n   * would make `loam validate` repeat \"no longer contains\" forever about a\n   * file that never did, with a re-record that re-derives the same state as\n   * the only offered repair. `token-missing` therefore always means \"was\n   * there at the attested commit and is gone\".\n   */\n  token?: string;\n}\n\n/**\n * How much of the cited line a pin carries. Enough to recognize a line of\n * source by eye and by equality; a cap because evidence may cite a line of a\n * generated client or a minified bundle, and the record is a YAML file people\n * read and diff — one pathological line must not turn it into one.\n */\nexport const PIN_TEXT_CAP = 200;\n\n/** The pin's line recipe: trimmed (indentation is formatting), capped at {@link PIN_TEXT_CAP}. */\nexport function pinnedText(line: string): string {\n  const trimmed = line.trim();\n  return trimmed.length > PIN_TEXT_CAP ? trimmed.slice(0, PIN_TEXT_CAP) : trimmed;\n}\n\n/**\n * The one spelling of where lines fall. Both sides of the pin — the write\n * side's bounds checks and the read side's re-grade — must number lines\n * identically, or a pin recorded at line 12 gets graded against a different\n * line 12; four call sites each spelling the regex themselves is how that\n * divergence would arrive, so the recipe has exactly one home.\n */\nexport function sourceLines(source: string): string[] {\n  return source.split(/\\r\\n|\\n|\\r/);\n}\n\n/**\n * The cited line of a source text, through the pin recipe — or undefined when\n * the line is past the end, which the caller grades (a refusal on the write\n * side, `unresolved` on the read side).\n */\nexport function citedLine(source: string, line: number): string | undefined {\n  const raw = sourceLines(source)[line - 1];\n  return raw === undefined ? undefined : pinnedText(raw);\n}\n\n/**\n * The pin's file digest: sha256 hex over the text with CRLF/CR normalized to\n * LF.\n *\n * Normalized because git's eol config makes blob bytes and working-tree bytes\n * legally differ: on a Windows checkout with `core.autocrlf=true`, the blob\n * the attested commit holds is LF while every file on disk is CRLF, so an\n * unnormalized digest would grade every pin `evidence.moved` forever on the\n * checkout config alone. The pin must convict content change, never checkout\n * config. The recipe is over TEXT by construction — the write side digests\n * `git show` output already decoded as utf8 — and the symmetric cost is\n * accepted and documented in SCHEMA.md: a pure line-ending change is invisible\n * to the lint.\n */\nexport function pinnedDigest(source: string): string {\n  return createHash(\"sha256\").update(source.replace(/\\r\\n|\\r/g, \"\\n\")).digest(\"hex\");\n}\n\n/**\n * The read-shape guard `asVerification` (../read/shape.ts) asks per claim, on the\n * `isConsumedContractReport` model to the letter: absent is fine — every\n * record written before pins existed, and every runner-answered claim, has\n * none — but present must be whole for the four fields the lint dereferences.\n * A broken pins block makes the WHOLE record unreadable and therefore never\n * overwritten, exactly the contract-report rule: it is somebody's record, and\n * a lint that silently skipped a malformed pin would read a hand-damaged\n * record as drift-free. `token` stays optional-and-any-string for `format`'s\n * reason — a field a newer loam learned to stamp must not brick the record\n * here.\n */\nexport function isEvidencePinList(v: unknown): boolean {\n  if (v === undefined) return true;\n  if (!Array.isArray(v)) return false;\n  for (const pin of v) {\n    if (!isRecord(pin)) return false;\n    if (typeof pin[\"path\"] !== \"string\") return false;\n    if (typeof pin[\"line\"] !== \"number\" || !Number.isInteger(pin[\"line\"]) || pin[\"line\"] < 1) return false;\n    if (typeof pin[\"file_sha256\"] !== \"string\" || typeof pin[\"text\"] !== \"string\") return false;\n    if (pin[\"token\"] !== undefined && typeof pin[\"token\"] !== \"string\") return false;\n  }\n  return true;\n}\n"]}