@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/commands/validate/service/api.js

@@ -10,11 +10,6 @@
  * is what reads it.
  */
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { parse as parseYaml } from "yaml";
-import { resolveInside } from "../../../core/kernel/path-safety.js";
-import { canonicalJson } from "../../../core/openapi/digest.js";
 import { closeIds } from "../../../core/c4/arch.js";
 import {} from "../../../core/c4/likec4.js";
 import {} from "../../../core/kernel/ids/service.js";
@@ -24,15 +19,19 @@ import { responseGovernanceFindings } from "../checks/requirements.js";
 import {} from "../../../core/document/spec.js";
 import { readOpenapi } from "../../../core/openapi/doc.js";
 import { FleetContext } from "../../../core/fleet-context.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import {} from "../../../core/kernel/ids/dirs.js";
 export async function apiAxisFindings(axis) {
-    const { service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;
+    const { docsDir, service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;
     const findings = [];
     // API coverage: every operation in openapi.yaml is governed by a requirement.
     const api = await readOpenapi(paths.openapi, fleet);
     const removeMarkers = api.ops.filter((o) => o.remove);
     const liveOps = api.ops.filter((o) => !o.remove);
-    const ops = liveOps.map((o) => o.id);
-    const deprecatedOps = new Set(liveOps.filter((o) => o.deprecated).map((o) => o.id));
+    /** No contract to read: deleted, renamed, or never written. */
+    const contractMissing = !existsSync(paths.openapi);
+    const contract = contractOf(api, contractMissing);
+    const { ops, deprecated: deprecatedOps } = contract;
     // Inbound calls the landscape can PROVE: op-linked edges whose target
     // resolves to this service. Null when the landscape proves nothing at all
     // (absent, or it did not parse) — which is not the same fact as "nobody
@@ -43,8 +42,6 @@ export async function apiAxisFindings(axis) {
     // The other half of the evidence a contract is owed: the living spec's own
     // `Operations:` lines. A requirement on its way out governs nothing.
     const governedOps = livingReqs.flatMap((r) => r.operations);
-    /** No contract to read: deleted, renamed, or never written. */
-    const contractMissing = !existsSync(paths.openapi);
     if (contractMissing) {
         // A contract that is gone is not a reason to stop grading the API axis —
         // it IS the axis's answer, and every check below used to live inside the
@@ -67,7 +64,7 @@ export async function apiAxisFindings(axis) {
                 severity: "error",
                 code: "service.no-openapi",
                 subject: service,
-                message: `No OpenAPI contract at ${paths.openapi}, and ${dangling.length} operation link(s) already point into it — ` +
+                message: `No OpenAPI contract at ${repoPath(docsDir, paths.openapi)}, and ${dangling.length} operation link(s) already point into it — ` +
                     `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,
                 details: dangling,
             });
@@ -76,7 +73,7 @@ export async function apiAxisFindings(axis) {
             findings.push({
                 severity: "warn",
                 code: "service.no-openapi",
-                message: `No OpenAPI contract at ${paths.openapi} — API coverage and the landscape spine are unchecked`,
+                message: `No OpenAPI contract at ${repoPath(docsDir, paths.openapi)} — API coverage and the landscape spine are unchecked`,
             });
         }
     }
@@ -236,103 +233,20 @@ export async function apiAxisFindings(axis) {
             }
         }
     }
-    return {
-        findings,
-        contract: { ops, deprecated: deprecatedOps, unreadable: api.unreadable || contractMissing },
-    };
+    return { findings, contract };
 }
 /**
- * The build's own contract document, compared with the copy the docs repo
- * committed — `openapi.generated-stale`, `contracts.source-missing`,
- * `contracts.source-invalid`.
- *
- * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no
- * meaning: it parses a standard document the team's own build emitted, at a
- * path a human wrote into `loam.json`, and compares a digest. That is the same
- * category as `verify --results` ingesting a cucumber report, and it is the
- * only thing in the product that can notice the assumption SCHEMA quietly makes
- * — that the committed `services/<id>/openapi.yaml` is the contract the service
- * actually serves. Most fleets generate that document; a fleet that copies it
- * by hand in month one is a fleet whose spine checks grade last quarter's
- * endpoints by month six, and until now nothing could say so.
- *
- * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,
- * because that is what makes the docs-repo document a contract somebody agreed
- * to rather than a cache of whatever the build last produced. loam reports the
- * divergence and stops.
- *
- * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions
- * that order keys differently, or a YAML dumper that re-wraps a description,
- * produce identical documents and must not produce a permanent warning nobody
- * can clear — the lesson `requirementDigest` already records one package over.
- *
- * Runs only in the SERVICE repo. From the docs repo there is no build output to
- * read and the whole family stays silent, exactly as `sources` provenance does.
+ * What the spine may conclude from one contract read — spelled once, because a
+ * `--base` run now grades a changed edge against a provider it does not grade
+ * as a target (`../scope.ts`), and two spellings of "which operations are
+ * live" would be two chances for a removal marker to count as defined.
  */
-export async function generatedContractFindings(service, repoDir, spelled, committedPath) {
-    if (spelled === undefined)
-        return [];
-    let generatedPath;
-    try {
-        // Containment is checked HERE rather than at config load, with the service
-        // in hand so the refusal can name it — and a path that escapes the repo is
-        // a finding, never a thrown config error that would take down every other
-        // command in the repo.
-        generatedPath = resolveInside(repoDir, spelled, `"contracts.openapi"`);
-    }
-    catch (err) {
-        return [{
-                severity: "error",
-                code: "contracts.source-invalid",
-                subject: service,
-                message: `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +
-                    `${err instanceof Error ? err.message : String(err)}`,
-            }];
-    }
-    if (!existsSync(generatedPath)) {
-        return [{
-                severity: "error",
-                code: "contracts.source-missing",
-                subject: service,
-                message: `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +
-                    "Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds " +
-                    "sees exactly this. Run the build first, or correct the path",
-            }];
-    }
-    const digests = [];
-    for (const [label, path] of [["generated", generatedPath], ["committed", committedPath]]) {
-        if (label === "committed" && !existsSync(path))
-            return [];
-        let parsed;
-        try {
-            parsed = parseYaml(await readFile(path, "utf8"));
-        }
-        catch (err) {
-            // An unreadable GENERATED document is this check's business; an
-            // unreadable committed one is already `openapi.invalid` and must not be
-            // reported twice under two codes.
-            if (label === "committed")
-                return [];
-            return [{
-                    severity: "error",
-                    code: "contracts.source-invalid",
-                    subject: service,
-                    message: `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +
-                        `${err instanceof Error ? err.message : String(err)}`,
-                }];
-        }
-        digests.push(createHash("sha256").update(canonicalJson(parsed), "utf8").digest("hex"));
-    }
-    if (digests[0] === digests[1])
-        return [];
-    return [{
-            severity: "warn",
-            code: "openapi.generated-stale",
-            subject: service,
-            message: `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ` +
-                "The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a " +
-                "contract this service no longer serves. Review the difference and copy the generated document across — " +
-                "loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build",
-        }];
+export function contractOf(api, missing) {
+    const live = api.ops.filter((o) => !o.remove);
+    return {
+        ops: live.map((o) => o.id),
+        deprecated: new Set(live.filter((o) => o.deprecated).map((o) => o.id)),
+        unreadable: api.unreadable || missing,
+    };
 }
 //# sourceMappingURL=api.js.map

package/dist/commands/validate/service/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The HTTP contract axis: openapi.yaml graded against the living spec.\n *\n * What it decides for everything downstream is whether there is a contract to\n * read at all. A missing or unparseable openapi.yaml is ONE finding about ONE\n * file, and that fact has to travel: grading the fleet map's inbound edges\n * against the empty operation set it leaves behind turns one broken YAML into\n * one `spine.op-undefined` per consumer, each of them accusing the landscape of\n * a fault that is not there. `ServiceContract` is how it travels; `./spine.js`\n * is what reads it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { createHash } from \"node:crypto\";\nimport { parse as parseYaml } from \"yaml\";\nimport { resolveInside } from \"../../../core/kernel/path-safety.js\";\nimport { canonicalJson } from \"../../../core/openapi/digest.js\";\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type DeclaredService, type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { responseGovernanceFindings } from \"../checks/requirements.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { readOpenapi } from \"../../../core/openapi/doc.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\n\n/** What the service target hands the HTTP axis. */\nexport interface ApiAxis {\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  paths: ServicePaths;\n  /** Every requirement the living spec declares, REMOVED ones included. */\n  reqs: Requirement[];\n  /** The ones that still govern something. */\n  livingReqs: Requirement[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver, built once per run; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  fleet?: FleetContext;\n}\n\n/**\n * What the spine may conclude from this service's contract.\n *\n * `unreadable` covers both shapes of \"there is nothing to read\" — absent and\n * unparseable — because they have the same consequence for an inbound edge:\n * the contract proves neither that the operation exists nor that it does not.\n */\nexport interface ServiceContract {\n  /** operationIds the living contract defines, empty when there is nothing to read. */\n  ops: string[];\n  /** Those of them the contract marks `deprecated: true`. */\n  deprecated: ReadonlySet<string>;\n  unreadable: boolean;\n}\n\nexport async function apiAxisFindings(\n  axis: ApiAxis,\n): Promise<{ findings: Finding[]; contract: ServiceContract }> {\n  const { service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;\n  const findings: Finding[] = [];\n\n  // API coverage: every operation in openapi.yaml is governed by a requirement.\n  const api = await readOpenapi(paths.openapi, fleet);\n  const removeMarkers = api.ops.filter((o) => o.remove);\n  const liveOps = api.ops.filter((o) => !o.remove);\n  const ops = liveOps.map((o) => o.id);\n  const deprecatedOps = new Set(liveOps.filter((o) => o.deprecated).map((o) => o.id));\n  // Inbound calls the landscape can PROVE: op-linked edges whose target\n  // resolves to this service. Null when the landscape proves nothing at all\n  // (absent, or it did not parse) — which is not the same fact as \"nobody\n  // calls me\", and the two must not be graded alike.\n  const inboundOps =\n    land === null || land.errors.length > 0\n      ? null\n      : land.relationships.filter((r) => r.op !== undefined && landSvcOf!(r.target) === me);\n  // The other half of the evidence a contract is owed: the living spec's own\n  // `Operations:` lines. A requirement on its way out governs nothing.\n  const governedOps = livingReqs.flatMap((r) => r.operations);\n  /** No contract to read: deleted, renamed, or never written. */\n  const contractMissing = !existsSync(paths.openapi);\n  if (contractMissing) {\n    // A contract that is gone is not a reason to stop grading the API axis —\n    // it IS the axis's answer, and every check below used to live inside the\n    // file-exists branch, so deleting or misspelling the file turned the whole\n    // axis (including the documented `spec-api.op-undefined`) green.\n    //\n    // What decides the severity is whether anything already written down is\n    // holding a join into it: a living `Operations:` line, or an op-linked\n    // landscape edge. With one of those, the absence breaks a link somebody\n    // authored — an error. With neither, this is a service that legitimately\n    // has no HTTP surface (a worker nobody calls), and a fleet mid-rollout\n    // must not go red for it — a warning, or, when the landscape PROVES nobody\n    // calls it, the documented silence.\n    //\n    // One finding, not one per dangling link: the fix is a single file, and\n    // the links it strands ride along as details.\n    const dangling = [...new Set([...governedOps, ...(inboundOps ?? []).map((r) => r.op!)])].sort();\n    if (dangling.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"service.no-openapi\",\n        subject: service,\n        message:\n          `No OpenAPI contract at ${paths.openapi}, and ${dangling.length} operation link(s) already point into it — ` +\n          `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,\n        details: dangling,\n      });\n    } else if (inboundOps === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"service.no-openapi\",\n        message: `No OpenAPI contract at ${paths.openapi} — API coverage and the landscape spine are unchecked`,\n      });\n    }\n  } else if (api.unreadable) {\n    // A contract that EXISTS but does not read is a broken source of truth, not\n    // an empty one: swallowing it into zero operations used to grade every\n    // inbound landscape edge `spine.op-undefined` — a false diagnosis pointing\n    // at the landscape when the truth was this file. So the file is the error,\n    // and every check that reads the contract (api.*, the spine's op\n    // resolution) is suspended below, the landscape.invalid discipline.\n    findings.push({\n      severity: \"error\",\n      code: \"openapi.invalid\",\n      message: `${service}: openapi.yaml does not parse — API coverage and the landscape spine are unchecked`,\n      ...(api.error === undefined ? {} : { details: [api.error] }),\n    });\n  } else {\n    if (removeMarkers.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-living\",\n        message: `${service}: living openapi.yaml contains ${removeMarkers.length} x-loam-remove marker(s) (${removeMarkers.map((op) => op.id).join(\", \")}) — removal markers are valid only in feature deltas`,\n      });\n    }\n    // The same marker written at PATH level, beside the methods. `readOpenapi`\n    // is keyed by (path, method), which is precisely why the check above cannot\n    // see this one and precisely how one reached a living contract in the first\n    // place: it addresses no operation, so it retired nothing, and it stayed\n    // invisible afterwards. Error, like its method-level sibling — a\n    // feature-only key published to every consumer of the fleet, and one that\n    // keeps the empty-path cleanup from ever firing. Same code as the archive\n    // plan's: one breach, one name, wherever it is found.\n    for (const removed of api.pathLevelRemovals) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: service,\n        message:\n          `${service}: living openapi.yaml carries x-loam-remove at PATH level on '${removed}' — ` +\n          `a removal marker names ONE operation, so beside the methods it retires nothing and is not a contract key either, ` +\n          `and no id-keyed check can see it. Delete it from the living contract; retire an operation through a feature delta whose marker sits inside the operation.`,\n      });\n    }\n    // Two slots claiming one operationId in a LIVING contract. `readOpenapi`\n    // has computed this since the merge needed it, and only the feature path\n    // (coherence) ever read it — so the ambiguity was reachable only when some\n    // unrelated feature happened to carry a delta for this service, and the\n    // fleet gate that actually runs in CI was blind to it. Same code and same\n    // sentence as the feature-scope check: one breach, one name.\n    for (const id of api.duplicateIds) {\n      const slots = api.ops.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.duplicate-operationid\",\n        subject: service,\n        message: `${service}: the living OpenAPI defines operationId '${id}' at ${slots.join(\" and \")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,\n      });\n    }\n    // The contract-depth probes. Form validated and depth did not: an\n    // operation whose one response is `description: OK`, and a `$ref` to a\n    // schema nobody wrote, both read as cleanly as a complete contract while\n    // a reader still cannot rebuild its payloads. Presence\n    // probes over the document's own keys; nothing reads what a schema says.\n    const undescribed = liveOps.filter((op) => op.undescribed === true).map((op) => op.id);\n    if (undescribed.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.response-undescribed\",\n        subject: service,\n        message:\n          `${service}: ${undescribed.length} operation(s) declare no response schema (${undescribed.join(\", \")}) — ` +\n          `the contract names the operation and says nothing about what it returns, so a reader still ` +\n          `needs the code; declare content with a schema on at least one response (204/304 excepted)`,\n      });\n    }\n    if (api.danglingRefs.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.ref-unresolved\",\n        subject: service,\n        message:\n          `${service}: openapi.yaml contains ${api.danglingRefs.length} internal $ref(s) that resolve to ` +\n          `nothing in the document — the operation validates while its schema is silently absent ` +\n          `(the archive plan refuses the same breach in a feature delta, as an error)`,\n        details: api.danglingRefs,\n      });\n    }\n    const defined = new Set(ops);\n    // `Operations:` on a LIVING requirement, resolved against this service's own\n    // contract. Nothing did this before: the same spine is checked inside a\n    // feature delta (coherence's spec-api.op-undefined) and then never again, so\n    // a typo that shipped, or an operation later renamed out of openapi.yaml,\n    // left a living requirement governing an operation that does not exist —\n    // green forever, and every downstream join through that id silently empty.\n    // Same code and severity as the feature-scope check on purpose: one breach,\n    // one name, wherever it is found.\n    for (const r of livingReqs) {\n      for (const op of r.operations) {\n        if (defined.has(op)) continue;\n        const close = closeIds(op, ops);\n        findings.push({\n          severity: \"error\",\n          code: \"spec-api.op-undefined\",\n          subject: service,\n          message:\n            `${service}: requirement '${r.name}' governs '${op}', not defined in ${service}'s OpenAPI` +\n            (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n        });\n      }\n    }\n    if (ops.length > 0) {\n    const governed = new Set(livingReqs.flatMap((r) => r.operations));\n    const orphans = ops.filter((op) => !governed.has(op));\n    if (orphans.length === 0) {\n      findings.push({\n        severity: \"ok\",\n        code: \"api.covered\",\n        // Both counts on purpose: the ratio is the one signal that lets a\n        // reviewer smell a thin baseline from the summary — forty behaviours\n        // filed under one requirement passes every check, and \"covered\" alone\n        // read as done.\n        message: `${service}: API covered (${ops.length} operation(s) governed by requirements · ${livingReqs.length} living requirement(s))`,\n      });\n    } else {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ungoverned\",\n        message: `${service}: ${orphans.length} operation(s) not governed by any requirement — ${orphans.join(\", \")}`,\n      });\n    }\n    findings.push(...responseGovernanceFindings(service, liveOps, livingReqs));\n    // The migration-debt case: requirements exist, the API exists, and no\n    // `Operations:` line ties them — every cross-axis check above and in\n    // feature mode is vacuously green. Once per service, not per operation;\n    // with zero requirements the spec (or its absence) is the finding instead.\n    if (reqs.length > 0 && reqs.every((r) => r.operations.length === 0)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ops-unlinked\",\n        message: `${service}: openapi.yaml defines ${ops.length} operation(s) but no requirement links any — the API axis is unchecked for this service`,\n      });\n    }\n    // Lifecycle: a requirement whose `Operations:` list resolves ONLY to\n    // deprecated operations governs behaviour the contract is retiring.\n    // Deprecation is the documented first step of removing an op; the explicit\n    // feature marker is the final step. Until that delta archives, the op stays\n    // live, so the fix is migration or a coordinated retirement. Ops the contract does not define at all\n    // prove nothing here and are left to spec-api.op-undefined above.\n    for (const r of reqs) {\n      const resolved = r.operations.filter((op) => defined.has(op));\n      if (resolved.length === 0 || !resolved.every((op) => deprecatedOps.has(op))) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"api.requirement-deprecated\",\n        message: `${service}: requirement '${r.name}' governs only deprecated operation(s) (${resolved.join(\", \")}) — the behaviour it describes is on its way out; migrate it to the replacement operation, or retire it`,\n      });\n    }\n    }\n  }\n\n  return {\n    findings,\n    contract: { ops, deprecated: deprecatedOps, unreadable: api.unreadable || contractMissing },\n  };\n}\n\n/**\n * The build's own contract document, compared with the copy the docs repo\n * committed — `openapi.generated-stale`, `contracts.source-missing`,\n * `contracts.source-invalid`.\n *\n * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no\n * meaning: it parses a standard document the team's own build emitted, at a\n * path a human wrote into `loam.json`, and compares a digest. That is the same\n * category as `verify --results` ingesting a cucumber report, and it is the\n * only thing in the product that can notice the assumption SCHEMA quietly makes\n * — that the committed `services/<id>/openapi.yaml` is the contract the service\n * actually serves. Most fleets generate that document; a fleet that copies it\n * by hand in month one is a fleet whose spine checks grade last quarter's\n * endpoints by month six, and until now nothing could say so.\n *\n * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,\n * because that is what makes the docs-repo document a contract somebody agreed\n * to rather than a cache of whatever the build last produced. loam reports the\n * divergence and stops.\n *\n * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions\n * that order keys differently, or a YAML dumper that re-wraps a description,\n * produce identical documents and must not produce a permanent warning nobody\n * can clear — the lesson `requirementDigest` already records one package over.\n *\n * Runs only in the SERVICE repo. From the docs repo there is no build output to\n * read and the whole family stays silent, exactly as `sources` provenance does.\n */\nexport async function generatedContractFindings(\n  service: string,\n  repoDir: string,\n  spelled: string | undefined,\n  committedPath: string,\n): Promise<Finding[]> {\n  if (spelled === undefined) return [];\n  let generatedPath: string;\n  try {\n    // Containment is checked HERE rather than at config load, with the service\n    // in hand so the refusal can name it — and a path that escapes the repo is\n    // a finding, never a thrown config error that would take down every other\n    // command in the repo.\n    generatedPath = resolveInside(repoDir, spelled, `\"contracts.openapi\"`);\n  } catch (err) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-invalid\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +\n        `${err instanceof Error ? err.message : String(err)}`,\n    }];\n  }\n  if (!existsSync(generatedPath)) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-missing\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +\n        \"Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds \" +\n        \"sees exactly this. Run the build first, or correct the path\",\n    }];\n  }\n  const digests: string[] = [];\n  for (const [label, path] of [[\"generated\", generatedPath], [\"committed\", committedPath]] as const) {\n    if (label === \"committed\" && !existsSync(path)) return [];\n    let parsed: unknown;\n    try {\n      parsed = parseYaml(await readFile(path, \"utf8\"));\n    } catch (err) {\n      // An unreadable GENERATED document is this check's business; an\n      // unreadable committed one is already `openapi.invalid` and must not be\n      // reported twice under two codes.\n      if (label === \"committed\") return [];\n      return [{\n        severity: \"error\",\n        code: \"contracts.source-invalid\",\n        subject: service,\n        message:\n          `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      }];\n    }\n    digests.push(createHash(\"sha256\").update(canonicalJson(parsed), \"utf8\").digest(\"hex\"));\n  }\n  if (digests[0] === digests[1]) return [];\n  return [{\n    severity: \"warn\",\n    code: \"openapi.generated-stale\",\n    subject: service,\n    message:\n      `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ` +\n      \"The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a \" +\n      \"contract this service no longer serves. Review the difference and copy the generated document across — \" +\n      \"loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build\",\n  }];\n}\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The HTTP contract axis: openapi.yaml graded against the living spec.\n *\n * What it decides for everything downstream is whether there is a contract to\n * read at all. A missing or unparseable openapi.yaml is ONE finding about ONE\n * file, and that fact has to travel: grading the fleet map's inbound edges\n * against the empty operation set it leaves behind turns one broken YAML into\n * one `spine.op-undefined` per consumer, each of them accusing the landscape of\n * a fault that is not there. `ServiceContract` is how it travels; `./spine.js`\n * is what reads it.\n */\nimport { existsSync } from \"node:fs\";\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type DeclaredService, type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { responseGovernanceFindings } from \"../checks/requirements.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { readOpenapi, type OpenapiDoc } from \"../../../core/openapi/doc.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/** What the service target hands the HTTP axis. */\nexport interface ApiAxis {\n  /** The docs root, so a message names the contract by its repo-relative path. */\n  docsDir: DocsDir;\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  paths: ServicePaths;\n  /** Every requirement the living spec declares, REMOVED ones included. */\n  reqs: Requirement[];\n  /** The ones that still govern something. */\n  livingReqs: Requirement[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver, built once per run; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  fleet: FleetContext;\n}\n\n/**\n * What the spine may conclude from this service's contract.\n *\n * `unreadable` covers both shapes of \"there is nothing to read\" — absent and\n * unparseable — because they have the same consequence for an inbound edge:\n * the contract proves neither that the operation exists nor that it does not.\n */\nexport interface ServiceContract {\n  /** operationIds the living contract defines, empty when there is nothing to read. */\n  ops: string[];\n  /** Those of them the contract marks `deprecated: true`. */\n  deprecated: ReadonlySet<string>;\n  unreadable: boolean;\n}\n\nexport async function apiAxisFindings(\n  axis: ApiAxis,\n): Promise<{ findings: Finding[]; contract: ServiceContract }> {\n  const { docsDir, service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;\n  const findings: Finding[] = [];\n\n  // API coverage: every operation in openapi.yaml is governed by a requirement.\n  const api = await readOpenapi(paths.openapi, fleet);\n  const removeMarkers = api.ops.filter((o) => o.remove);\n  const liveOps = api.ops.filter((o) => !o.remove);\n  /** No contract to read: deleted, renamed, or never written. */\n  const contractMissing = !existsSync(paths.openapi);\n  const contract = contractOf(api, contractMissing);\n  const { ops, deprecated: deprecatedOps } = contract;\n  // Inbound calls the landscape can PROVE: op-linked edges whose target\n  // resolves to this service. Null when the landscape proves nothing at all\n  // (absent, or it did not parse) — which is not the same fact as \"nobody\n  // calls me\", and the two must not be graded alike.\n  const inboundOps =\n    land === null || land.errors.length > 0\n      ? null\n      : land.relationships.filter((r) => r.op !== undefined && landSvcOf!(r.target) === me);\n  // The other half of the evidence a contract is owed: the living spec's own\n  // `Operations:` lines. A requirement on its way out governs nothing.\n  const governedOps = livingReqs.flatMap((r) => r.operations);\n  if (contractMissing) {\n    // A contract that is gone is not a reason to stop grading the API axis —\n    // it IS the axis's answer, and every check below used to live inside the\n    // file-exists branch, so deleting or misspelling the file turned the whole\n    // axis (including the documented `spec-api.op-undefined`) green.\n    //\n    // What decides the severity is whether anything already written down is\n    // holding a join into it: a living `Operations:` line, or an op-linked\n    // landscape edge. With one of those, the absence breaks a link somebody\n    // authored — an error. With neither, this is a service that legitimately\n    // has no HTTP surface (a worker nobody calls), and a fleet mid-rollout\n    // must not go red for it — a warning, or, when the landscape PROVES nobody\n    // calls it, the documented silence.\n    //\n    // One finding, not one per dangling link: the fix is a single file, and\n    // the links it strands ride along as details.\n    const dangling = [...new Set([...governedOps, ...(inboundOps ?? []).map((r) => r.op!)])].sort();\n    if (dangling.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"service.no-openapi\",\n        subject: service,\n        message:\n          `No OpenAPI contract at ${repoPath(docsDir, paths.openapi)}, and ${dangling.length} operation link(s) already point into it — ` +\n          `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,\n        details: dangling,\n      });\n    } else if (inboundOps === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"service.no-openapi\",\n        message: `No OpenAPI contract at ${repoPath(docsDir, paths.openapi)} — API coverage and the landscape spine are unchecked`,\n      });\n    }\n  } else if (api.unreadable) {\n    // A contract that EXISTS but does not read is a broken source of truth, not\n    // an empty one: swallowing it into zero operations used to grade every\n    // inbound landscape edge `spine.op-undefined` — a false diagnosis pointing\n    // at the landscape when the truth was this file. So the file is the error,\n    // and every check that reads the contract (api.*, the spine's op\n    // resolution) is suspended below, the landscape.invalid discipline.\n    findings.push({\n      severity: \"error\",\n      code: \"openapi.invalid\",\n      message: `${service}: openapi.yaml does not parse — API coverage and the landscape spine are unchecked`,\n      ...(api.error === undefined ? {} : { details: [api.error] }),\n    });\n  } else {\n    if (removeMarkers.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-living\",\n        message: `${service}: living openapi.yaml contains ${removeMarkers.length} x-loam-remove marker(s) (${removeMarkers.map((op) => op.id).join(\", \")}) — removal markers are valid only in feature deltas`,\n      });\n    }\n    // The same marker written at PATH level, beside the methods. `readOpenapi`\n    // is keyed by (path, method), which is precisely why the check above cannot\n    // see this one and precisely how one reached a living contract in the first\n    // place: it addresses no operation, so it retired nothing, and it stayed\n    // invisible afterwards. Error, like its method-level sibling — a\n    // feature-only key published to every consumer of the fleet, and one that\n    // keeps the empty-path cleanup from ever firing. Same code as the archive\n    // plan's: one breach, one name, wherever it is found.\n    for (const removed of api.pathLevelRemovals) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: service,\n        message:\n          `${service}: living openapi.yaml carries x-loam-remove at PATH level on '${removed}' — ` +\n          `a removal marker names ONE operation, so beside the methods it retires nothing and is not a contract key either, ` +\n          `and no id-keyed check can see it. Delete it from the living contract; retire an operation through a feature delta whose marker sits inside the operation.`,\n      });\n    }\n    // Two slots claiming one operationId in a LIVING contract. `readOpenapi`\n    // has computed this since the merge needed it, and only the feature path\n    // (coherence) ever read it — so the ambiguity was reachable only when some\n    // unrelated feature happened to carry a delta for this service, and the\n    // fleet gate that actually runs in CI was blind to it. Same code and same\n    // sentence as the feature-scope check: one breach, one name.\n    for (const id of api.duplicateIds) {\n      const slots = api.ops.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.duplicate-operationid\",\n        subject: service,\n        message: `${service}: the living OpenAPI defines operationId '${id}' at ${slots.join(\" and \")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,\n      });\n    }\n    // The contract-depth probes. Form validated and depth did not: an\n    // operation whose one response is `description: OK`, and a `$ref` to a\n    // schema nobody wrote, both read as cleanly as a complete contract while\n    // a reader still cannot rebuild its payloads. Presence\n    // probes over the document's own keys; nothing reads what a schema says.\n    const undescribed = liveOps.filter((op) => op.undescribed === true).map((op) => op.id);\n    if (undescribed.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.response-undescribed\",\n        subject: service,\n        message:\n          `${service}: ${undescribed.length} operation(s) declare no response schema (${undescribed.join(\", \")}) — ` +\n          `the contract names the operation and says nothing about what it returns, so a reader still ` +\n          `needs the code; declare content with a schema on at least one response (204/304 excepted)`,\n      });\n    }\n    if (api.danglingRefs.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.ref-unresolved\",\n        subject: service,\n        message:\n          `${service}: openapi.yaml contains ${api.danglingRefs.length} internal $ref(s) that resolve to ` +\n          `nothing in the document — the operation validates while its schema is silently absent ` +\n          `(the archive plan refuses the same breach in a feature delta, as an error)`,\n        details: api.danglingRefs,\n      });\n    }\n    const defined = new Set(ops);\n    // `Operations:` on a LIVING requirement, resolved against this service's own\n    // contract. Nothing did this before: the same spine is checked inside a\n    // feature delta (coherence's spec-api.op-undefined) and then never again, so\n    // a typo that shipped, or an operation later renamed out of openapi.yaml,\n    // left a living requirement governing an operation that does not exist —\n    // green forever, and every downstream join through that id silently empty.\n    // Same code and severity as the feature-scope check on purpose: one breach,\n    // one name, wherever it is found.\n    for (const r of livingReqs) {\n      for (const op of r.operations) {\n        if (defined.has(op)) continue;\n        const close = closeIds(op, ops);\n        findings.push({\n          severity: \"error\",\n          code: \"spec-api.op-undefined\",\n          subject: service,\n          message:\n            `${service}: requirement '${r.name}' governs '${op}', not defined in ${service}'s OpenAPI` +\n            (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n        });\n      }\n    }\n    if (ops.length > 0) {\n    const governed = new Set(livingReqs.flatMap((r) => r.operations));\n    const orphans = ops.filter((op) => !governed.has(op));\n    if (orphans.length === 0) {\n      findings.push({\n        severity: \"ok\",\n        code: \"api.covered\",\n        // Both counts on purpose: the ratio is the one signal that lets a\n        // reviewer smell a thin baseline from the summary — forty behaviours\n        // filed under one requirement passes every check, and \"covered\" alone\n        // read as done.\n        message: `${service}: API covered (${ops.length} operation(s) governed by requirements · ${livingReqs.length} living requirement(s))`,\n      });\n    } else {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ungoverned\",\n        message: `${service}: ${orphans.length} operation(s) not governed by any requirement — ${orphans.join(\", \")}`,\n      });\n    }\n    findings.push(...responseGovernanceFindings(service, liveOps, livingReqs));\n    // The migration-debt case: requirements exist, the API exists, and no\n    // `Operations:` line ties them — every cross-axis check above and in\n    // feature mode is vacuously green. Once per service, not per operation;\n    // with zero requirements the spec (or its absence) is the finding instead.\n    if (reqs.length > 0 && reqs.every((r) => r.operations.length === 0)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ops-unlinked\",\n        message: `${service}: openapi.yaml defines ${ops.length} operation(s) but no requirement links any — the API axis is unchecked for this service`,\n      });\n    }\n    // Lifecycle: a requirement whose `Operations:` list resolves ONLY to\n    // deprecated operations governs behaviour the contract is retiring.\n    // Deprecation is the documented first step of removing an op; the explicit\n    // feature marker is the final step. Until that delta archives, the op stays\n    // live, so the fix is migration or a coordinated retirement. Ops the contract does not define at all\n    // prove nothing here and are left to spec-api.op-undefined above.\n    for (const r of reqs) {\n      const resolved = r.operations.filter((op) => defined.has(op));\n      if (resolved.length === 0 || !resolved.every((op) => deprecatedOps.has(op))) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"api.requirement-deprecated\",\n        message: `${service}: requirement '${r.name}' governs only deprecated operation(s) (${resolved.join(\", \")}) — the behaviour it describes is on its way out; migrate it to the replacement operation, or retire it`,\n      });\n    }\n    }\n  }\n\n  return { findings, contract };\n}\n\n/**\n * What the spine may conclude from one contract read — spelled once, because a\n * `--base` run now grades a changed edge against a provider it does not grade\n * as a target (`../scope.ts`), and two spellings of \"which operations are\n * live\" would be two chances for a removal marker to count as defined.\n */\nexport function contractOf(api: OpenapiDoc, missing: boolean): ServiceContract {\n  const live = api.ops.filter((o) => !o.remove);\n  return {\n    ops: live.map((o) => o.id),\n    deprecated: new Set(live.filter((o) => o.deprecated).map((o) => o.id)),\n    unreadable: api.unreadable || missing,\n  };\n}\n"]}

package/dist/commands/validate/service/contracts/generated.js

@@ -0,0 +1,134 @@
+/**
+ * The generated-contract check: the build's own OpenAPI document against the
+ * copy the docs repo committed.
+ *
+ * It sits beside the HTTP axis (`../api.ts`) rather than inside it because it
+ * reads a different document for a different question. The axis grades the
+ * committed contract against the living spec; this asks whether that committed
+ * contract is still the one the service serves, and it runs only in a service
+ * repo. They used to share one file, and naming the operationIds that moved
+ * pushed it over the line limit.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { parse as parseYaml } from "yaml";
+import { resolveInside } from "../../../../core/kernel/path-safety.js";
+import { canonicalJson } from "../../../../core/openapi/digest.js";
+import { openapiFromText } from "../../../../core/openapi/doc.js";
+import {} from "../../../../core/vocabulary/report.js";
+/**
+ * The build's own contract document, compared with the copy the docs repo
+ * committed — `openapi.generated-stale`, `contracts.source-missing`,
+ * `contracts.source-invalid`.
+ *
+ * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no
+ * meaning: it parses a standard document the team's own build emitted, at a
+ * path a human wrote into `loam.json`, and compares a digest. That is the same
+ * category as `verify --results` ingesting a cucumber report, and it is the
+ * only thing in the product that can notice the assumption SCHEMA quietly makes
+ * — that the committed `services/<id>/openapi.yaml` is the contract the service
+ * actually serves. Most fleets generate that document; a fleet that copies it
+ * by hand in month one is a fleet whose spine checks grade last quarter's
+ * endpoints by month six, and until now nothing could say so.
+ *
+ * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,
+ * because that is what makes the docs-repo document a contract somebody agreed
+ * to rather than a cache of whatever the build last produced. loam reports the
+ * divergence and stops.
+ *
+ * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions
+ * that order keys differently, or a YAML dumper that re-wraps a description,
+ * produce identical documents and must not produce a permanent warning nobody
+ * can clear — the lesson `requirementDigest` (core/document/spec.ts) already records.
+ *
+ * THE DIGEST DECIDES, THE operationId SETS EXPLAIN. A reworded description and
+ * 29 vanished endpoints were one identical warning, each costing a manual diff
+ * to tell apart, so a fired warning names the set difference both ways (or says
+ * the sets agree). The sets never fire it on their own: the digest still does.
+ *
+ * Runs only in the SERVICE repo. From the docs repo there is no build output to
+ * read and the whole family stays silent, exactly as `sources` provenance does.
+ */
+export async function generatedContractFindings(service, repoDir, spelled, committedPath) {
+    if (spelled === undefined)
+        return [];
+    let generatedPath;
+    try {
+        // Containment is checked HERE rather than at config load, with the service
+        // in hand so the refusal can name it — and a path that escapes the repo is
+        // a finding, never a thrown config error that would take down every other
+        // command in the repo.
+        generatedPath = resolveInside(repoDir, spelled, `"contracts.openapi"`);
+    }
+    catch (err) {
+        return [{
+                severity: "error",
+                code: "contracts.source-invalid",
+                subject: service,
+                message: `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            }];
+    }
+    if (!existsSync(generatedPath)) {
+        return [{
+                severity: "error",
+                code: "contracts.source-missing",
+                subject: service,
+                message: `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +
+                    "Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds " +
+                    "sees exactly this. Run the build first, or correct the path",
+            }];
+    }
+    const digests = [];
+    const idSets = [];
+    for (const [label, path] of [["generated", generatedPath], ["committed", committedPath]]) {
+        if (label === "committed" && !existsSync(path))
+            return [];
+        let parsed, text;
+        try {
+            text = await readFile(path, "utf8");
+            parsed = parseYaml(text);
+        }
+        catch (err) {
+            // An unreadable GENERATED document is this check's business; an
+            // unreadable committed one is already `openapi.invalid` and must not be
+            // reported twice under two codes.
+            if (label === "committed")
+                return [];
+            return [{
+                    severity: "error",
+                    code: "contracts.source-invalid",
+                    subject: service,
+                    message: `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +
+                        `${err instanceof Error ? err.message : String(err)}`,
+                }];
+        }
+        digests.push(createHash("sha256").update(canonicalJson(parsed), "utf8").digest("hex"));
+        // The walk every operation join uses: "served" means what a spine check sees.
+        idSets.push(new Set(openapiFromText(text).ops.map((op) => op.id)));
+    }
+    if (digests[0] === digests[1])
+        return [];
+    const [served, committed] = idSets;
+    const added = [...served].filter((id) => !committed.has(id)).sort();
+    const removed = [...committed].filter((id) => !served.has(id)).sort();
+    const details = [
+        ...added.map((id) => `served, not in the committed copy: ${id}`),
+        ...removed.map((id) => `committed, no longer served: ${id}`),
+    ];
+    const moved = details.length === 0
+        ? "Every operationId matches, so what moved is inside an operation or outside `paths`. "
+        : `${added.length} operation(s) served but not committed, ${removed.length} committed but no longer served (details). `;
+    return [{
+            severity: "warn",
+            code: "openapi.generated-stale",
+            subject: service,
+            message: `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ${moved}` +
+                "The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a " +
+                "contract this service no longer serves. Review the difference and copy the generated document across — " +
+                "loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build",
+            ...(details.length === 0 ? {} : { details }),
+        }];
+}
+//# sourceMappingURL=generated.js.map

package/dist/commands/validate/service/contracts/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/contracts/generated.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated-contract check: the build's own OpenAPI document against the\n * copy the docs repo committed.\n *\n * It sits beside the HTTP axis (`../api.ts`) rather than inside it because it\n * reads a different document for a different question. The axis grades the\n * committed contract against the living spec; this asks whether that committed\n * contract is still the one the service serves, and it runs only in a service\n * repo. They used to share one file, and naming the operationIds that moved\n * pushed it over the line limit.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { createHash } from \"node:crypto\";\nimport { parse as parseYaml } from \"yaml\";\nimport { resolveInside } from \"../../../../core/kernel/path-safety.js\";\nimport { canonicalJson } from \"../../../../core/openapi/digest.js\";\nimport { openapiFromText } from \"../../../../core/openapi/doc.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\n\n/**\n * The build's own contract document, compared with the copy the docs repo\n * committed — `openapi.generated-stale`, `contracts.source-missing`,\n * `contracts.source-invalid`.\n *\n * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no\n * meaning: it parses a standard document the team's own build emitted, at a\n * path a human wrote into `loam.json`, and compares a digest. That is the same\n * category as `verify --results` ingesting a cucumber report, and it is the\n * only thing in the product that can notice the assumption SCHEMA quietly makes\n * — that the committed `services/<id>/openapi.yaml` is the contract the service\n * actually serves. Most fleets generate that document; a fleet that copies it\n * by hand in month one is a fleet whose spine checks grade last quarter's\n * endpoints by month six, and until now nothing could say so.\n *\n * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,\n * because that is what makes the docs-repo document a contract somebody agreed\n * to rather than a cache of whatever the build last produced. loam reports the\n * divergence and stops.\n *\n * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions\n * that order keys differently, or a YAML dumper that re-wraps a description,\n * produce identical documents and must not produce a permanent warning nobody\n * can clear — the lesson `requirementDigest` (core/document/spec.ts) already records.\n *\n * THE DIGEST DECIDES, THE operationId SETS EXPLAIN. A reworded description and\n * 29 vanished endpoints were one identical warning, each costing a manual diff\n * to tell apart, so a fired warning names the set difference both ways (or says\n * the sets agree). The sets never fire it on their own: the digest still does.\n *\n * Runs only in the SERVICE repo. From the docs repo there is no build output to\n * read and the whole family stays silent, exactly as `sources` provenance does.\n */\nexport async function generatedContractFindings(\n  service: string,\n  repoDir: string,\n  spelled: string | undefined,\n  committedPath: string,\n): Promise<Finding[]> {\n  if (spelled === undefined) return [];\n  let generatedPath: string;\n  try {\n    // Containment is checked HERE rather than at config load, with the service\n    // in hand so the refusal can name it — and a path that escapes the repo is\n    // a finding, never a thrown config error that would take down every other\n    // command in the repo.\n    generatedPath = resolveInside(repoDir, spelled, `\"contracts.openapi\"`);\n  } catch (err) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-invalid\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +\n        `${err instanceof Error ? err.message : String(err)}`,\n    }];\n  }\n  if (!existsSync(generatedPath)) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-missing\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +\n        \"Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds \" +\n        \"sees exactly this. Run the build first, or correct the path\",\n    }];\n  }\n  const digests: string[] = [];\n  const idSets: Set<string>[] = [];\n  for (const [label, path] of [[\"generated\", generatedPath], [\"committed\", committedPath]] as const) {\n    if (label === \"committed\" && !existsSync(path)) return [];\n    let parsed: unknown, text: string;\n    try {\n      text = await readFile(path, \"utf8\");\n      parsed = parseYaml(text);\n    } catch (err) {\n      // An unreadable GENERATED document is this check's business; an\n      // unreadable committed one is already `openapi.invalid` and must not be\n      // reported twice under two codes.\n      if (label === \"committed\") return [];\n      return [{\n        severity: \"error\",\n        code: \"contracts.source-invalid\",\n        subject: service,\n        message:\n          `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      }];\n    }\n    digests.push(createHash(\"sha256\").update(canonicalJson(parsed), \"utf8\").digest(\"hex\"));\n    // The walk every operation join uses: \"served\" means what a spine check sees.\n    idSets.push(new Set(openapiFromText(text).ops.map((op) => op.id)));\n  }\n  if (digests[0] === digests[1]) return [];\n  const [served, committed] = idSets as [Set<string>, Set<string>];\n  const added = [...served].filter((id) => !committed.has(id)).sort();\n  const removed = [...committed].filter((id) => !served.has(id)).sort();\n  const details = [\n    ...added.map((id) => `served, not in the committed copy: ${id}`),\n    ...removed.map((id) => `committed, no longer served: ${id}`),\n  ];\n  const moved = details.length === 0\n    ? \"Every operationId matches, so what moved is inside an operation or outside `paths`. \"\n    : `${added.length} operation(s) served but not committed, ${removed.length} committed but no longer served (details). `;\n  return [{\n    severity: \"warn\",\n    code: \"openapi.generated-stale\",\n    subject: service,\n    message:\n      `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ${moved}` +\n      \"The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a \" +\n      \"contract this service no longer serves. Review the difference and copy the generated document across — \" +\n      \"loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build\",\n    ...(details.length === 0 ? {} : { details }),\n  }];\n}\n"]}

package/dist/commands/validate/service/events/events.js

@@ -15,11 +15,13 @@
 import { existsSync } from "node:fs";
 import {} from "../../../../core/kernel/ids/service.js";
 import {} from "../../../../core/c4/likec4.js";
+import { eventKeys, infrastructureKind, unboundSentence } from "../../../../core/c4/direction/direction.js";
 import {} from "../../../../core/repo/paths.js";
 import {} from "../../../../core/vocabulary/report.js";
 import {} from "../../../../core/document/spec.js";
 import { readAsyncapi, slotsOf } from "../../../../core/asyncapi/read.js";
 import { FleetContext } from "../../../../core/fleet-context.js";
+import { repoPath } from "../../../../core/envelope/json.js";
 import { producerFindings } from "./message-producers.js";
 export async function eventAxisFindings(axis) {
     const { docsDir, service, me, paths, reqs, livingReqs, archReqs, land, landSvcOf, known, fleet } = axis;
@@ -33,20 +35,40 @@ export async function eventAxisFindings(axis) {
     const receivedHere = new Set(events.received);
     // Every edge that binds THIS service to a message: `publishes` binds the
     // edge's source (a service produces what it declares an `action: send` for),
-    // `consumes` binds its target. One edge may legitimately carry both — a relay
-    // that reads one topic and writes another is a single arrow in most fleet maps.
-    const eventEdges = land === null || land.errors.length > 0
+    // `consumes` binds its target — `eventKeys` is where that rule is written,
+    // once, for this scope and the feature gate alike. One edge may legitimately
+    // carry both: a producer drawn straight to its consumer is a single arrow.
+    const readable = land !== null && land.errors.length === 0 && landSvcOf !== null;
+    const eventEdges = !readable
         ? []
-        : land.relationships.flatMap((r) => {
-            const bound = [];
-            if (r.publishes !== undefined && landSvcOf(r.source) === me) {
-                bound.push({ direction: "publishes", message: r.publishes, other: landSvcOf(r.target) });
+        : land.relationships.flatMap((r) => eventKeys(r)
+            .filter((k) => landSvcOf(k.bound) === me)
+            .map((k) => ({ direction: k.direction, message: k.message, other: landSvcOf(k.other) })));
+    // The edges the filter above drops that THIS service drew the wrong way
+    // round: a key bound to infrastructure (a topic, which neither publishes nor
+    // consumes) while this service sits at the other end. It used to fall out of
+    // `eventEdges` without a word, so a consume edge drawn from the consumer to
+    // the topic graded nothing and said nothing. A key bound to an `#external`
+    // system is NOT this case — an outside producer or consumer, which the
+    // drawing states correctly (core/c4/direction/direction.ts says why). Raised on
+    // the service at the unbound end, because it is the one with a drawing to fix.
+    const knownIds = known;
+    if (readable) {
+        const infraKindOf = infrastructureKind(land.elements);
+        for (const r of land.relationships) {
+            for (const key of eventKeys(r)) {
+                const kind = infraKindOf(key.bound);
+                if (kind === undefined || landSvcOf(key.other) !== me || knownIds.has(landSvcOf(key.bound)))
+                    continue;
+                findings.push({
+                    severity: "warn",
+                    code: "spine.message-unbound",
+                    subject: service,
+                    message: `${service}: landscape ${unboundSentence(r, key, kind)}`,
+                });
             }
-            if (r.consumes !== undefined && landSvcOf(r.target) === me) {
-                bound.push({ direction: "consumes", message: r.consumes, other: landSvcOf(r.source) });
-            }
-            return bound;
-        });
+        }
+    }
     // Both requirement namespaces, and a REMOVED requirement links nothing —
     // the `livingReqs` rule the API axis already follows, applied to the pair.
     const eventLinks = [...livingReqs, ...archReqs.filter((r) => r.kind !== "REMOVED")].flatMap((r) => [
@@ -71,7 +93,7 @@ export async function eventAxisFindings(axis) {
                 severity: "error",
                 code: "service.no-asyncapi",
                 subject: service,
-                message: `No async contract at ${paths.asyncapi}, and ${dangling.length} message link(s) already point into it — ` +
+                message: `No async contract at ${repoPath(docsDir, paths.asyncapi)}, and ${dangling.length} message link(s) already point into it — ` +
                     `every landscape edge and requirement naming one of them resolves to nothing until the file is back`,
                 details: dangling,
             });
@@ -86,7 +108,7 @@ export async function eventAxisFindings(axis) {
             severity: "error",
             code: "asyncapi.invalid",
             subject: service,
-            message: `${service}: asyncapi.yaml does not parse — the event spine is unchecked for this service`,
+            message: `${service}: asyncapi.yaml does not read as AsyncAPI 3.0 (it does not parse, or it declares an older version) — the event spine is unchecked for this service`,
             ...(events.error === undefined ? {} : { details: [events.error] }),
         });
     }