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

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

@@ -0,0 +1,224 @@
+/**
+ * The verification record read back, and refused when it cannot be trusted.
+ *
+ * The record is several files now: the one-file `verification.yaml` (the
+ * all-at-once form, and every federated record written before the directory
+ * existed) and one `verification/<svc>.yaml` per attesting service. Each file
+ * is graded on its own here, and `./union.ts` adds the graded files up
+ * into the one `Verification` every reader takes — so no reader learns the
+ * layout, and a record that is half one form and half the other reads as one
+ * record.
+ *
+ * Reading is deliberately not the inverse of rendering. A file loam wrote is
+ * re-graded on the way in — git conflict markers, unreadable YAML, a shape that
+ * is not a verification, a `summary` that disagrees with the claims below it —
+ * because the record 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.
+ *
+ * A package of its own (`core/verify/read/`, moved from `core/verify/file.ts`)
+ * because the reader now leans on two modules that lean back on
+ * `../record.ts`: kept in `core/verify` beside them it would have been a
+ * package cycle that `import/no-cycle` cannot see.
+ */
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { conflictMarkerLines } from "../../conflict-markers.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { verificationDir, verificationPath } from "../location.js";
+import {} from "../record.js";
+import { asVerification, summaryDisagreement } from "./shape.js";
+import { assembleRecord } from "./union.js";
+/**
+ * `live` is the digest of the checklist the caller knows is being asked — see
+ * `assembleRecord` for why the union needs it. A caller that only learns it
+ * after the read (it derives the checklist only when there IS a record) adds
+ * the same files up again with {@link answering} instead of reading twice.
+ */
+export async function readVerificationState(featureDir, live) {
+    const legacy = await readRecordFile(verificationPath(featureDir), null);
+    if (legacy.state === "unreadable")
+        return legacy;
+    const listed = await serviceFiles(featureDir);
+    if (!Array.isArray(listed))
+        return listed;
+    // In parallel — the files are independent, and a fleet-sized feature has
+    // one per service — but graded in the listing's sorted order, so the file a
+    // refusal names is the first unreadable one by name on every machine, never
+    // whichever read happened to fail first.
+    const reads = await inOrder(listed, ({ service, path }) => readRecordFile(path, service));
+    const services = new Map();
+    for (const [i, read] of reads.entries()) {
+        if (read.state === "unreadable")
+            return read;
+        // Listed and then gone is a file a concurrent writer removed: absent.
+        if (read.state === "ok")
+            services.set(listed[i].service, read.file);
+    }
+    const files = { legacy: legacy.state === "ok" ? legacy.file : null, services };
+    const verification = answering(files, live);
+    if (verification === null)
+        return { state: "absent" };
+    return { state: "ok", verification, files };
+}
+/**
+ * The record's files added up for the checklist `live` asks — what
+ * {@link readVerificationState} answers, and what it would have answered for a
+ * caller that only learned `live` after the read. Pure: the files are the ones
+ * that read already graded. Null only when there are no files at all.
+ */
+export function answering(files, live) {
+    return assembleRecord(files.legacy?.verification ?? null, [...files.services.values()].map((file) => file.verification), live);
+}
+/**
+ * The per-service files, sorted by service id so the union is the same on
+ * every machine. Dotfiles are skipped — staging parks its temp files beside
+ * the target as `.<name>.loam-….tmp`, and a reader racing a writer must not
+ * grade one — and so is anything that is not `*.yaml`: the directory is the
+ * list of attestations, and a README beside them is not one.
+ */
+async function serviceFiles(featureDir) {
+    const dir = verificationDir(featureDir);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        return {
+            state: "unreadable",
+            path: dir,
+            reason: err instanceof Error ? err.message : String(err),
+            advice: "It has to be a directory holding one <svc>.yaml per attesting service; move whatever is there aside, then record again.",
+        };
+    }
+    return entries
+        .filter((e) => !e.name.startsWith(".") && e.name.endsWith(".yaml") && !e.isDirectory())
+        .map((e) => ({ service: e.name.slice(0, -".yaml".length), path: join(dir, e.name) }))
+        .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));
+}
+/**
+ * The recipe for a file loam could not use. See {@link VerificationRead} for
+ * why the two kinds of file get different ones. Neither tells anybody to edit
+ * the counts — a summary made to agree by hand still says nothing about what
+ * was checked — and both end in a record that can actually run: the old
+ * one-size "record the answers again" sent a miscounted record straight back
+ * into this refusal, because `--record` will not write over a file it could
+ * not read.
+ */
+function adviceFor(service) {
+    if (service !== null) {
+        return (`It is ${service}'s attestation file and holds no other service's word: repair it by hand, or delete it and ` +
+            `record ${service} again from that service's own repository (\`--service ${service} --record\`). ` +
+            "After a merge, both sides of a conflict in it are that one service's attestations.");
+    }
+    return ("It may hold other services' attestations, so do not delete it: repair it by hand, or restore it from version " +
+        "control — after a merge, take the copy on the branch you merged into — and then record again. A `--service` " +
+        "record goes to verification/<svc>.yaml beside it and leaves this file as it is.");
+}
+/**
+ * One file of the record, graded. `service` is the file's own service for a
+ * `verification/<svc>.yaml` — the file NAME is the claim about whose word it
+ * holds, so the content has to agree with it — and null for the one-file
+ * record.
+ */
+async function readRecordFile(path, service) {
+    // The code rides in an object, as a `code:` property, rather than as a
+    // parameter: a parameter named `code` makes this helper an emitter to the
+    // stable-code collector, which then cannot read the slot at the call sites
+    // that leave it out.
+    const unreadable = (reason, coded = {}) => ({
+        state: "unreadable",
+        path,
+        reason,
+        advice: adviceFor(service),
+        ...coded,
+    });
+    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 unreadable("it is a symlink whose target does not exist — replace the link with a real record, or remove it");
+            }
+            return unreadable("it appeared while being read — another writer is landing; re-run");
+        }
+        return unreadable(err instanceof Error ? err.message : String(err));
+    }
+    const text = raw.toString("utf8");
+    // Before the parser, because the parser's answer to a merge is the wrong
+    // one: YAML either fails on a line that is not the problem or — where the
+    // markers land inside a block scalar — reads both sides as one plausible
+    // document. Neither says "a merge left this", which is the one sentence that
+    // leads to the right fix.
+    const markers = conflictMarkerLines(text);
+    if (markers.length > 0) {
+        return unreadable(`it still contains git conflict markers (line${markers.length === 1 ? "" : "s"} ${markers.join(", ")}) — ` +
+            "a merge left both sides in it, so nothing it says is anyone's record");
+    }
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    catch (err) {
+        return unreadable(yamlReason(err));
+    }
+    const verification = asVerification(doc);
+    if (verification === null) {
+        return unreadable("it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)");
+    }
+    const foreign = service === null ? null : notOnlyFrom(verification, service);
+    if (foreign !== null)
+        return unreadable(foreign);
+    const miscount = summaryDisagreement(verification);
+    // Spelled twice on purpose: the field is what a caller branches on, the
+    // prose is what a terminal prints and what somebody greps for.
+    if (miscount !== null)
+        return unreadable(`verify.record-miscounted: ${miscount}`, { code: "verify.record-miscounted" });
+    return { state: "ok", file: { path, verification, raw } };
+}
+/**
+ * A per-service file must be exactly what its name says: a federated record
+ * carrying that one service's attestation and that service's answers. loam
+ * never writes anything else there, and the advice for a damaged file — delete
+ * it and record that service again — is only safe while it is true.
+ */
+function notOnlyFrom(v, service) {
+    const attested = (v.attestations ?? []).map((a) => a.service);
+    if (v.schema !== 2 || attested.length !== 1 || attested[0] !== service) {
+        return `it is named for ${service} but does not hold exactly ${service}'s attestation (it holds ${attested.length === 0 ? "none" : attested.join(", ")})`;
+    }
+    const strays = v.claims.filter((c) => c.subject !== service).map((c) => c.id);
+    return strays.length === 0 ? null : `it is named for ${service} but answers claims filed under another service: ${strays.join(", ")}`;
+}
+/** 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}`;
+}
+//# sourceMappingURL=file.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../../src/core/verify/read/file.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The verification record read back, and refused when it cannot be trusted.\n *\n * The record is several files now: the one-file `verification.yaml` (the\n * all-at-once form, and every federated record written before the directory\n * existed) and one `verification/<svc>.yaml` per attesting service. Each file\n * is graded on its own here, and `./union.ts` adds the graded files up\n * into the one `Verification` every reader takes — so no reader learns the\n * layout, and a record that is half one form and half the other reads as one\n * record.\n *\n * Reading is deliberately not the inverse of rendering. A file loam wrote is\n * re-graded on the way in — git conflict markers, unreadable YAML, a shape that\n * is not a verification, a `summary` that disagrees with the claims below it —\n * because the record is data meant to survive without loam, and anything may\n * have edited it since. The render lives with the writer it feeds\n * (`../store/render.ts` produces exactly the bytes `../store/commit.ts` swaps into\n * place; races and kills mid-write live there too), and the lock that\n * serialises writers is taken by `commands/verify/verify.ts` before this\n * module's authoritative read. Nothing here touches the filesystem except to\n * read.\n *\n * A package of its own (`core/verify/read/`, moved from `core/verify/file.ts`)\n * because the reader now leans on two modules that lean back on\n * `../record.ts`: kept in `core/verify` beside them it would have been a\n * package cycle that `import/no-cycle` cannot see.\n */\nimport { lstat, readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { parse } from \"yaml\";\nimport { conflictMarkerLines } from \"../../conflict-markers.js\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { verificationDir, verificationPath } from \"../location.js\";\nimport { type Verification } from \"../record.js\";\nimport { asVerification, summaryDisagreement } from \"./shape.js\";\nimport { assembleRecord } from \"./union.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   * `path` is the ONE file that failed — with several files making up the\n   * record, \"the record is unreadable\" names nothing a person can open.\n   * `reason` names the YAML line when the parser gave one, or the conflict\n   * markers' lines. `advice` is the recipe, and it differs by file on purpose:\n   * a `verification/<svc>.yaml` holds one service's word, so deleting it and\n   * recording that service again loses nobody else's evidence, while the\n   * one-file record may hold a whole fleet's attestations and must never be\n   * the file a recipe tells somebody to delete. `code` is set for the one\n   * unreadable that parses perfectly: a file whose `summary` contradicts its\n   * own `claims[]`. That lives here rather than in a state of its own so every\n   * reader which already refuses an unreadable record refuses this one too,\n   * without a line of new code.\n   */\n  | { state: \"unreadable\"; path: string; reason: string; advice: string; code?: \"verify.record-miscounted\" }\n  /**\n   * `verification` is the union the readers use; `files` is what it was added\n   * up from, each with the exact bytes it was parsed from. A writer merges over\n   * the PARSE, but commits over the BYTES: `commitVerification` compares each\n   * file it replaces or deletes against these immediately before its swap, so\n   * an edit that landed between this read and that write — an editor, a writer\n   * that ignored the docs lock — is refused and preserved instead of silently\n   * buried.\n   */\n  | { state: \"ok\"; verification: Verification; files: RecordFiles };\n\n/** One graded file of the record, with the bytes it was graded from. */\nexport interface RecordFile {\n  path: string;\n  verification: Verification;\n  raw: Buffer;\n}\n\n/** The files a record was added up from: the one-file form, and the per-service files by service id. */\nexport interface RecordFiles {\n  legacy: RecordFile | null;\n  services: ReadonlyMap<string, RecordFile>;\n}\n\ntype Unreadable = Extract<VerificationRead, { state: \"unreadable\" }>;\ntype FileRead = { state: \"absent\" } | Unreadable | { state: \"ok\"; file: RecordFile };\n\n/**\n * `live` is the digest of the checklist the caller knows is being asked — see\n * `assembleRecord` for why the union needs it. A caller that only learns it\n * after the read (it derives the checklist only when there IS a record) adds\n * the same files up again with {@link answering} instead of reading twice.\n */\nexport async function readVerificationState(featureDir: string, live?: string): Promise<VerificationRead> {\n  const legacy = await readRecordFile(verificationPath(featureDir), null);\n  if (legacy.state === \"unreadable\") return legacy;\n  const listed = await serviceFiles(featureDir);\n  if (!Array.isArray(listed)) return listed;\n  // In parallel — the files are independent, and a fleet-sized feature has\n  // one per service — but graded in the listing's sorted order, so the file a\n  // refusal names is the first unreadable one by name on every machine, never\n  // whichever read happened to fail first.\n  const reads = await inOrder(listed, ({ service, path }) => readRecordFile(path, service));\n  const services = new Map<string, RecordFile>();\n  for (const [i, read] of reads.entries()) {\n    if (read.state === \"unreadable\") return read;\n    // Listed and then gone is a file a concurrent writer removed: absent.\n    if (read.state === \"ok\") services.set(listed[i]!.service, read.file);\n  }\n  const files: RecordFiles = { legacy: legacy.state === \"ok\" ? legacy.file : null, services };\n  const verification = answering(files, live);\n  if (verification === null) return { state: \"absent\" };\n  return { state: \"ok\", verification, files };\n}\n\n/**\n * The record's files added up for the checklist `live` asks — what\n * {@link readVerificationState} answers, and what it would have answered for a\n * caller that only learned `live` after the read. Pure: the files are the ones\n * that read already graded. Null only when there are no files at all.\n */\nexport function answering(files: RecordFiles, live: string | undefined): Verification | null {\n  return assembleRecord(\n    files.legacy?.verification ?? null,\n    [...files.services.values()].map((file) => file.verification),\n    live,\n  );\n}\n\n/**\n * The per-service files, sorted by service id so the union is the same on\n * every machine. Dotfiles are skipped — staging parks its temp files beside\n * the target as `.<name>.loam-….tmp`, and a reader racing a writer must not\n * grade one — and so is anything that is not `*.yaml`: the directory is the\n * list of attestations, and a README beside them is not one.\n */\nasync function serviceFiles(featureDir: string): Promise<Array<{ service: string; path: string }> | Unreadable> {\n  const dir = verificationDir(featureDir);\n  let entries;\n  try {\n    entries = await readdir(dir, { withFileTypes: true });\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n    return {\n      state: \"unreadable\",\n      path: dir,\n      reason: err instanceof Error ? err.message : String(err),\n      advice: \"It has to be a directory holding one <svc>.yaml per attesting service; move whatever is there aside, then record again.\",\n    };\n  }\n  return entries\n    .filter((e) => !e.name.startsWith(\".\") && e.name.endsWith(\".yaml\") && !e.isDirectory())\n    .map((e) => ({ service: e.name.slice(0, -\".yaml\".length), path: join(dir, e.name) }))\n    .sort((a, b) => (a.service < b.service ? -1 : a.service > b.service ? 1 : 0));\n}\n\n/**\n * The recipe for a file loam could not use. See {@link VerificationRead} for\n * why the two kinds of file get different ones. Neither tells anybody to edit\n * the counts — a summary made to agree by hand still says nothing about what\n * was checked — and both end in a record that can actually run: the old\n * one-size \"record the answers again\" sent a miscounted record straight back\n * into this refusal, because `--record` will not write over a file it could\n * not read.\n */\nfunction adviceFor(service: string | null): string {\n  if (service !== null) {\n    return (\n      `It is ${service}'s attestation file and holds no other service's word: repair it by hand, or delete it and ` +\n      `record ${service} again from that service's own repository (\\`--service ${service} --record\\`). ` +\n      \"After a merge, both sides of a conflict in it are that one service's attestations.\"\n    );\n  }\n  return (\n    \"It may hold other services' attestations, so do not delete it: repair it by hand, or restore it from version \" +\n    \"control — after a merge, take the copy on the branch you merged into — and then record again. A `--service` \" +\n    \"record goes to verification/<svc>.yaml beside it and leaves this file as it is.\"\n  );\n}\n\n/**\n * One file of the record, graded. `service` is the file's own service for a\n * `verification/<svc>.yaml` — the file NAME is the claim about whose word it\n * holds, so the content has to agree with it — and null for the one-file\n * record.\n */\nasync function readRecordFile(path: string, service: string | null): Promise<FileRead> {\n  // The code rides in an object, as a `code:` property, rather than as a\n  // parameter: a parameter named `code` makes this helper an emitter to the\n  // stable-code collector, which then cannot read the slot at the call sites\n  // that leave it out.\n  const unreadable = (reason: string, coded: { code?: \"verify.record-miscounted\" } = {}): Unreadable => ({\n    state: \"unreadable\",\n    path,\n    reason,\n    advice: adviceFor(service),\n    ...coded,\n  });\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 unreadable(\"it is a symlink whose target does not exist — replace the link with a real record, or remove it\");\n      }\n      return unreadable(\"it appeared while being read — another writer is landing; re-run\");\n    }\n    return unreadable(err instanceof Error ? err.message : String(err));\n  }\n  const text = raw.toString(\"utf8\");\n  // Before the parser, because the parser's answer to a merge is the wrong\n  // one: YAML either fails on a line that is not the problem or — where the\n  // markers land inside a block scalar — reads both sides as one plausible\n  // document. Neither says \"a merge left this\", which is the one sentence that\n  // leads to the right fix.\n  const markers = conflictMarkerLines(text);\n  if (markers.length > 0) {\n    return unreadable(\n      `it still contains git conflict markers (line${markers.length === 1 ? \"\" : \"s\"} ${markers.join(\", \")}) — ` +\n        \"a merge left both sides in it, so nothing it says is anyone's record\",\n    );\n  }\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch (err) {\n    return unreadable(yamlReason(err));\n  }\n  const verification = asVerification(doc);\n  if (verification === null) {\n    return unreadable(\n      \"it parses as YAML but does not have a verification record's shape (feature, recorded, checklist, summary and claims)\",\n    );\n  }\n  const foreign = service === null ? null : notOnlyFrom(verification, service);\n  if (foreign !== null) return unreadable(foreign);\n  const miscount = summaryDisagreement(verification);\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  if (miscount !== null) return unreadable(`verify.record-miscounted: ${miscount}`, { code: \"verify.record-miscounted\" });\n  return { state: \"ok\", file: { path, verification, raw } };\n}\n\n/**\n * A per-service file must be exactly what its name says: a federated record\n * carrying that one service's attestation and that service's answers. loam\n * never writes anything else there, and the advice for a damaged file — delete\n * it and record that service again — is only safe while it is true.\n */\nfunction notOnlyFrom(v: Verification, service: string): string | null {\n  const attested = (v.attestations ?? []).map((a) => a.service);\n  if (v.schema !== 2 || attested.length !== 1 || attested[0] !== service) {\n    return `it is named for ${service} but does not hold exactly ${service}'s attestation (it holds ${attested.length === 0 ? \"none\" : attested.join(\", \")})`;\n  }\n  const strays = v.claims.filter((c) => c.subject !== service).map((c) => c.id);\n  return strays.length === 0 ? null : `it is named for ${service} but answers claims filed under another service: ${strays.join(\", \")}`;\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"]}

package/dist/core/verify/read/shape.js

@@ -0,0 +1,169 @@
+/**
+ * What a file must hold to be a verification record — the shape check and the
+ * self-consistency check every file of the record passes on the way in.
+ *
+ * Moved out of `./file.ts` when the record became several files: that module
+ * now owns WHICH files make up a record and how a damaged one is reported,
+ * while this one owns what any single file has to say to be read at all. The
+ * two are phases — find the files, then grade each — and the grading never
+ * needed to know where its bytes came from.
+ */
+import { isRecord } from "../../kernel/records.js";
+import { VERDICTS } from "../answers.js";
+import { isEvidencePinList } from "../pins/pin.js";
+import { tallyAnswers } from "../record.js";
+/**
+ * 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.
+ */
+export 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`;
+}
+/**
+ * The shape check `readVerificationState` (`./file.ts`) 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.
+ */
+export 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=shape.js.map

package/dist/core/verify/read/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../../src/core/verify/read/shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a file must hold to be a verification record — the shape check and the\n * self-consistency check every file of the record passes on the way in.\n *\n * Moved out of `./file.ts` when the record became several files: that module\n * now owns WHICH files make up a record and how a damaged one is reported,\n * while this one owns what any single file has to say to be read at all. The\n * two are phases — find the files, then grade each — and the grading never\n * needed to know where its bytes came from.\n */\nimport { isRecord } from \"../../kernel/records.js\";\nimport { VERDICTS } from \"../answers.js\";\nimport { isEvidencePinList } from \"../pins/pin.js\";\nimport { tallyAnswers, type Verification } from \"../record.js\";\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 */\nexport function 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/**\n * The shape check `readVerificationState` (`./file.ts`) stands behind:\n * 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 */\nexport function 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"]}

package/dist/core/verify/read/union.js

@@ -0,0 +1,105 @@
+/**
+ * The record as the union of its files: the one-file `verification.yaml` and
+ * one `verification/<svc>.yaml` per attesting service, added up into the single
+ * `Verification` every reader already takes.
+ *
+ * Pure on purpose — `./file.ts` reads and grades the bytes, the writer in
+ * `commands/verify/record.ts` hands in the files as they will stand after its
+ * commit, and both get the same answer from the same arithmetic. A writer that
+ * computed the post-record verdict its own way would be the second opinion
+ * `../record.ts` exists to prevent; this way what `--record` prints is exactly
+ * what the next read will say.
+ *
+ * Nothing here reads a `summary` as fact. Each file's own `summary` was graded
+ * against its own `claims[]` on the way in, and the union's is recomputed here
+ * from the claims it actually counts — so the block that used to be the
+ * hottest conflict in a fleet's docs PRs is now derived, never merged.
+ */
+import { tallyAnswers } from "../record.js";
+/**
+ * Add the files up. `services` are the graded per-service files, each a
+ * schema-2 record holding exactly its own service's attestation (the reader
+ * refuses one that does not). Null only when there is nothing at all.
+ *
+ * With no per-service file the one-file record is returned VERBATIM — a record
+ * written before the directory existed, or by the all-at-once form, reads
+ * exactly as it always did, retained answers and all.
+ *
+ * Otherwise the record answers ONE version of the checklist. A file that
+ * answered a different version keeps its attestation on the list — that is
+ * what `verify.checklist-forked` reads to name it — but its answers do not
+ * count. The single shared file used to settle this by rewriting: the last
+ * writer pruned everybody's answers to ITS checklist. Per-service files are
+ * never rewritten by anyone else, so nothing can prune them, and counting an
+ * answer filed against another question set would let an old id that the
+ * feature no longer asks fill the slot of a new one it does — a record reading
+ * `verified` over a question nobody answered. Excluding is the honest half:
+ * the service behind is named, and recording it again is the whole fix.
+ *
+ * WHICH version is `live`'s to say whenever the caller knows it: the digest of
+ * the checklist the feature asks now (`loam verify`, its writer, `tasks`, and
+ * `status`/`list`/`gate` for an in-flight feature all derive it anyway), or
+ * the one `loam archive` captured as it merged. The files that answered it
+ * count. Only when no caller knows — the frozen view of an archived feature
+ * with no capture — or when no file answered it does the newest file decide
+ * (by `recorded`, a later service id breaking a same-day tie, and any
+ * per-service file outranking the one-file record). Newest-by-date used to
+ * decide always, and `recorded` is a DATE: a service recording this morning
+ * against the current checklist lost the tie to a service with a later id that
+ * recorded an older checklist an hour before — or a day later, from a docs
+ * branch that was behind — so the current answers were dropped, every reader
+ * called the record stale, and the writer printed a tally its own answers were
+ * not in.
+ */
+export function assembleRecord(legacy, services, live) {
+    if (services.length === 0)
+        return legacy;
+    const filed = new Set(services.flatMap((s) => (s.attestations ?? []).map((a) => a.service)));
+    const parts = [...legacyRemnant(legacy, filed), ...services];
+    // The question being asked now, when somebody answered it; every part only
+    // when nobody did — then the record is stale under every reader whichever
+    // part represents it, and the newest is the one a reader recognises.
+    const answering = live === undefined ? [] : parts.filter((part) => part.checklist === live);
+    const pool = answering.length > 0 ? answering : parts;
+    // `>=` so a later part wins a same-day tie: services arrive sorted by id,
+    // and after the one-file remnant, which is exactly the precedence above.
+    const current = pool.reduce((newest, part) => (part.recorded >= newest.recorded ? part : newest));
+    const claims = parts.filter((part) => part.checklist === current.checklist).flatMap((part) => part.claims);
+    const tally = tallyAnswers(claims);
+    return {
+        schema: 2,
+        feature: current.feature,
+        recorded: current.recorded,
+        checklist: current.checklist,
+        summary: {
+            claims: current.summary.claims,
+            confirmed: tally.confirmed,
+            unconfirmed: tally.unconfirmed,
+            unanswered: current.summary.claims - claims.length,
+        },
+        claims,
+        attestations: parts.flatMap((part) => part.attestations ?? []).sort((a, b) => a.service.localeCompare(b.service)),
+    };
+}
+/**
+ * What of the one-file record still counts once services have files of their
+ * own: the attestations of the services that have NOT re-recorded since, and
+ * their answers.
+ *
+ * A schema-1 (all-at-once) file contributes nothing. Its answers carry no
+ * commit attestation, so a federated record could never count them — the rule
+ * the first federated write applied when it used to overwrite the file, and the
+ * reason that write now deletes it. A schema-2 file's attestation for a service
+ * that has a file of its own is superseded by that file and drops out, answers
+ * with it; when every attestation in it is superseded, nothing in it counts.
+ */
+function legacyRemnant(legacy, filed) {
+    if (legacy === null || legacy.schema !== 2)
+        return [];
+    const attestations = (legacy.attestations ?? []).filter((a) => !filed.has(a.service));
+    if (attestations.length === 0)
+        return [];
+    const kept = new Set(attestations.map((a) => a.service));
+    return [{ ...legacy, attestations, claims: legacy.claims.filter((c) => c.subject !== undefined && kept.has(c.subject)) }];
+}
+//# sourceMappingURL=union.js.map

package/dist/core/verify/read/union.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"union.js","sourceRoot":"","sources":["../../../../src/core/verify/read/union.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The record as the union of its files: the one-file `verification.yaml` and\n * one `verification/<svc>.yaml` per attesting service, added up into the single\n * `Verification` every reader already takes.\n *\n * Pure on purpose — `./file.ts` reads and grades the bytes, the writer in\n * `commands/verify/record.ts` hands in the files as they will stand after its\n * commit, and both get the same answer from the same arithmetic. A writer that\n * computed the post-record verdict its own way would be the second opinion\n * `../record.ts` exists to prevent; this way what `--record` prints is exactly\n * what the next read will say.\n *\n * Nothing here reads a `summary` as fact. Each file's own `summary` was graded\n * against its own `claims[]` on the way in, and the union's is recomputed here\n * from the claims it actually counts — so the block that used to be the\n * hottest conflict in a fleet's docs PRs is now derived, never merged.\n */\nimport { tallyAnswers, type Verification } from \"../record.js\";\n\n/**\n * Add the files up. `services` are the graded per-service files, each a\n * schema-2 record holding exactly its own service's attestation (the reader\n * refuses one that does not). Null only when there is nothing at all.\n *\n * With no per-service file the one-file record is returned VERBATIM — a record\n * written before the directory existed, or by the all-at-once form, reads\n * exactly as it always did, retained answers and all.\n *\n * Otherwise the record answers ONE version of the checklist. A file that\n * answered a different version keeps its attestation on the list — that is\n * what `verify.checklist-forked` reads to name it — but its answers do not\n * count. The single shared file used to settle this by rewriting: the last\n * writer pruned everybody's answers to ITS checklist. Per-service files are\n * never rewritten by anyone else, so nothing can prune them, and counting an\n * answer filed against another question set would let an old id that the\n * feature no longer asks fill the slot of a new one it does — a record reading\n * `verified` over a question nobody answered. Excluding is the honest half:\n * the service behind is named, and recording it again is the whole fix.\n *\n * WHICH version is `live`'s to say whenever the caller knows it: the digest of\n * the checklist the feature asks now (`loam verify`, its writer, `tasks`, and\n * `status`/`list`/`gate` for an in-flight feature all derive it anyway), or\n * the one `loam archive` captured as it merged. The files that answered it\n * count. Only when no caller knows — the frozen view of an archived feature\n * with no capture — or when no file answered it does the newest file decide\n * (by `recorded`, a later service id breaking a same-day tie, and any\n * per-service file outranking the one-file record). Newest-by-date used to\n * decide always, and `recorded` is a DATE: a service recording this morning\n * against the current checklist lost the tie to a service with a later id that\n * recorded an older checklist an hour before — or a day later, from a docs\n * branch that was behind — so the current answers were dropped, every reader\n * called the record stale, and the writer printed a tally its own answers were\n * not in.\n */\nexport function assembleRecord(\n  legacy: Verification | null,\n  services: readonly Verification[],\n  live?: string,\n): Verification | null {\n  if (services.length === 0) return legacy;\n  const filed = new Set(services.flatMap((s) => (s.attestations ?? []).map((a) => a.service)));\n  const parts = [...legacyRemnant(legacy, filed), ...services];\n  // The question being asked now, when somebody answered it; every part only\n  // when nobody did — then the record is stale under every reader whichever\n  // part represents it, and the newest is the one a reader recognises.\n  const answering = live === undefined ? [] : parts.filter((part) => part.checklist === live);\n  const pool = answering.length > 0 ? answering : parts;\n  // `>=` so a later part wins a same-day tie: services arrive sorted by id,\n  // and after the one-file remnant, which is exactly the precedence above.\n  const current = pool.reduce((newest, part) => (part.recorded >= newest.recorded ? part : newest));\n  const claims = parts.filter((part) => part.checklist === current.checklist).flatMap((part) => part.claims);\n  const tally = tallyAnswers(claims);\n  return {\n    schema: 2,\n    feature: current.feature,\n    recorded: current.recorded,\n    checklist: current.checklist,\n    summary: {\n      claims: current.summary.claims,\n      confirmed: tally.confirmed,\n      unconfirmed: tally.unconfirmed,\n      unanswered: current.summary.claims - claims.length,\n    },\n    claims,\n    attestations: parts.flatMap((part) => part.attestations ?? []).sort((a, b) => a.service.localeCompare(b.service)),\n  };\n}\n\n/**\n * What of the one-file record still counts once services have files of their\n * own: the attestations of the services that have NOT re-recorded since, and\n * their answers.\n *\n * A schema-1 (all-at-once) file contributes nothing. Its answers carry no\n * commit attestation, so a federated record could never count them — the rule\n * the first federated write applied when it used to overwrite the file, and the\n * reason that write now deletes it. A schema-2 file's attestation for a service\n * that has a file of its own is superseded by that file and drops out, answers\n * with it; when every attestation in it is superseded, nothing in it counts.\n */\nfunction legacyRemnant(legacy: Verification | null, filed: ReadonlySet<string>): Verification[] {\n  if (legacy === null || legacy.schema !== 2) return [];\n  const attestations = (legacy.attestations ?? []).filter((a) => !filed.has(a.service));\n  if (attestations.length === 0) return [];\n  const kept = new Set(attestations.map((a) => a.service));\n  return [{ ...legacy, attestations, claims: legacy.claims.filter((c) => c.subject !== undefined && kept.has(c.subject)) }];\n}\n"]}