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

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"]}

package/dist/core/verify/record.js

@@ -0,0 +1,142 @@
+/**
+ * What gets written down, and how a set of answers counts up to a verdict.
+ *
+ * The shapes and the arithmetic are one module because they are one claim about
+ * the same numbers: `tallyRecord` recounts from the answers rather than reading
+ * the `summary` field back, so a record whose header disagrees with its own
+ * claims is caught rather than believed. A separate counter would be a second
+ * opinion, which is precisely what this file exists to prevent.
+ *
+ * `verified` is reserved for a checklist whose scenarios a RUN answered.
+ * Where an agent answered one instead — a legacy service whose suite is months
+ * away, which is the fleet loam exists for — the record marks it attested, and
+ * `attestedNotice` says so on every surface that reads the record.
+ */
+import { join } from "node:path";
+import {} from "./claims/identity.js";
+import {} from "./answers.js";
+import {} from "./pins/pin.js";
+/**
+ * The confirmed `scenario.tested` claims that no test run answered.
+ *
+ * A scenario claim's whole premise is that a run answers it — its digest IS the
+ * tag `loam gherkin` stamps, and `--results` matches the two mechanically. An
+ * agent may still answer one, because a legacy service has no runnable suite
+ * for months and that fleet is who loam is for; but the answer is somebody's
+ * word about a test, and it must not read as the run. A record written before
+ * `--results` existed carries no `answered_by` at all: unknown counts as agent
+ * here, because the alternative is to credit a run nobody can point at.
+ */
+export function attestedClaims(claims) {
+    return claims
+        .filter((c) => c.kind === "scenario.tested" && c.verdict === "confirmed" && c.answered_by !== "runner")
+        .map((c) => c.id);
+}
+/**
+ * Of the CONFIRMED answers, one count per `answered_by` value. Anything that is not a runner spelling
+ * counts as the agent's word — a record too old to carry the field says nothing, and crediting a run
+ * nobody can point at is the error that matters. Never derive it by subtracting {@link attestedClaims}
+ * from the confirmed total: that count is `scenario.tested` ALONE, so the fleet scorecard filed every
+ * other kind an agent confirmed under a runner that never ran.
+ */
+export function confirmedProvenance(claims) {
+    const done = claims.filter((c) => c.verdict === "confirmed");
+    const by = (who) => done.filter((c) => c.answered_by === who).length;
+    const ran = { runner: by("runner"), "external-runner": by("external-runner") };
+    return { ...ran, agent: done.length - ran.runner - ran["external-runner"] };
+}
+/**
+ * `unanswered` is the count the answers themselves cannot show: a federated
+ * record holds only what somebody answered, and the claims still owed to other
+ * repositories exist on the checklist, not in `claims[]`. Read views that carry
+ * an `unanswered` status inside the list pass 0 and are counted in place.
+ */
+export function tallyAnswers(claims, unanswered = 0) {
+    const of = (verdict) => claims.filter((c) => c.verdict === verdict).length;
+    return {
+        claims: claims.length + unanswered,
+        confirmed: of("confirmed"),
+        unconfirmed: of("unconfirmed"),
+        unanswered: of("unanswered") + unanswered,
+        attested: attestedClaims(claims).length,
+    };
+}
+/**
+ * The record's own answers, recounted. Never `v.summary`: the summary is what
+ * whoever wrote the file said the answers add up to, and every reader that
+ * believed it reported a record full of unconfirmed claims as fully confirmed.
+ * `readVerificationState` refuses a record whose summary contradicts this, so a
+ * caller holding a Verification may use either — and should use this one.
+ */
+export function tallyRecord(v) {
+    return tallyAnswers(v.claims, v.summary.unanswered ?? 0);
+}
+/**
+ * Three states, because two were a lie. `verified` is the strong claim — every
+ * question answered, every answer confirmed, and every scenario answered by a
+ * digest-matched green run. `attested` is the same completeness resting, for at
+ * least one scenario, on an agent's word. `unverified` is everything else:
+ * nothing recorded, a record gone stale, a claim unanswered or unconfirmed, or
+ * a checklist that asks nothing at all.
+ */
+export const VERIFICATION_VERDICTS = ["verified", "attested", "unverified"];
+export function verificationVerdict(t, stale = false) {
+    if (stale || t.claims === 0 || t.confirmed !== t.claims)
+        return "unverified";
+    return t.attested > 0 ? "attested" : "verified";
+}
+/**
+ * The one notice `verify`, `list` and `status` all show: this record's scenario
+ * claims were confirmed without a run.
+ *
+ * It is a warning and it gates nothing — verify has never gated, and a service
+ * with no suite yet has to be able to ship. What it must never do is read the
+ * same as a green run.
+ */
+export function attestedNotice(claims, feature) {
+    const ids = attestedClaims(claims);
+    if (ids.length === 0)
+        return null;
+    return {
+        code: "verify.scenario-attested",
+        severity: "warn",
+        message: `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(", ")}. ` +
+            `Answer them mechanically once the suite runs: \`loam verify ${feature} --results <cucumber.json>\`.`,
+        claims: ids,
+    };
+}
+/**
+ * The one-line honesty summary of a record that leaves claims open: partial is
+ * not a clean result, and the counts alone did not say so — `summary` carries
+ * them on every surface, and a reader skimming for the ⚠ lines shipped a
+ * half-answered record as done anyway. Null when nothing is open, and the
+ * callers fire it only when a record EXISTS: a feature with no record already
+ * says "Not verified", and calling that "not a clean result" would conflate
+ * not-started with partial. A pure-attested record (all confirmed, some on an
+ * agent's word) never reaches the message either — its counts are closed, and
+ * `attestedNotice` above owns that honesty; two notices about one fact is the
+ * double-reporting this file's notices exist to prevent.
+ */
+export function openClaimsNotice(tally, feature) {
+    const open = tally.unconfirmed + tally.unanswered;
+    if (open === 0)
+        return null;
+    return {
+        code: "verify.claims-open",
+        severity: "warn",
+        message: `not a clean result: of ${tally.claims} claim(s), ${tally.confirmed} confirmed` +
+            (tally.attested > 0 ? ` (${tally.attested} on an agent's word)` : "") +
+            `, ${tally.unconfirmed} unconfirmed, ${tally.unanswered} unanswered — ` +
+            `treat ${feature} as unverified until every claim is answered and confirmed.`,
+    };
+}
+/**
+ * Where the record lives: inside the feature, so `archive` carries it into
+ * `features/archive/` with everything else and a reviewer finds it next to the
+ * delta it is about. YAML rather than frontmatter or JSON — it is data, it has
+ * to survive without loam, and one claim per block is a diff a person can read.
+ */
+export function verificationPath(featureDir) {
+    return join(featureDir, "verification.yaml");
+}
+//# sourceMappingURL=record.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/core/verify/record.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What gets written down, and how a set of answers counts up to a verdict.\n *\n * The shapes and the arithmetic are one module because they are one claim about\n * the same numbers: `tallyRecord` recounts from the answers rather than reading\n * the `summary` field back, so a record whose header disagrees with its own\n * claims is caught rather than believed. A separate counter would be a second\n * opinion, which is precisely what this file exists to prevent.\n *\n * `verified` is reserved for a checklist whose scenarios a RUN answered.\n * Where an agent answered one instead — a legacy service whose suite is months\n * away, which is the fleet loam exists for — the record marks it attested, and\n * `attestedNotice` says so on every surface that reads the record.\n */\nimport { join } from \"node:path\";\nimport { type ClaimKind } from \"./claims/identity.js\";\nimport { type AnsweredBy, type Verdict } from \"./answers.js\";\nimport { type EvidencePin } from \"./pins/pin.js\";\n\nexport interface RecordedClaim {\n  id: string;\n  kind: ClaimKind;\n  /** Present in federated records; omitted by legacy records written before schema 2. */\n  subject?: string;\n  claim: string;\n  verdict: Verdict;\n  /** Who answered — absent only in records written before `--results` existed. */\n  answered_by?: AnsweredBy;\n  evidence: string[];\n  note?: string;\n  /**\n   * One pin per file:line citation of a federated agent-confirmed answer: the\n   * cited file's normalized sha256 at the attested commit, the cited line's\n   * text, and the claim's token where it asserts one. A pin records which\n   * text was cited at that commit so `loam validate`, run later in the\n   * service's own repo, can convict drift; it does not prove the claim true —\n   * a faithful pin of the wrong line is still a wrong answer. Absent on\n   * runner-answered claims (their evidence names a report entry, not a file)\n   * and on every record written before pins existed.\n   */\n  evidence_pins?: EvidencePin[];\n}\n\n/**\n * The test report a `--results` run consumed.\n *\n * Nothing can prove a JSON file came from executing a particular commit — a\n * report is bytes, and bytes are writable. What loam can do is stop leaving the\n * question open: it records exactly which file it read (inside the attesting\n * repository, resolved by the same path rules as evidence), the sha256 of the\n * bytes it read, the file's own mtime and how many digest-tagged scenarios it\n * carried. A reviewer holding the repository can tell whether this is that\n * file; before this, `answered_by: runner` named nothing at all.\n */\nexport interface ConsumedReport {\n  /** As it was passed to `--results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read, so `shasum -a 256 <path>` answers the question. */\n  digest: string;\n  /** ISO-8601 mtime of the report file — when the run that wrote it finished. */\n  mtime: string;\n  /** How many digest-tagged scenarios the report carried. */\n  scenarios: number;\n}\n\n/**\n * The contract-test report a `--contract-results` run consumed — the same pin,\n * the same honesty, for the report that answers `api.exposes` claims by\n * operationId. Nothing here proves the file came from executing the attested\n * commit either; the digest identifies WHICH file was consumed, and the\n * federated form binds a committed one to the commit exactly as `report:` is.\n */\nexport interface ConsumedContractReport {\n  /** As it was passed to `--contract-results` — repo-relative in a federated record. */\n  path: string;\n  /** Full sha256 of the bytes read. */\n  digest: string;\n  /** ISO-8601 mtime of the report file. */\n  mtime: string;\n  /** How many distinct operationIds the report's entries name. */\n  operations: number;\n  /**\n   * Which accepted shape the report was read as — `\"generic\"` for the\n   * documented `loamContractReport: 1` shape, the only one v1 accepts. loam\n   * always writes it, but the READ shape keeps it optional: no reader\n   * dereferences it, so a hand-written pin without it stays a readable record\n   * (`isConsumedContractReport` in ./file.ts says why) — and it is a string\n   * rather than a closed union so a format a NEWER loam learned to read stays\n   * readable here too.\n   */\n  format?: string;\n}\n\n/**\n * Both mechanical answer sheets one recording run may consume, together\n * because they are validated together (`validateServiceEvidence` binds each to\n * the attested commit) and filed together (on the record all-at-once, inside\n * the service's attestation federated). Two loose optional parameters made the\n * inconsistent pair representable at every call site.\n */\nexport interface ConsumedReports {\n  results?: ConsumedReport;\n  contract?: ConsumedContractReport;\n}\n\n/** A service repository's commit-bound contribution to a federated record. */\nexport interface ServiceAttestation {\n  service: string;\n  commit: string;\n  recorded: string;\n  /** Claim ids this commit answered. Kept explicit so stale answers can be pruned safely. */\n  claims: string[];\n  /**\n   * The checklist digest THIS attestation answered.\n   *\n   * The record carries one `checklist` for the whole file, which is the right\n   * field for the all-at-once form and an incomplete one for a federated\n   * record: two services attesting a week apart across a changed delta write\n   * the same top-level digest, and nothing in the file can say they answered\n   * different questions. With this, `verify.checklist-forked` can.\n   *\n   * Optional forever. An attestation written before this field existed carries\n   * no claim about which checklist it answered, and inventing one from the\n   * record-level digest would be asserting exactly the thing that cannot be\n   * known — the `evidence.unpinned` precedent, one axis over.\n   */\n  checklist?: string;\n  /**\n   * The docs-repo commit the checklist was computed from, when the docs repo is\n   * a git repository with a committed HEAD.\n   *\n   * `commit` pins the SERVICE repo — the code the evidence points into.\n   * Nothing pinned the side the QUESTION came from, so a reader could not tell\n   * a re-record against an unchanged feature from one against a rewritten\n   * delta. Absent whenever git cannot answer: a docs repo is not required to be\n   * a git checkout, and a missing pin is not a defect.\n   */\n  docsCommit?: string;\n  /** The report that answered this service's scenario claims, when `--results` did. */\n  report?: ConsumedReport;\n  /** The report that answered this service's api.exposes claims, when `--contract-results` did. */\n  contractReport?: ConsumedContractReport;\n}\n\nexport interface Verification {\n  /** Federated, partial records use schema 2. Absent means the original all-at-once format. */\n  schema?: 2;\n  feature: string;\n  /** The day the answers were recorded. */\n  recorded: string;\n  /** The checklist digest they answer — how a later reader spots a record gone stale. */\n  checklist: string;\n  summary: { claims: number; confirmed: number; unconfirmed: number; unanswered?: number };\n  claims: RecordedClaim[];\n  /** The all-at-once form's consumed report; the federated form files it per attestation. */\n  report?: ConsumedReport;\n  /** The all-at-once form's consumed contract report — filed per attestation when federated. */\n  contractReport?: ConsumedContractReport;\n  attestations?: ServiceAttestation[];\n}\n\n/**\n * Anything carrying an answer, whichever surface holds it: a recorded claim, or\n * the read view's per-claim status. Structural on purpose — the same questions\n * are asked of both, and neither should have to convert into the other to be\n * counted.\n */\nexport interface AnsweredClaim {\n  id: string;\n  kind: string;\n  verdict: string;\n  answered_by?: string;\n}\n\n/**\n * The confirmed `scenario.tested` claims that no test run answered.\n *\n * A scenario claim's whole premise is that a run answers it — its digest IS the\n * tag `loam gherkin` stamps, and `--results` matches the two mechanically. An\n * agent may still answer one, because a legacy service has no runnable suite\n * for months and that fleet is who loam is for; but the answer is somebody's\n * word about a test, and it must not read as the run. A record written before\n * `--results` existed carries no `answered_by` at all: unknown counts as agent\n * here, because the alternative is to credit a run nobody can point at.\n */\nexport function attestedClaims(claims: readonly AnsweredClaim[]): string[] {\n  return claims\n    .filter((c) => c.kind === \"scenario.tested\" && c.verdict === \"confirmed\" && c.answered_by !== \"runner\")\n    .map((c) => c.id);\n}\n\n/**\n * Of the CONFIRMED answers, one count per `answered_by` value. Anything that is not a runner spelling\n * counts as the agent's word — a record too old to carry the field says nothing, and crediting a run\n * nobody can point at is the error that matters. Never derive it by subtracting {@link attestedClaims}\n * from the confirmed total: that count is `scenario.tested` ALONE, so the fleet scorecard filed every\n * other kind an agent confirmed under a runner that never ran.\n */\nexport function confirmedProvenance(claims: readonly AnsweredClaim[]): Record<AnsweredBy, number> {\n  const done = claims.filter((c) => c.verdict === \"confirmed\");\n  const by = (who: AnsweredBy): number => done.filter((c) => c.answered_by === who).length;\n  const ran = { runner: by(\"runner\"), \"external-runner\": by(\"external-runner\") };\n  return { ...ran, agent: done.length - ran.runner - ran[\"external-runner\"] };\n}\n\n/** How a set of answers counts up — recounted from the answers, never read off a `summary`. */\nexport interface RecordTally {\n  /** Questions asked: answered, plus the ones a federated record leaves for other repos. */\n  claims: number;\n  confirmed: number;\n  unconfirmed: number;\n  unanswered: number;\n  /** Of the confirmed, the scenario claims on an agent's word. See {@link attestedClaims}. */\n  attested: number;\n}\n\n/**\n * `unanswered` is the count the answers themselves cannot show: a federated\n * record holds only what somebody answered, and the claims still owed to other\n * repositories exist on the checklist, not in `claims[]`. Read views that carry\n * an `unanswered` status inside the list pass 0 and are counted in place.\n */\nexport function tallyAnswers(claims: readonly AnsweredClaim[], unanswered = 0): RecordTally {\n  const of = (verdict: string): number => claims.filter((c) => c.verdict === verdict).length;\n  return {\n    claims: claims.length + unanswered,\n    confirmed: of(\"confirmed\"),\n    unconfirmed: of(\"unconfirmed\"),\n    unanswered: of(\"unanswered\") + unanswered,\n    attested: attestedClaims(claims).length,\n  };\n}\n\n/**\n * The record's own answers, recounted. Never `v.summary`: the summary is what\n * whoever wrote the file said the answers add up to, and every reader that\n * believed it reported a record full of unconfirmed claims as fully confirmed.\n * `readVerificationState` refuses a record whose summary contradicts this, so a\n * caller holding a Verification may use either — and should use this one.\n */\nexport function tallyRecord(v: Verification): RecordTally {\n  return tallyAnswers(v.claims, v.summary.unanswered ?? 0);\n}\n\n/**\n * Three states, because two were a lie. `verified` is the strong claim — every\n * question answered, every answer confirmed, and every scenario answered by a\n * digest-matched green run. `attested` is the same completeness resting, for at\n * least one scenario, on an agent's word. `unverified` is everything else:\n * nothing recorded, a record gone stale, a claim unanswered or unconfirmed, or\n * a checklist that asks nothing at all.\n */\nexport const VERIFICATION_VERDICTS = [\"verified\", \"attested\", \"unverified\"] as const;\nexport type VerificationVerdict = (typeof VERIFICATION_VERDICTS)[number];\n\nexport function verificationVerdict(t: RecordTally, stale = false): VerificationVerdict {\n  if (stale || t.claims === 0 || t.confirmed !== t.claims) return \"unverified\";\n  return t.attested > 0 ? \"attested\" : \"verified\";\n}\n\n/** A finding a verify surface reports about a record. Stable code, prose that may change. */\nexport interface VerifyNotice {\n  code: string;\n  severity: \"warn\";\n  message: string;\n  /** The claims it is about, when it is about claims. */\n  claims?: string[];\n}\n\n/**\n * The one notice `verify`, `list` and `status` all show: this record's scenario\n * claims were confirmed without a run.\n *\n * It is a warning and it gates nothing — verify has never gated, and a service\n * with no suite yet has to be able to ship. What it must never do is read the\n * same as a green run.\n */\nexport function attestedNotice(claims: readonly AnsweredClaim[], feature: string): VerifyNotice | null {\n  const ids = attestedClaims(claims);\n  if (ids.length === 0) return null;\n  return {\n    code: \"verify.scenario-attested\",\n    severity: \"warn\",\n    message:\n      `${ids.length} scenario claim(s) are confirmed on an agent's word, not on a test run: ${ids.join(\", \")}. ` +\n      `Answer them mechanically once the suite runs: \\`loam verify ${feature} --results <cucumber.json>\\`.`,\n    claims: ids,\n  };\n}\n\n/**\n * The one-line honesty summary of a record that leaves claims open: partial is\n * not a clean result, and the counts alone did not say so — `summary` carries\n * them on every surface, and a reader skimming for the ⚠ lines shipped a\n * half-answered record as done anyway. Null when nothing is open, and the\n * callers fire it only when a record EXISTS: a feature with no record already\n * says \"Not verified\", and calling that \"not a clean result\" would conflate\n * not-started with partial. A pure-attested record (all confirmed, some on an\n * agent's word) never reaches the message either — its counts are closed, and\n * `attestedNotice` above owns that honesty; two notices about one fact is the\n * double-reporting this file's notices exist to prevent.\n */\nexport function openClaimsNotice(tally: RecordTally, feature: string): VerifyNotice | null {\n  const open = tally.unconfirmed + tally.unanswered;\n  if (open === 0) return null;\n  return {\n    code: \"verify.claims-open\",\n    severity: \"warn\",\n    message:\n      `not a clean result: of ${tally.claims} claim(s), ${tally.confirmed} confirmed` +\n      (tally.attested > 0 ? ` (${tally.attested} on an agent's word)` : \"\") +\n      `, ${tally.unconfirmed} unconfirmed, ${tally.unanswered} unanswered — ` +\n      `treat ${feature} as unverified until every claim is answered and confirmed.`,\n  };\n}\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 */\nexport function verificationPath(featureDir: string): string {\n  return join(featureDir, \"verification.yaml\");\n}\n\n"]}

package/dist/core/verify/store/commit.js

@@ -0,0 +1,89 @@
+/**
+ * The verification record's commit: staged beside the target, compared against
+ * the byte pre-image the merge consumed, swapped in by one rename(2).
+ *
+ * The record used to go down as a plain `writeFile`, which cost three ways at
+ * once: two `--record` runs read the same pre-image and the last writer
+ * silently discarded the other service's attestation; a process killed
+ * mid-write left the ONLY copy truncated, unreadable, and blocking every later
+ * record; and an edit that landed between the read and the write was buried
+ * under bytes computed from a document that no longer existed. The docs lock
+ * (taken by `loam verify` before its authoritative read) closes the first;
+ * this module closes the other two, and backstops the lock itself for a writer
+ * that never took it.
+ *
+ * A sub-package of core/verify rather than a sixth file in it, and a consumer
+ * of core/staging's primitives rather than a re-implementation: `stageWrites`
+ * and `swapStaged` already do temp-beside-target, whole-content compare-and-set
+ * and same-directory rename — vouch commits through exactly this shape.
+ */
+import { message, rollbackMessage, rollbackStaged, stageWrites, StagingRaceError, swapStaged } from "../../staging/commit.js";
+import { repoPath } from "../../envelope/json.js";
+import {} from "../../staging/writes.js";
+import { renderVerification } from "./render.js";
+import { verificationPath } from "../record.js";
+/**
+ * `preImage` is the exact bytes the caller's merge was computed from, or null
+ * when the record was absent at the authoritative read — in which case the
+ * commit may only CREATE (link(2) refuses a file that appeared since), never
+ * replace one it has not read.
+ */
+export async function commitVerification(featureDir, v, preImage, docsDir) {
+    const path = verificationPath(featureDir);
+    const display = repoPath(docsDir, path);
+    const write = preImage === null ? { path, content: renderVerification(v), exclusive: true } : { path, content: renderVerification(v) };
+    // Staging touches the filesystem — a read-only feature directory, a full
+    // disk, a pre-image that will not read. None of that is a bug in loam, and
+    // letting it escape as `internal` sends the reader looking for one (archive
+    // draws the same line around its own `stageWrites`). Nothing was written.
+    let staged;
+    try {
+        staged = await stageWrites([write]);
+    }
+    catch (err) {
+        return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
+    }
+    // Joined by path, not by index — vouch's rule, for vouch's reason: one entry
+    // per planned write in order is true today and promised nowhere, and a
+    // compare-and-set over the wrong pair would vouch for bytes the merge never
+    // saw. A missing entry fails closed as a merge that never happened.
+    const s = staged.find((x) => x.write.path === path);
+    if (s === undefined) {
+        await rollbackStaged(staged);
+        return { ok: false, code: "merge-failed", message: `staging returned no entry for ${display} — nothing was recorded` };
+    }
+    // The compare the read promised: the file as staging found it must be the
+    // file the merge consumed. `swapStaged` re-checks against ITS read just
+    // before the rename, so together the two compares cover the whole window
+    // from the authoritative read to the swap.
+    const edited = preImage === null ? s.before !== null : s.before === null || !s.before.equals(preImage);
+    if (edited) {
+        await rollbackStaged(staged);
+        return { ok: false, code: "record-raced", message: racedMessage(display) };
+    }
+    try {
+        await swapStaged(staged);
+    }
+    catch (err) {
+        const failures = await rollbackStaged(staged);
+        if (failures.length > 0) {
+            return {
+                ok: false,
+                code: "rollback-incomplete",
+                message: rollbackMessage(err, failures, "written"),
+            };
+        }
+        // EEXIST is the exclusive create losing its race — same fact as the CAS
+        // refusal, discovered by link(2) instead of by the compare.
+        if (err instanceof StagingRaceError || err.code === "EEXIST") {
+            return { ok: false, code: "record-raced", message: racedMessage(display) };
+        }
+        return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
+    }
+    return { ok: true, path };
+}
+function racedMessage(display) {
+    return (`${display} changed while this record was being written — another writer or an editor landed between the read and the write. ` +
+        "Nothing was written and their bytes are untouched. Re-run: the merge is recomputed over the record as it now stands.");
+}
+//# sourceMappingURL=commit.js.map

package/dist/core/verify/store/commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../../src/core/verify/store/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The verification record's commit: staged beside the target, compared against\n * the byte pre-image the merge consumed, swapped in by one rename(2).\n *\n * The record used to go down as a plain `writeFile`, which cost three ways at\n * once: two `--record` runs read the same pre-image and the last writer\n * silently discarded the other service's attestation; a process killed\n * mid-write left the ONLY copy truncated, unreadable, and blocking every later\n * record; and an edit that landed between the read and the write was buried\n * under bytes computed from a document that no longer existed. The docs lock\n * (taken by `loam verify` before its authoritative read) closes the first;\n * this module closes the other two, and backstops the lock itself for a writer\n * that never took it.\n *\n * A sub-package of core/verify rather than a sixth file in it, and a consumer\n * of core/staging's primitives rather than a re-implementation: `stageWrites`\n * and `swapStaged` already do temp-beside-target, whole-content compare-and-set\n * and same-directory rename — vouch commits through exactly this shape.\n */\nimport { message, rollbackMessage, rollbackStaged, stageWrites, StagingRaceError, swapStaged } from \"../../staging/commit.js\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { type PlannedWrite, type StagedWrite } from \"../../staging/writes.js\";\nimport { renderVerification } from \"./render.js\";\nimport { verificationPath, type Verification } from \"../record.js\";\n\n/**\n * `record-raced` re-runs cleanly: the merge is recomputed over whatever the\n * other writer left. The other two are staging's own vocabulary, with staging's\n * meanings — `merge-failed` trusts the repo, `rollback-incomplete` does not.\n */\nexport type VerificationCommit =\n  | { ok: true; path: string }\n  | { ok: false; code: \"record-raced\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * `preImage` is the exact bytes the caller's merge was computed from, or null\n * when the record was absent at the authoritative read — in which case the\n * commit may only CREATE (link(2) refuses a file that appeared since), never\n * replace one it has not read.\n */\nexport async function commitVerification(\n  featureDir: string,\n  v: Verification,\n  preImage: Buffer | null,\n  docsDir: string,\n): Promise<VerificationCommit> {\n  const path = verificationPath(featureDir);\n  const display = repoPath(docsDir, path);\n  const write: PlannedWrite =\n    preImage === null ? { path, content: renderVerification(v), exclusive: true } : { path, content: renderVerification(v) };\n  // Staging touches the filesystem — a read-only feature directory, a full\n  // disk, a pre-image that will not read. None of that is a bug in loam, and\n  // letting it escape as `internal` sends the reader looking for one (archive\n  // draws the same line around its own `stageWrites`). Nothing was written.\n  let staged: StagedWrite[];\n  try {\n    staged = await stageWrites([write]);\n  } catch (err) {\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  // Joined by path, not by index — vouch's rule, for vouch's reason: one entry\n  // per planned write in order is true today and promised nowhere, and a\n  // compare-and-set over the wrong pair would vouch for bytes the merge never\n  // saw. A missing entry fails closed as a merge that never happened.\n  const s = staged.find((x) => x.write.path === path);\n  if (s === undefined) {\n    await rollbackStaged(staged);\n    return { ok: false, code: \"merge-failed\", message: `staging returned no entry for ${display} — nothing was recorded` };\n  }\n  // The compare the read promised: the file as staging found it must be the\n  // file the merge consumed. `swapStaged` re-checks against ITS read just\n  // before the rename, so together the two compares cover the whole window\n  // from the authoritative read to the swap.\n  const edited = preImage === null ? s.before !== null : s.before === null || !s.before.equals(preImage);\n  if (edited) {\n    await rollbackStaged(staged);\n    return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n  }\n  try {\n    await swapStaged(staged);\n  } catch (err) {\n    const failures = await rollbackStaged(staged);\n    if (failures.length > 0) {\n      return {\n        ok: false,\n        code: \"rollback-incomplete\",\n        message: rollbackMessage(err, failures, \"written\"),\n      };\n    }\n    // EEXIST is the exclusive create losing its race — same fact as the CAS\n    // refusal, discovered by link(2) instead of by the compare.\n    if (err instanceof StagingRaceError || (err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n    }\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  return { ok: true, path };\n}\n\nfunction racedMessage(display: string): string {\n  return (\n    `${display} changed while this record was being written — another writer or an editor landed between the read and the write. ` +\n    \"Nothing was written and their bytes are untouched. Re-run: the merge is recomputed over the record as it now stands.\"\n  );\n}\n"]}