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

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":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAgB,MAAM,uCAAuC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAe,EACf,OAAe,EACf,OAA2B,EAC3B,aAAqB;IAErB,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrC,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,2EAA2E;QAC3E,2EAA2E;QAC3E,0EAA0E;QAC1E,uBAAuB;QACvB,aAAa,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC;gBACN,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EACL,GAAG,OAAO,wCAAwC,OAAO,qDAAqD;oBAC9G,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;aACxD,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC;gBACN,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,OAAO;gBAChB,OAAO,EACL,GAAG,OAAO,wCAAwC,OAAO,2BAA2B;oBACpF,2GAA2G;oBAC3G,6DAA6D;aAChE,CAAC,CAAC;IACL,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,aAAa,CAAC,CAAU,EAAE,CAAC;QAClG,IAAI,KAAK,KAAK,WAAW,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QAC1D,IAAI,MAAe,EAAE,IAAY,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACpC,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gEAAgE;YAChE,wEAAwE;YACxE,kCAAkC;YAClC,IAAI,KAAK,KAAK,WAAW;gBAAE,OAAO,EAAE,CAAC;YACrC,OAAO,CAAC;oBACN,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,0BAA0B;oBAChC,OAAO,EAAE,OAAO;oBAChB,OAAO,EACL,GAAG,OAAO,wBAAwB,OAAO,qCAAqC;wBAC9E,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;iBACxD,CAAC,CAAC;QACL,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvF,8EAA8E;QAC9E,MAAM,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,MAAoC,CAAC;IACjE,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpE,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,OAAO,GAAG;QACd,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,sCAAsC,EAAE,EAAE,CAAC;QAChE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,gCAAgC,EAAE,EAAE,CAAC;KAC7D,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC;QAChC,CAAC,CAAC,sFAAsF;QACxF,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,2CAA2C,OAAO,CAAC,MAAM,6CAA6C,CAAC;IAC1H,OAAO,CAAC;YACN,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,OAAO,oFAAoF,OAAO,MAAM,KAAK,EAAE;gBAClH,6GAA6G;gBAC7G,yGAAyG;gBACzG,kHAAkH;YACpH,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;SAC7C,CAAC,CAAC;AACL,CAAC","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

@@ -0,0 +1,241 @@
+/**
+ * The async contract axis — AsyncAPI messages on the landscape spine.
+ *
+ * The HTTP spine (`./spine.js`) and this one are mirror images, and the mirror
+ * is the whole reason this is a second axis rather than a second `metadata`
+ * key. On the HTTP axis the PROVIDER owns the contract: an edge names an
+ * operation and the target's openapi.yaml settles it, locally, in one file.
+ * Here the PRODUCER owns the message and the consumer joins to it from another
+ * repository — so "is this message declared" is local, while "does anybody
+ * publish it" is a fleet question with no local answer at all. That second
+ * question is the only check on either spine that reads other services'
+ * contracts; it lives in `./message-producers.js`, and this axis only decides
+ * when it is worth paying for — exactly when something actually consumes.
+ */
+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;
+    const findings = [];
+    // Where this axis started, so the closing ok-finding can be "nothing here
+    // broke" rather than a second, independently-computed claim about the same
+    // facts. A positive finding derived from the same walk cannot disagree with it.
+    const eventFindingsAt = findings.length;
+    const events = await readAsyncapi(paths.asyncapi, fleet);
+    const sentHere = new Set(events.sent);
+    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 — `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) => 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)}`,
+                });
+            }
+        }
+    }
+    // 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) => [
+        ...r.publishes.map((m) => ({ direction: "publishes", message: m, requirement: r.name })),
+        ...r.consumes.map((m) => ({ direction: "consumes", message: m, requirement: r.name })),
+    ]);
+    if (!existsSync(paths.asyncapi)) {
+        // Deliberately TWO grades, not the three `service.no-openapi` uses. Its
+        // middle grade — warn when the landscape cannot prove nobody calls this
+        // service — rests on HTTP being the default: most services expose one, so
+        // "I could not look" is worth saying. An event contract is genuinely
+        // optional; most services in a legacy fleet touch no topic at all. Warning
+        // every one of them the moment a landscape fails to parse would put a
+        // finding on the whole fleet that names a file nobody owes.
+        //
+        // So: something already joins into the absent file, or silence.
+        const dangling = [
+            ...new Set([...eventEdges.map((e) => e.message), ...eventLinks.map((e) => e.message)]),
+        ].sort();
+        if (dangling.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "service.no-asyncapi",
+                subject: service,
+                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,
+            });
+        }
+    }
+    else if (events.unreadable) {
+        // The openapi.invalid discipline: a contract that EXISTS but does not read
+        // is a broken source of truth, not an empty one. Grading the links against
+        // an empty message set would turn one file into one `spine.message-undefined`
+        // per edge, every one of them pointing at the landscape.
+        findings.push({
+            severity: "error",
+            code: "asyncapi.invalid",
+            subject: 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] }),
+        });
+    }
+    else {
+        // Feature-only bookkeeping published to the fleet — the openapi axis's
+        // `openapi.remove-marker-living` discipline, one code for every depth the
+        // reader collects markers at (slots and inline channel messages alike).
+        if (events.markers.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "asyncapi.remove-marker-living",
+                subject: service,
+                message: `${service}: living asyncapi.yaml carries x-loam-remove: true at ${events.markers.join(", ")} — removal markers are valid only in feature deltas; retire a slot through a feature's asyncapi.yaml instead`,
+            });
+        }
+        for (const name of events.duplicateNames) {
+            findings.push({
+                severity: "warn",
+                code: "asyncapi.duplicate-message",
+                subject: service,
+                message: `${service}: asyncapi.yaml declares message '${name}' in ${slotsOf(events, name).join(" and ")} — every join on the name (an edge's metadata { publishes }, a requirement's Publishes: line) picks one of those slots arbitrarily`,
+            });
+        }
+        // The contract-depth probes. Form validated and depth did not: a payload
+        // of bare `type: object` and a `$ref` to nothing both read as cleanly as
+        // a full schema, while a reader still cannot rebuild the payload from the
+        // green contract. Presence probes only — a non-JSON schemaFormat
+        // is skipped, so Avro stays a document change.
+        const empties = events.messages.filter((m) => m.payloadEmpty === true).map((m) => m.name);
+        if (empties.length > 0) {
+            findings.push({
+                severity: "warn",
+                code: "asyncapi.payload-undescribed",
+                subject: service,
+                message: `${service}: ${empties.length} message(s) declare no payload shape (${empties.join(", ")}) — ` +
+                    `the name joins the spine, but nothing defines what a consumer would read; ` +
+                    `declare properties, or a schemaFormat for a non-JSON schema`,
+            });
+        }
+        if (events.danglingRefs.length > 0) {
+            findings.push({
+                severity: "warn",
+                code: "asyncapi.ref-unresolved",
+                subject: service,
+                message: `${service}: asyncapi.yaml contains ${events.danglingRefs.length} internal $ref(s) that resolve ` +
+                    `to nothing in the document — whatever they were meant to carry is silently absent from the ` +
+                    `spine's view of this contract`,
+                details: events.danglingRefs,
+            });
+        }
+        // Local resolution, both directions and both sources of a claim. An edge and
+        // a requirement making the same broken claim get the same sentence under
+        // different codes, matching how `spine.op-undefined` and
+        // `spec-api.op-undefined` split the HTTP axis: one is the fleet map's
+        // mistake, the other is this document's, and the fix is in a different file.
+        const declares = (direction, message) => direction === "publishes" ? sentHere.has(message) : receivedHere.has(message);
+        const action = (direction) => direction === "publishes" ? "send" : "receive";
+        for (const e of eventEdges) {
+            if (declares(e.direction, e.message))
+                continue;
+            findings.push({
+                severity: "error",
+                code: "spine.message-undefined",
+                subject: service,
+                message: `${service}: landscape edge ${e.direction === "publishes" ? `${service} → ${e.other}` : `${e.other} → ${service}`} ` +
+                    `${e.direction} '${e.message}', but ${service}'s asyncapi.yaml declares no operation with action: ${action(e.direction)} for it`,
+            });
+        }
+        for (const e of eventLinks) {
+            if (declares(e.direction, e.message))
+                continue;
+            findings.push({
+                severity: "error",
+                code: "spec-event.message-undefined",
+                subject: service,
+                message: `${service}: requirement '${e.requirement}' ${e.direction} '${e.message}', but ${service}'s asyncapi.yaml declares no operation with action: ${action(e.direction)} for it`,
+            });
+        }
+        // The migration-debt case, `api.ops-unlinked`'s twin: a contract and
+        // requirements that never name each other leave this axis vacuously green.
+        if (events.messages.length > 0 && reqs.length + archReqs.length > 0 && eventLinks.length === 0) {
+            findings.push({
+                severity: "warn",
+                code: "event.messages-unlinked",
+                subject: service,
+                message: `${service}: asyncapi.yaml declares ${events.messages.length} message(s) but no requirement links any — the event axis is unchecked for this service`,
+            });
+        }
+        // `api.ungoverned`'s event twin, and the per-message half the check above
+        // cannot see: `event.messages-unlinked` fires only when ZERO links exist,
+        // so a contract with five declared messages and three governed ones
+        // reported nothing about the other two. The join is against requirement
+        // lines ONLY, deliberately ignoring landscape edges — an edge is a claim
+        // about traffic, a requirement is governance — exactly as the API axis
+        // ignores inbound edges when grading coverage.
+        const governed = new Set(eventLinks.map((e) => e.message));
+        const orphans = [...new Set(events.messages.map((m) => m.name))].filter((name) => !governed.has(name));
+        if (orphans.length > 0) {
+            findings.push({
+                severity: "warn",
+                code: "event.ungoverned",
+                subject: service,
+                message: `${service}: ${orphans.length} message(s) not governed by any requirement's Publishes:/Consumes: line — ${orphans.join(", ")}`,
+            });
+        }
+    }
+    // The consumed-message list is the handover to the fleet question in
+    // ./message-producers.js — a fleet where nothing consumes walks nothing.
+    const consumed = [
+        ...new Set([
+            ...eventEdges.filter((e) => e.direction === "consumes").map((e) => e.message),
+            ...eventLinks.filter((e) => e.direction === "consumes").map((e) => e.message),
+        ]),
+    ].sort();
+    findings.push(...(await producerFindings({ docsDir, service, land, landSvcOf, known, events, consumed, fleet })));
+    // Positive confirmation, on the same rule `spine.resolved` follows: claimed
+    // only where the axis actually checked something. A service that touches no
+    // topic says nothing here — an "event axis clean" on every worker in the fleet
+    // would be a green tick for work nobody did.
+    const eventChecks = eventEdges.length + eventLinks.length;
+    if (eventChecks > 0 && findings.length === eventFindingsAt) {
+        findings.push({
+            severity: "ok",
+            code: "event.covered",
+            message: `${service}: event spine (${eventChecks} message link(s) resolve to asyncapi.yaml)`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/events/events.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The async contract axis — AsyncAPI messages on the landscape spine.\n *\n * The HTTP spine (`./spine.js`) and this one are mirror images, and the mirror\n * is the whole reason this is a second axis rather than a second `metadata`\n * key. On the HTTP axis the PROVIDER owns the contract: an edge names an\n * operation and the target's openapi.yaml settles it, locally, in one file.\n * Here the PRODUCER owns the message and the consumer joins to it from another\n * repository — so \"is this message declared\" is local, while \"does anybody\n * publish it\" is a fleet question with no local answer at all. That second\n * question is the only check on either spine that reads other services'\n * contracts; it lives in `./message-producers.js`, and this axis only decides\n * when it is worth paying for — exactly when something actually consumes.\n */\nimport { existsSync } from \"node:fs\";\nimport {\n  type DeclaredService,\n  type PathableService,\n  type RawServiceId,\n} from \"../../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport { eventKeys, infrastructureKind, unboundSentence } from \"../../../../core/c4/direction/direction.js\";\nimport { type ServicePaths } from \"../../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\nimport { type Requirement } from \"../../../../core/document/spec.js\";\nimport { readAsyncapi, slotsOf } from \"../../../../core/asyncapi/read.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport { repoPath } from \"../../../../core/envelope/json.js\";\nimport { producerFindings } from \"./message-producers.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\n\n/** What the service target hands the event axis. */\nexport interface EventAxis {\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; `event.messages-unlinked` counts what is written. */\n  reqs: Requirement[];\n  /** The ones that still govern something — a REMOVED requirement links nothing. */\n  livingReqs: Requirement[];\n  /** arch.spec.md's requirements, which carry as many event links as spec.md's do. */\n  archReqs: Requirement[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  /** Service directories that exist — the fleet the producer question is asked over. */\n  known: ReadonlySet<RawServiceId>;\n  fleet: FleetContext;\n}\n\nexport async function eventAxisFindings(axis: EventAxis): Promise<Finding[]> {\n  const { docsDir, service, me, paths, reqs, livingReqs, archReqs, land, landSvcOf, known, fleet } =\n    axis;\n  const findings: Finding[] = [];\n\n  // Where this axis started, so the closing ok-finding can be \"nothing here\n  // broke\" rather than a second, independently-computed claim about the same\n  // facts. A positive finding derived from the same walk cannot disagree with it.\n  const eventFindingsAt = findings.length;\n  const events = await readAsyncapi(paths.asyncapi, fleet);\n  const sentHere = new Set(events.sent);\n  const receivedHere = new Set(events.received);\n\n  // Every edge that binds THIS service to a message: `publishes` binds the\n  // edge's source (a service produces what it declares an `action: send` for),\n  // `consumes` binds its target — `eventKeys` is where that rule is written,\n  // once, for this scope and the feature gate alike. One edge may legitimately\n  // carry both: a producer drawn straight to its consumer is a single arrow.\n  const readable = land !== null && land.errors.length === 0 && landSvcOf !== null;\n  const eventEdges = !readable\n    ? []\n    : land.relationships.flatMap((r) =>\n        eventKeys(r)\n          .filter((k) => landSvcOf(k.bound) === me)\n          .map((k) => ({ direction: k.direction, message: k.message, other: landSvcOf(k.other) })),\n      );\n  // The edges the filter above drops that THIS service drew the wrong way\n  // round: a key bound to infrastructure (a topic, which neither publishes nor\n  // consumes) while this service sits at the other end. It used to fall out of\n  // `eventEdges` without a word, so a consume edge drawn from the consumer to\n  // the topic graded nothing and said nothing. A key bound to an `#external`\n  // system is NOT this case — an outside producer or consumer, which the\n  // drawing states correctly (core/c4/direction/direction.ts says why). Raised on\n  // the service at the unbound end, because it is the one with a drawing to fix.\n  const knownIds: ReadonlySet<string> = known;\n  if (readable) {\n    const infraKindOf = infrastructureKind(land.elements);\n    for (const r of land.relationships) {\n      for (const key of eventKeys(r)) {\n        const kind = infraKindOf(key.bound);\n        if (kind === undefined || landSvcOf(key.other) !== me || knownIds.has(landSvcOf(key.bound))) continue;\n        findings.push({\n          severity: \"warn\",\n          code: \"spine.message-unbound\",\n          subject: service,\n          message: `${service}: landscape ${unboundSentence(r, key, kind)}`,\n        });\n      }\n    }\n  }\n  // Both requirement namespaces, and a REMOVED requirement links nothing —\n  // the `livingReqs` rule the API axis already follows, applied to the pair.\n  const eventLinks = [...livingReqs, ...archReqs.filter((r) => r.kind !== \"REMOVED\")].flatMap((r) => [\n    ...r.publishes.map((m) => ({ direction: \"publishes\" as const, message: m, requirement: r.name })),\n    ...r.consumes.map((m) => ({ direction: \"consumes\" as const, message: m, requirement: r.name })),\n  ]);\n\n  if (!existsSync(paths.asyncapi)) {\n    // Deliberately TWO grades, not the three `service.no-openapi` uses. Its\n    // middle grade — warn when the landscape cannot prove nobody calls this\n    // service — rests on HTTP being the default: most services expose one, so\n    // \"I could not look\" is worth saying. An event contract is genuinely\n    // optional; most services in a legacy fleet touch no topic at all. Warning\n    // every one of them the moment a landscape fails to parse would put a\n    // finding on the whole fleet that names a file nobody owes.\n    //\n    // So: something already joins into the absent file, or silence.\n    const dangling = [\n      ...new Set([...eventEdges.map((e) => e.message), ...eventLinks.map((e) => e.message)]),\n    ].sort();\n    if (dangling.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"service.no-asyncapi\",\n        subject: service,\n        message:\n          `No async contract at ${repoPath(docsDir, paths.asyncapi)}, and ${dangling.length} message link(s) already point into it — ` +\n          `every landscape edge and requirement naming one of them resolves to nothing until the file is back`,\n        details: dangling,\n      });\n    }\n  } else if (events.unreadable) {\n    // The openapi.invalid discipline: a contract that EXISTS but does not read\n    // is a broken source of truth, not an empty one. Grading the links against\n    // an empty message set would turn one file into one `spine.message-undefined`\n    // per edge, every one of them pointing at the landscape.\n    findings.push({\n      severity: \"error\",\n      code: \"asyncapi.invalid\",\n      subject: service,\n      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`,\n      ...(events.error === undefined ? {} : { details: [events.error] }),\n    });\n  } else {\n    // Feature-only bookkeeping published to the fleet — the openapi axis's\n    // `openapi.remove-marker-living` discipline, one code for every depth the\n    // reader collects markers at (slots and inline channel messages alike).\n    if (events.markers.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"asyncapi.remove-marker-living\",\n        subject: service,\n        message: `${service}: living asyncapi.yaml carries x-loam-remove: true at ${events.markers.join(\", \")} — removal markers are valid only in feature deltas; retire a slot through a feature's asyncapi.yaml instead`,\n      });\n    }\n    for (const name of events.duplicateNames) {\n      findings.push({\n        severity: \"warn\",\n        code: \"asyncapi.duplicate-message\",\n        subject: service,\n        message: `${service}: asyncapi.yaml declares message '${name}' in ${slotsOf(events, name).join(\" and \")} — every join on the name (an edge's metadata { publishes }, a requirement's Publishes: line) picks one of those slots arbitrarily`,\n      });\n    }\n    // The contract-depth probes. Form validated and depth did not: a payload\n    // of bare `type: object` and a `$ref` to nothing both read as cleanly as\n    // a full schema, while a reader still cannot rebuild the payload from the\n    // green contract. Presence probes only — a non-JSON schemaFormat\n    // is skipped, so Avro stays a document change.\n    const empties = events.messages.filter((m) => m.payloadEmpty === true).map((m) => m.name);\n    if (empties.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"asyncapi.payload-undescribed\",\n        subject: service,\n        message:\n          `${service}: ${empties.length} message(s) declare no payload shape (${empties.join(\", \")}) — ` +\n          `the name joins the spine, but nothing defines what a consumer would read; ` +\n          `declare properties, or a schemaFormat for a non-JSON schema`,\n      });\n    }\n    if (events.danglingRefs.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"asyncapi.ref-unresolved\",\n        subject: service,\n        message:\n          `${service}: asyncapi.yaml contains ${events.danglingRefs.length} internal $ref(s) that resolve ` +\n          `to nothing in the document — whatever they were meant to carry is silently absent from the ` +\n          `spine's view of this contract`,\n        details: events.danglingRefs,\n      });\n    }\n    // Local resolution, both directions and both sources of a claim. An edge and\n    // a requirement making the same broken claim get the same sentence under\n    // different codes, matching how `spine.op-undefined` and\n    // `spec-api.op-undefined` split the HTTP axis: one is the fleet map's\n    // mistake, the other is this document's, and the fix is in a different file.\n    const declares = (direction: \"publishes\" | \"consumes\", message: string): boolean =>\n      direction === \"publishes\" ? sentHere.has(message) : receivedHere.has(message);\n    const action = (direction: \"publishes\" | \"consumes\"): string =>\n      direction === \"publishes\" ? \"send\" : \"receive\";\n    for (const e of eventEdges) {\n      if (declares(e.direction, e.message)) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"spine.message-undefined\",\n        subject: service,\n        message:\n          `${service}: landscape edge ${e.direction === \"publishes\" ? `${service} → ${e.other}` : `${e.other} → ${service}`} ` +\n          `${e.direction} '${e.message}', but ${service}'s asyncapi.yaml declares no operation with action: ${action(e.direction)} for it`,\n      });\n    }\n    for (const e of eventLinks) {\n      if (declares(e.direction, e.message)) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"spec-event.message-undefined\",\n        subject: service,\n        message: `${service}: requirement '${e.requirement}' ${e.direction} '${e.message}', but ${service}'s asyncapi.yaml declares no operation with action: ${action(e.direction)} for it`,\n      });\n    }\n    // The migration-debt case, `api.ops-unlinked`'s twin: a contract and\n    // requirements that never name each other leave this axis vacuously green.\n    if (events.messages.length > 0 && reqs.length + archReqs.length > 0 && eventLinks.length === 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"event.messages-unlinked\",\n        subject: service,\n        message: `${service}: asyncapi.yaml declares ${events.messages.length} message(s) but no requirement links any — the event axis is unchecked for this service`,\n      });\n    }\n    // `api.ungoverned`'s event twin, and the per-message half the check above\n    // cannot see: `event.messages-unlinked` fires only when ZERO links exist,\n    // so a contract with five declared messages and three governed ones\n    // reported nothing about the other two. The join is against requirement\n    // lines ONLY, deliberately ignoring landscape edges — an edge is a claim\n    // about traffic, a requirement is governance — exactly as the API axis\n    // ignores inbound edges when grading coverage.\n    const governed = new Set(eventLinks.map((e) => e.message));\n    const orphans = [...new Set(events.messages.map((m) => m.name))].filter((name) => !governed.has(name));\n    if (orphans.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"event.ungoverned\",\n        subject: service,\n        message: `${service}: ${orphans.length} message(s) not governed by any requirement's Publishes:/Consumes: line — ${orphans.join(\", \")}`,\n      });\n    }\n  }\n\n  // The consumed-message list is the handover to the fleet question in\n  // ./message-producers.js — a fleet where nothing consumes walks nothing.\n  const consumed = [\n    ...new Set([\n      ...eventEdges.filter((e) => e.direction === \"consumes\").map((e) => e.message),\n      ...eventLinks.filter((e) => e.direction === \"consumes\").map((e) => e.message),\n    ]),\n  ].sort();\n  findings.push(...(await producerFindings({ docsDir, service, land, landSvcOf, known, events, consumed, fleet })));\n\n  // Positive confirmation, on the same rule `spine.resolved` follows: claimed\n  // only where the axis actually checked something. A service that touches no\n  // topic says nothing here — an \"event axis clean\" on every worker in the fleet\n  // would be a green tick for work nobody did.\n  const eventChecks = eventEdges.length + eventLinks.length;\n  if (eventChecks > 0 && findings.length === eventFindingsAt) {\n    findings.push({\n      severity: \"ok\",\n      code: \"event.covered\",\n      message: `${service}: event spine (${eventChecks} message link(s) resolve to asyncapi.yaml)`,\n    });\n  }\n\n  return findings;\n}\n"]}

package/dist/commands/validate/service/events/message-producers.js

@@ -0,0 +1,77 @@
+/**
+ * The fleet question the event axis asks: who produces what this service
+ * consumes. Split out of `./events.js` along the seam its own header always
+ * named — the local axis grades one service's files, while this is the only
+ * check on either spine that reads OTHER services' contracts, and the two
+ * subjects share nothing but the consumed-message list the axis hands over.
+ */
+import {} from "../../../../core/kernel/ids/service.js";
+import {} from "../../../../core/c4/likec4.js";
+import {} from "../../../../core/vocabulary/report.js";
+import { producersByMessage } from "../../../../core/asyncapi/producers.js";
+import {} from "../../../../core/asyncapi/model.js";
+import { FleetContext } from "../../../../core/fleet-context.js";
+import { externalProducerOf } from "../../../../core/c4/resolve/external.js";
+// The fleet question, and the one check on either spine that a single
+// repository cannot answer: a consumer joins to a message whose schema lives
+// in the producer's contract, in the producer's repo. Paid only when something
+// actually consumes — a fleet where nobody has adopted the axis walks nothing.
+export async function producerFindings(input) {
+    const { docsDir, service, land, landSvcOf, known, events, consumed, fleet } = input;
+    const findings = [];
+    if (consumed.length === 0)
+        return findings;
+    const producers = await producersByMessage(docsDir, [...known], fleet);
+    for (const message of consumed) {
+        const who = producers.byMessage.get(message) ?? [];
+        // "Nobody produces this" is an argument from absence, and it is only
+        // sound over a fleet loam could actually read. One unreadable contract
+        // anywhere suspends it — that service may be the producer, and the
+        // alternative is blaming every consumer for somebody else's broken YAML.
+        // The external answer and the contested answer below rest on positive
+        // evidence and need no such guard.
+        if (who.length === 0) {
+            // A message produced OUTSIDE the fleet used to be inexpressible: the
+            // landscape said the producer was #external, and this error fired
+            // anyway — so honesty cost a red build, and the exit ramp people took
+            // was deleting the link. The landscape already carries the answer; an
+            // external producer shifts the contract question to the one file that
+            // can settle it, this service's own asyncapi.yaml.
+            const ext = externalProducerOf(message, land, landSvcOf, known);
+            if (ext !== null) {
+                const local = events.messages.find((m) => m.name === message);
+                if (local === undefined || local.payloadEmpty === true) {
+                    findings.push({
+                        severity: "warn",
+                        code: "spine.message-external",
+                        subject: service,
+                        message: `${service}: consumes '${message}' from '${ext}', a system outside the fleet — the ` +
+                            `producer declares no contract here, so the only payload definition is this service's ` +
+                            `own asyncapi.yaml, and it currently defines no shape for it; declare the message with ` +
+                            `its payload`,
+                    });
+                }
+                // A carried contract closes the question: the landscape states the
+                // external dependency, the consumer owns the schema — nothing to say.
+            }
+            else if (producers.unreadable.length === 0) {
+                findings.push({
+                    severity: "error",
+                    code: "spine.message-unproduced",
+                    subject: service,
+                    message: `${service}: consumes '${message}', but no service in the fleet and no #external element declares it is sent — the message has no producer anywhere, so nothing defines its payload`,
+                });
+            }
+        }
+        else if (who.length > 1) {
+            findings.push({
+                severity: "warn",
+                code: "asyncapi.message-contested",
+                subject: service,
+                message: `${service}: consumes '${message}', which ${who.length} services declare they send (${who.join(", ")}) — every consumer's join picks one of them arbitrarily, so the payload this service reads is whichever one happens to win`,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=message-producers.js.map

package/dist/commands/validate/service/events/message-producers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-producers.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/events/message-producers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet question the event axis asks: who produces what this service\n * consumes. Split out of `./events.js` along the seam its own header always\n * named — the local axis grades one service's files, while this is the only\n * check on either spine that reads OTHER services' contracts, and the two\n * subjects share nothing but the consumed-message list the axis hands over.\n */\nimport { type DeclaredService, type PathableService, type RawServiceId } from \"../../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\nimport { producersByMessage } from \"../../../../core/asyncapi/producers.js\";\nimport { type AsyncapiDoc } from \"../../../../core/asyncapi/model.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport { externalProducerOf } from \"../../../../core/c4/resolve/external.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\n\n/**\n * What the producer question is asked over. One record rather than a parameter\n * list: everything here is already bound together as one service's view of the\n * fleet, and the 4-parameter limit says so too.\n */\nexport interface ProducerQuestion {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  /** Service directories that exist — the fleet the producer question is asked over. */\n  known: ReadonlySet<RawServiceId>;\n  /** This service's own parsed contract — the local-shape half of the external answer. */\n  events: AsyncapiDoc;\n  /** The deduped message names this service consumes, from edges and requirement lines alike. */\n  consumed: readonly string[];\n  fleet: FleetContext;\n}\n\n// The fleet question, and the one check on either spine that a single\n// repository cannot answer: a consumer joins to a message whose schema lives\n// in the producer's contract, in the producer's repo. Paid only when something\n// actually consumes — a fleet where nobody has adopted the axis walks nothing.\nexport async function producerFindings(input: ProducerQuestion): Promise<Finding[]> {\n  const { docsDir, service, land, landSvcOf, known, events, consumed, fleet } = input;\n  const findings: Finding[] = [];\n  if (consumed.length === 0) return findings;\n  const producers = await producersByMessage(docsDir, [...known], fleet);\n  for (const message of consumed) {\n    const who = producers.byMessage.get(message) ?? [];\n    // \"Nobody produces this\" is an argument from absence, and it is only\n    // sound over a fleet loam could actually read. One unreadable contract\n    // anywhere suspends it — that service may be the producer, and the\n    // alternative is blaming every consumer for somebody else's broken YAML.\n    // The external answer and the contested answer below rest on positive\n    // evidence and need no such guard.\n    if (who.length === 0) {\n      // A message produced OUTSIDE the fleet used to be inexpressible: the\n      // landscape said the producer was #external, and this error fired\n      // anyway — so honesty cost a red build, and the exit ramp people took\n      // was deleting the link. The landscape already carries the answer; an\n      // external producer shifts the contract question to the one file that\n      // can settle it, this service's own asyncapi.yaml.\n      const ext = externalProducerOf(message, land, landSvcOf, known);\n      if (ext !== null) {\n        const local = events.messages.find((m) => m.name === message);\n        if (local === undefined || local.payloadEmpty === true) {\n          findings.push({\n            severity: \"warn\",\n            code: \"spine.message-external\",\n            subject: service,\n            message:\n              `${service}: consumes '${message}' from '${ext}', a system outside the fleet — the ` +\n              `producer declares no contract here, so the only payload definition is this service's ` +\n              `own asyncapi.yaml, and it currently defines no shape for it; declare the message with ` +\n              `its payload`,\n          });\n        }\n        // A carried contract closes the question: the landscape states the\n        // external dependency, the consumer owns the schema — nothing to say.\n      } else if (producers.unreadable.length === 0) {\n        findings.push({\n          severity: \"error\",\n          code: \"spine.message-unproduced\",\n          subject: service,\n          message: `${service}: consumes '${message}', but no service in the fleet and no #external element declares it is sent — the message has no producer anywhere, so nothing defines its payload`,\n        });\n      }\n    } else if (who.length > 1) {\n      findings.push({\n        severity: \"warn\",\n        code: \"asyncapi.message-contested\",\n        subject: service,\n        message: `${service}: consumes '${message}', which ${who.length} services declare they send (${who.join(\", \")}) — every consumer's join picks one of them arbitrarily, so the payload this service reads is whichever one happens to win`,\n      });\n    }\n  }\n  return findings;\n}\n"]}