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

package/dist/core/verify/file.js

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

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

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

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

@@ -0,0 +1,157 @@
+/**
+ * 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` (`../file.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` (`../file.ts` asks `./pin.ts` for the read\n * guard, `../answers.ts` for the shape), so importing 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` (../file.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` (../file.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"]}