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

package/dist/core/verify/record.js

@@ -0,0 +1,165 @@
+/**
+ * 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 {} from "./claims/identity.js";
+import { ANSWERED_BY } 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"] };
+}
+/**
+ * The confirmed split as the per-feature human views print it — `13 runner · 6 agent`, empty
+ * buckets left out. `loam status <FEAT>` and `list`'s verification column print it beside the
+ * verdict because the verdict turns on the scenario claims alone ({@link verificationVerdict}), so
+ * `verified 19/19 confirmed` read as nineteen runs over a record where six were an agent's word —
+ * the split `--json` and the fleet scorecard already carried. The scorecard keeps all three keys
+ * for its stable-shape reason (validate's scorecard/print.ts); a one-feature line has no shape to
+ * keep, and a column of zeros is width the reader pays for nothing.
+ */
+export function answeredSplit(answered) {
+    return ANSWERED_BY.filter((who) => answered[who] > 0)
+        .map((who) => `${answered[who]} ${who}`)
+        .join(" · ");
+}
+/**
+ * `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);
+}
+/**
+ * The recorded rows that may answer a checklist, keyed by claim id — the one
+ * spelling of the attestation-scoping rule. A legacy (no `schema`) record is
+ * all-at-once, so every row answers. In a federated record a row only counts
+ * where an attestation from the claim's OWN subject (per `claims`, the live
+ * checklist) listed it, so one repository cannot answer another's claims by
+ * writing their ids into its own attestation. `verify`'s read view and `loam
+ * tasks` each used to carry a copy, the second labelled "a deliberate mirror"
+ * because core could not import the command module the first lived in; the
+ * rule lives here now and both import it.
+ */
+export function countedAnswers(claims, recorded) {
+    const subjects = new Map(claims.map((claim) => [claim.id, claim.subject]));
+    const attested = recorded.schema !== 2
+        ? null
+        : new Set((recorded.attestations ?? []).flatMap((a) => a.claims.filter((id) => subjects.get(id) === a.service)));
+    return new Map(recorded.claims.filter((c) => attested === null || attested.has(c.id)).map((c) => [c.id, c]));
+}
+/**
+ * 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 <report.json>\` — ` +
+            "a cucumber JSON report, or loam's runner-neutral loamScenarioReport shape for any other runner.",
+        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.`,
+    };
+}
+//# 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 { type ClaimKind } from \"./claims/identity.js\";\nimport { ANSWERED_BY, 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 ./read/shape.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/**\n * The confirmed split as the per-feature human views print it — `13 runner · 6 agent`, empty\n * buckets left out. `loam status <FEAT>` and `list`'s verification column print it beside the\n * verdict because the verdict turns on the scenario claims alone ({@link verificationVerdict}), so\n * `verified 19/19 confirmed` read as nineteen runs over a record where six were an agent's word —\n * the split `--json` and the fleet scorecard already carried. The scorecard keeps all three keys\n * for its stable-shape reason (validate's scorecard/print.ts); a one-feature line has no shape to\n * keep, and a column of zeros is width the reader pays for nothing.\n */\nexport function answeredSplit(answered: Record<AnsweredBy, number>): string {\n  return ANSWERED_BY.filter((who) => answered[who] > 0)\n    .map((who) => `${answered[who]} ${who}`)\n    .join(\" · \");\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 * The recorded rows that may answer a checklist, keyed by claim id — the one\n * spelling of the attestation-scoping rule. A legacy (no `schema`) record is\n * all-at-once, so every row answers. In a federated record a row only counts\n * where an attestation from the claim's OWN subject (per `claims`, the live\n * checklist) listed it, so one repository cannot answer another's claims by\n * writing their ids into its own attestation. `verify`'s read view and `loam\n * tasks` each used to carry a copy, the second labelled \"a deliberate mirror\"\n * because core could not import the command module the first lived in; the\n * rule lives here now and both import it.\n */\nexport function countedAnswers(\n  claims: readonly { id: string; subject: string }[],\n  recorded: Verification,\n): Map<string, RecordedClaim> {\n  const subjects = new Map(claims.map((claim) => [claim.id, claim.subject]));\n  const attested =\n    recorded.schema !== 2\n      ? null\n      : new Set(\n          (recorded.attestations ?? []).flatMap((a) => a.claims.filter((id) => subjects.get(id) === a.service)),\n        );\n  return new Map(recorded.claims.filter((c) => attested === null || attested.has(c.id)).map((c) => [c.id, c]));\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 <report.json>\\` — ` +\n      \"a cucumber JSON report, or loam's runner-neutral loamScenarioReport shape for any other runner.\",\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"]}

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

@@ -0,0 +1,99 @@
+/**
+ * The verification record's commit: staged beside the target, compared against
+ * the byte pre-image the merge consumed, swapped in by one rename(2) per file.
+ * A write is one file, or two: a service's own `verification/<svc>.yaml`, and
+ * — once nothing in it counts any more — the removal of the one-file record it
+ * supersedes. Never another service's file: those are not this run's to touch.
+ *
+ * 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 {} from "../record.js";
+/**
+ * Writes land in the order given, so a caller puts what must survive a kill
+ * FIRST: a service's own file before the one-file record it supersedes, so a
+ * process killed between the two renames leaves a record that still reads
+ * whole — the new file counted, the old one superseded by it — rather than one
+ * with the old file gone and nothing in its place.
+ */
+export async function commitVerification(writes, docsDir) {
+    const planned = writes.map((w) => w.record === null
+        ? { path: w.path, content: null }
+        : w.preImage === null
+            ? { path: w.path, content: renderVerification(w.record), exclusive: true }
+            : { path: w.path, content: renderVerification(w.record) });
+    // 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(planned);
+    }
+    catch (err) {
+        return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
+    }
+    for (const w of writes) {
+        const display = repoPath(docsDir, w.path);
+        // 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 === w.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 = w.preImage === null ? s.before !== null : s.before === null || !s.before.equals(w.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") {
+            const path = err instanceof StagingRaceError ? err.path : (writes.find((w) => w.preImage === null)?.path ?? writes[0].path);
+            return { ok: false, code: "record-raced", message: racedMessage(repoPath(docsDir, path)) };
+        }
+        return { ok: false, code: "merge-failed", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };
+    }
+    return { ok: true };
+}
+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":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC9H,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAuC,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAqB,MAAM,cAAc,CAAC;AA2BjD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAqB,EAAE,OAAe;IAC7E,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CACxB,CAAC,CAAC,EAAgB,EAAE,CAClB,CAAC,CAAC,MAAM,KAAK,IAAI;QACf,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;QACjC,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI;YACnB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;YAC1E,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAChE,CAAC;IACF,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,mEAAmE,EAAE,CAAC;IAC1I,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,uEAAuE;QACvE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iCAAiC,OAAO,yBAAyB,EAAE,CAAC;QACzH,CAAC;QACD,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,2CAA2C;QAC3C,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC3G,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EAAE,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC;aACnD,CAAC;QACJ,CAAC;QACD,wEAAwE;QACxE,4DAA4D;QAC5D,IAAI,GAAG,YAAY,gBAAgB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxF,MAAM,IAAI,GAAG,GAAG,YAAY,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,EAAE,IAAI,IAAI,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC;YAC7H,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7F,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,mEAAmE,EAAE,CAAC;IAC1I,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,CACL,GAAG,OAAO,oHAAoH;QAC9H,sHAAsH,CACvH,CAAC;AACJ,CAAC","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) per file.\n * A write is one file, or two: a service's own `verification/<svc>.yaml`, and\n * — once nothing in it counts any more — the removal of the one-file record it\n * supersedes. Never another service's file: those are not this run's to touch.\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 { 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 }\n  | { ok: false; code: \"record-raced\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * One file of the record this commit writes or removes.\n *\n * `preImage` is the exact bytes the caller's merge was computed from, or null\n * when the file was absent at the authoritative read — in which case the\n * commit may only CREATE it (link(2) refuses a file that appeared since), never\n * replace one it has not read. `record: null` removes the file, and only over\n * the bytes that read saw: a delete is a replace with nothing, and it is held\n * to the same compare.\n */\nexport interface RecordWrite {\n  path: string;\n  record: Verification | null;\n  preImage: Buffer | null;\n}\n\n/**\n * Writes land in the order given, so a caller puts what must survive a kill\n * FIRST: a service's own file before the one-file record it supersedes, so a\n * process killed between the two renames leaves a record that still reads\n * whole — the new file counted, the old one superseded by it — rather than one\n * with the old file gone and nothing in its place.\n */\nexport async function commitVerification(writes: RecordWrite[], docsDir: string): Promise<VerificationCommit> {\n  const planned = writes.map(\n    (w): PlannedWrite =>\n      w.record === null\n        ? { path: w.path, content: null }\n        : w.preImage === null\n          ? { path: w.path, content: renderVerification(w.record), exclusive: true }\n          : { path: w.path, content: renderVerification(w.record) },\n  );\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(planned);\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  for (const w of writes) {\n    const display = repoPath(docsDir, w.path);\n    // Joined by path, not by index — vouch's rule, for vouch's reason: one\n    // entry per planned write in order is true today and promised nowhere, and\n    // a compare-and-set over the wrong pair would vouch for bytes the merge\n    // never saw. A missing entry fails closed as a merge that never happened.\n    const s = staged.find((x) => x.write.path === w.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 = w.preImage === null ? s.before !== null : s.before === null || !s.before.equals(w.preImage);\n    if (edited) {\n      await rollbackStaged(staged);\n      return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n    }\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      const path = err instanceof StagingRaceError ? err.path : (writes.find((w) => w.preImage === null)?.path ?? writes[0]!.path);\n      return { ok: false, code: \"record-raced\", message: racedMessage(repoPath(docsDir, path)) };\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 };\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"]}

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

@@ -0,0 +1,61 @@
+/**
+ * The record as bytes: the header and the YAML that `store/commit.ts` swaps
+ * into place. Moved here from `../file.ts` when the contract-report validation
+ * pushed that module over the line limit — and the seam is real, not
+ * arithmetic: reading was never the inverse of rendering (a record is
+ * re-graded on the way in, because anything may have edited it since), so the
+ * two were cohabiting rather than forming a codec, while the RENDER and the
+ * COMMIT genuinely are one concern — this module produces exactly the bytes
+ * whose atomic swap that one performs. The reading went on to a package of its
+ * own, `../read/` (`file.ts` finds and grades the files, `shape.ts` says what a
+ * file must hold, `union.ts` adds the files up), and `../read/file.ts`'s header
+ * says where the render went.
+ */
+import { stringify } from "yaml";
+import {} from "../record.js";
+/**
+ * The record as a file. The header explains what the reader is looking at,
+ * because the whole point is that this is legible to someone who has never run
+ * loam — including the part loam cannot vouch for.
+ */
+export function renderVerification(v) {
+    const header = [
+        `# Verification record for ${v.feature} — written by \`loam verify ${v.feature}\` (--results / --contract-results / --record).`,
+        "#",
+        "# Every claim below was derived mechanically from this feature's own artifacts:",
+        "# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/",
+        "# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a",
+        "# test report's digest-tagged scenarios answered it mechanically — cucumber JSON,",
+        "# or loam's own {\"loamScenarioReport\": 1, ...} shape that any runner adapts into;",
+        "# `answered_by: external-runner` means a contract-test report's operationId-matched",
+        "# entries did, and `contractReport:` records which file a --contract-results run",
+        "# read; `answered_by: agent` means somebody's word about the code, which loam did",
+        "# not check. Nothing gates on any of them.",
+        "#",
+        "# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam",
+        "# reports it as `verify.scenario-attested` and the feature does not count as",
+        "# verified until a report answers it. `report:` records the file a --results run",
+        "# read — its sha256 and mtime say WHICH file, not that it came from that commit;",
+        "# no digest can say that.",
+        "#",
+        "# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same",
+        "# one, the feature changed after this was recorded and these answers are stale.",
+        ...(v.schema === 2
+            ? [
+                "#",
+                "# Schema 2 is federated: each service entry under `attestations` binds its claim ids",
+                "# and file:line evidence to that repository's git commit. Each attesting service has a",
+                "# file of its own, verification/<svc>.yaml, and the record is the directory: claims",
+                "# another service owns are honestly unanswered in this file and answered in that",
+                "# service's own, and loam adds the files up when it reads them.",
+                "# `evidence_pins` records each cited file's sha256 (CRLF-normalized) and line text at",
+                "# the attested commit, so `loam validate` in that repo can convict drift later; a pin",
+                "# identifies what was cited — it does not prove the claim true.",
+            ]
+            : []),
+        "",
+    ].join("\n");
+    // lineWidth 0: never fold a claim onto a second line — these are grepped and diffed.
+    return header + stringify(v, { lineWidth: 0 });
+}
+//# sourceMappingURL=render.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../../src/core/verify/store/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAqB,MAAM,cAAc,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAe;IAChD,MAAM,MAAM,GAAG;QACb,6BAA6B,CAAC,CAAC,OAAO,+BAA+B,CAAC,CAAC,OAAO,iDAAiD;QAC/H,GAAG;QACH,iFAAiF;QACjF,gFAAgF;QAChF,mFAAmF;QACnF,mFAAmF;QACnF,qFAAqF;QACrF,qFAAqF;QACrF,kFAAkF;QAClF,mFAAmF;QACnF,4CAA4C;QAC5C,GAAG;QACH,8EAA8E;QAC9E,8EAA8E;QAC9E,kFAAkF;QAClF,kFAAkF;QAClF,2BAA2B;QAC3B,GAAG;QACH,uFAAuF;QACvF,iFAAiF;QACjF,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;YAChB,CAAC,CAAC;gBACE,GAAG;gBACH,sFAAsF;gBACtF,wFAAwF;gBACxF,qFAAqF;gBACrF,kFAAkF;gBAClF,iEAAiE;gBACjE,uFAAuF;gBACvF,uFAAuF;gBACvF,iEAAiE;aAClE;YACH,CAAC,CAAC,EAAE,CAAC;QACP,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,qFAAqF;IACrF,OAAO,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;AACjD,CAAC","sourcesContent":["/**\n * The record as bytes: the header and the YAML that `store/commit.ts` swaps\n * into place. Moved here from `../file.ts` when the contract-report validation\n * pushed that module over the line limit — and the seam is real, not\n * arithmetic: reading was never the inverse of rendering (a record is\n * re-graded on the way in, because anything may have edited it since), so the\n * two were cohabiting rather than forming a codec, while the RENDER and the\n * COMMIT genuinely are one concern — this module produces exactly the bytes\n * whose atomic swap that one performs. The reading went on to a package of its\n * own, `../read/` (`file.ts` finds and grades the files, `shape.ts` says what a\n * file must hold, `union.ts` adds the files up), and `../read/file.ts`'s header\n * says where the render went.\n */\nimport { stringify } from \"yaml\";\nimport { type Verification } from \"../record.js\";\n\n/**\n * The record as a file. The header explains what the reader is looking at,\n * because the whole point is that this is legible to someone who has never run\n * loam — including the part loam cannot vouch for.\n */\nexport function renderVerification(v: Verification): string {\n  const header = [\n    `# Verification record for ${v.feature} — written by \\`loam verify ${v.feature}\\` (--results / --contract-results / --record).`,\n    \"#\",\n    \"# Every claim below was derived mechanically from this feature's own artifacts:\",\n    \"# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/\",\n    \"# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a\",\n    \"# test report's digest-tagged scenarios answered it mechanically — cucumber JSON,\",\n    \"# or loam's own {\\\"loamScenarioReport\\\": 1, ...} shape that any runner adapts into;\",\n    \"# `answered_by: external-runner` means a contract-test report's operationId-matched\",\n    \"# entries did, and `contractReport:` records which file a --contract-results run\",\n    \"# read; `answered_by: agent` means somebody's word about the code, which loam did\",\n    \"# not check. Nothing gates on any of them.\",\n    \"#\",\n    \"# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam\",\n    \"# reports it as `verify.scenario-attested` and the feature does not count as\",\n    \"# verified until a report answers it. `report:` records the file a --results run\",\n    \"# read — its sha256 and mtime say WHICH file, not that it came from that commit;\",\n    \"# no digest can say that.\",\n    \"#\",\n    \"# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same\",\n    \"# one, the feature changed after this was recorded and these answers are stale.\",\n    ...(v.schema === 2\n      ? [\n          \"#\",\n          \"# Schema 2 is federated: each service entry under `attestations` binds its claim ids\",\n          \"# and file:line evidence to that repository's git commit. Each attesting service has a\",\n          \"# file of its own, verification/<svc>.yaml, and the record is the directory: claims\",\n          \"# another service owns are honestly unanswered in this file and answered in that\",\n          \"# service's own, and loam adds the files up when it reads them.\",\n          \"# `evidence_pins` records each cited file's sha256 (CRLF-normalized) and line text at\",\n          \"# the attested commit, so `loam validate` in that repo can convict drift later; a pin\",\n          \"# identifies what was cited — it does not prove the claim true.\",\n        ]\n      : []),\n    \"\",\n  ].join(\"\\n\");\n  // lineWidth 0: never fold a claim onto a second line — these are grepped and diffed.\n  return header + stringify(v, { lineWidth: 0 });\n}\n"]}

package/dist/core/vocabulary/health.js

@@ -0,0 +1,91 @@
+/**
+ * The minimal reader for `services/<svc>/health.yaml` — the moment that file
+ * stops being inert. loam reads exactly one KIND of thing out of it: ids. The
+ * alert and SLI ids, so the architecture spec axis can ask whether a
+ * requirement covers each one (`health.uncovered`); and the dependency ids,
+ * so the same axis can weigh and reconcile them against the service's own
+ * model — otherwise the file an on-call engineer reaches for first is free text
+ * as far as validation is concerned and can hold false operational claims under
+ * a green result. Queries, thresholds, checks, criticality — everything else
+ * stays authored prose that no check reads, the same stance `operationIds`
+ * takes on OpenAPI schemas.
+ *
+ * The recognized keys (documented in SCHEMA.md, and deliberately few):
+ *
+ *   slis:         a YAML sequence; each entry contributes its `name` (or `id`
+ *   alerts:       when there is no name), and a plain string entry is its own id.
+ *   dependencies: a YAML sequence; each entry contributes its `id` (or
+ *                 `service`, or `name` — accepted inputs use all three forms),
+ *                 and a plain string entry is its own id.
+ *
+ * Tolerant about absence, honest about breakage: a health.yaml that is missing
+ * or declares nothing recognizable yields an empty set — and an empty set
+ * produces no findings, because an absent file must not manufacture
+ * obligations. A file that EXISTS but cannot be read is different evidence:
+ * its ids are unknown, not empty, so the `unreadable` flag travels alongside
+ * (parsers never diagnose — validate grades it as `health.invalid`). The old
+ * silent empty set turned every `Covers: alert:/sli:` entry of that service
+ * into a false `covers.unknown` "typo", when the truth was this file.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+const NO_HEALTH_IDS = { slis: [], alerts: [] };
+export async function readHealth(healthPath) {
+    if (!existsSync(healthPath))
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };
+    let doc;
+    try {
+        doc = parse(await readFile(healthPath, "utf8"));
+    }
+    catch (e) {
+        return {
+            ids: NO_HEALTH_IDS,
+            dependencies: [],
+            unreadable: true,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    // An empty file parses to null: it declares nothing, and says so honestly.
+    // A scalar or sequence document declares nothing READABLE — flag it.
+    if (doc === null)
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };
+    if (typeof doc !== "object" || Array.isArray(doc)) {
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: true, error: "document is not a YAML mapping" };
+    }
+    const top = doc;
+    return {
+        ids: { slis: idsOf(top["slis"], NAME_KEYS), alerts: idsOf(top["alerts"], NAME_KEYS) },
+        dependencies: idsOf(top["dependencies"], DEPENDENCY_KEYS),
+        unreadable: false,
+    };
+}
+/** slis/alerts entries answer to `name` first — the key SCHEMA.md teaches. */
+const NAME_KEYS = ["name", "id"];
+/**
+ * Dependency entries answer to `id` first, because it is the explicit
+ * identity; `service` and `name` are the spellings found in the wild.
+ * Tolerance in reading is not vocabulary — SCHEMA.md still teaches one.
+ */
+const DEPENDENCY_KEYS = ["id", "service", "name"];
+/** The ids one sequence declares — first recognized key wins, deduped, document order. */
+function idsOf(section, keys) {
+    if (!Array.isArray(section))
+        return [];
+    const out = new Set();
+    for (const entry of section) {
+        if (typeof entry === "string") {
+            if (entry.trim().length > 0)
+                out.add(entry.trim());
+            continue;
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const rec = entry;
+        const id = keys.map((k) => rec[k]).find((v) => typeof v === "string" && v.trim().length > 0);
+        if (typeof id === "string")
+            out.add(id.trim());
+    }
+    return [...out];
+}
+//# sourceMappingURL=health.js.map

package/dist/core/vocabulary/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/core/vocabulary/health.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The minimal reader for `services/<svc>/health.yaml` — the moment that file\n * stops being inert. loam reads exactly one KIND of thing out of it: ids. The\n * alert and SLI ids, so the architecture spec axis can ask whether a\n * requirement covers each one (`health.uncovered`); and the dependency ids,\n * so the same axis can weigh and reconcile them against the service's own\n * model — otherwise the file an on-call engineer reaches for first is free text\n * as far as validation is concerned and can hold false operational claims under\n * a green result. Queries, thresholds, checks, criticality — everything else\n * stays authored prose that no check reads, the same stance `operationIds`\n * takes on OpenAPI schemas.\n *\n * The recognized keys (documented in SCHEMA.md, and deliberately few):\n *\n *   slis:         a YAML sequence; each entry contributes its `name` (or `id`\n *   alerts:       when there is no name), and a plain string entry is its own id.\n *   dependencies: a YAML sequence; each entry contributes its `id` (or\n *                 `service`, or `name` — accepted inputs use all three forms),\n *                 and a plain string entry is its own id.\n *\n * Tolerant about absence, honest about breakage: a health.yaml that is missing\n * or declares nothing recognizable yields an empty set — and an empty set\n * produces no findings, because an absent file must not manufacture\n * obligations. A file that EXISTS but cannot be read is different evidence:\n * its ids are unknown, not empty, so the `unreadable` flag travels alongside\n * (parsers never diagnose — validate grades it as `health.invalid`). The old\n * silent empty set turned every `Covers: alert:/sli:` entry of that service\n * into a false `covers.unknown` \"typo\", when the truth was this file.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\n\nexport interface HealthIds {\n  slis: string[];\n  alerts: string[];\n}\n\nconst NO_HEALTH_IDS: HealthIds = { slis: [], alerts: [] };\n\n/** The read of one health.yaml: its declared ids, and whether the file could be read at all. */\nexport interface HealthFile {\n  ids: HealthIds;\n  /** Ids of the `dependencies:` entries — empty when the file is missing, empty, or unreadable. */\n  dependencies: string[];\n  /** True when the file exists but is not a readable YAML mapping. Missing and empty files read as empty, not broken. */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n}\n\nexport async function readHealth(healthPath: string): Promise<HealthFile> {\n  if (!existsSync(healthPath)) return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };\n  let doc: unknown;\n  try {\n    doc = parse(await readFile(healthPath, \"utf8\"));\n  } catch (e) {\n    return {\n      ids: NO_HEALTH_IDS,\n      dependencies: [],\n      unreadable: true,\n      error: e instanceof Error ? e.message : String(e),\n    };\n  }\n  // An empty file parses to null: it declares nothing, and says so honestly.\n  // A scalar or sequence document declares nothing READABLE — flag it.\n  if (doc === null) return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };\n  if (typeof doc !== \"object\" || Array.isArray(doc)) {\n    return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  const top = doc as Record<string, unknown>;\n  return {\n    ids: { slis: idsOf(top[\"slis\"], NAME_KEYS), alerts: idsOf(top[\"alerts\"], NAME_KEYS) },\n    dependencies: idsOf(top[\"dependencies\"], DEPENDENCY_KEYS),\n    unreadable: false,\n  };\n}\n\n/** slis/alerts entries answer to `name` first — the key SCHEMA.md teaches. */\nconst NAME_KEYS = [\"name\", \"id\"] as const;\n/**\n * Dependency entries answer to `id` first, because it is the explicit\n * identity; `service` and `name` are the spellings found in the wild.\n * Tolerance in reading is not vocabulary — SCHEMA.md still teaches one.\n */\nconst DEPENDENCY_KEYS = [\"id\", \"service\", \"name\"] as const;\n\n/** The ids one sequence declares — first recognized key wins, deduped, document order. */\nfunction idsOf(section: unknown, keys: readonly string[]): string[] {\n  if (!Array.isArray(section)) return [];\n  const out = new Set<string>();\n  for (const entry of section) {\n    if (typeof entry === \"string\") {\n      if (entry.trim().length > 0) out.add(entry.trim());\n      continue;\n    }\n    if (entry === null || typeof entry !== \"object\" || Array.isArray(entry)) continue;\n    const rec = entry as Record<string, unknown>;\n    const id = keys.map((k) => rec[k]).find((v) => typeof v === \"string\" && v.trim().length > 0);\n    if (typeof id === \"string\") out.add(id.trim());\n  }\n  return [...out];\n}\n"]}

package/dist/core/vocabulary/issue.js

@@ -0,0 +1,59 @@
+/**
+ * A coherence breach: something that makes a feature unsafe to merge into the
+ * living docs. Shared by every check the archive gate runs.
+ */
+/** Whether `loam archive` refuses on this issue without `--approve`. */
+export function gatesArchive(i) {
+    return i.gates ?? i.severity === "error";
+}
+/** One issue in the shared validation/status finding shape. */
+export function issueFinding(i) {
+    return {
+        severity: i.severity,
+        code: i.code,
+        gates: gatesArchive(i),
+        ...(i.subject === undefined ? {} : { subject: i.subject }),
+        ...(i.locations === undefined ? {} : { locations: i.locations }),
+        ...(i.details === undefined ? {} : { details: i.details }),
+        message: i.message,
+    };
+}
+/**
+ * Whether `--approve` can move this issue when it gates. A third axis beside
+ * severity and gating: severity answers "is the DOCUMENT valid", gating
+ * answers "is the MERGE safe", and this one answers whose call the refusal is
+ * — a human's or the grammar's. Almost every gating issue is a judgment about
+ * the feature, which is exactly the judgment `--approve` exists to override.
+ *
+ * The exceptions are the ones where approval could not change what happens.
+ * `c4.service-binding-invalid`: the binding IS the path the merge would write,
+ * so the fix is the name, never the flag. `glossary.term-exists`: the merge is
+ * a whole-file copy over an authored definition, so approving it is approving a
+ * deletion nobody described — and the alternative the message names (edit the
+ * living definition in the same change) costs one `git mv` and loses nothing.
+ * `usecase.flow-exists` is the same act one axis over: the merge would copy a
+ * feature's flow over a living one, and an ordered hop sequence is recorded
+ * nowhere else either. `usecase.flow-invalid` is the other kind of exception —
+ * not a deletion but a BLINDNESS: loam could not read the feature's flows
+ * against the map its own merge would leave, so it graded nothing, and
+ * `--approve` overrides loam's judgment about coherence and never its ability
+ * to read an axis. That is the same line `delta.likec4`'s unparseable case is
+ * refused on, one merge over.
+ *
+ * `archive` refuses these under the same `not-coherent` envelope and spells
+ * this verdict per issue as the additive `overridable` key, so a `--json`
+ * consumer branches on data rather than on a code list.
+ */
+const NEVER_OVERRIDABLE = new Set([
+    "c4.service-binding-invalid",
+    "glossary.term-exists",
+    "usecase.flow-exists",
+    "deployment.doc-exists",
+    "deployment.doc-invalid",
+    "deployment.doc-reserved",
+    "usecase.flow-invalid",
+]);
+export function approveOverrides(i) {
+    return !NEVER_OVERRIDABLE.has(i.code);
+}
+//# sourceMappingURL=issue.js.map