@ybotok/loam 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/commands/validate.js

@@ -1,17 +1,17 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { cpus } from "node:os";
-import { join } from "node:path";
 import { agentsStaleFinding } from "../core/agents-stamp.js";
+import { inOrder } from "../core/concurrency.js";
 import { loadConfig } from "../core/config.js";
 import { listField, readFrontmatter } from "../core/frontmatter.js";
-import { emitJson, fail, reportNoConfig } from "../core/json.js";
-import { elementService, loadFile, serviceOf, serviceResolver, } from "../core/likec4.js";
-import { DocsRepoUnavailableError, docsRepoState, featurePaths, featureSpecPaths, featureSpecServices, landscapePath as landscapeFile, listFeatures, listServices, missingFeatureMessage, resolveFeature, serviceIdFindings, servicePaths, } from "../core/repo.js";
-import { countSeverity, reportValid, targetJson, targetValid, } from "../core/report.js";
+import { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../core/json.js";
+import { elementService, loadFile, serviceResolver, } from "../core/likec4.js";
+import { DocsRepoUnavailableError, agentsPath as agentsFile, docsRepoState, featurePaths, featureSpecPaths, featureSpecServices, landscapePath as landscapeFile, listFeatures, listServices, missingFeatureMessage, resolveFeature, serviceIdFindings, servicePaths, SPEC_AXES, } from "../core/repo.js";
+import { countSeverity, reportValid, SEVERITY_MARK, targetJson, targetValid, } from "../core/report.js";
 import { parseRequirements, requirementIdProblems, requirementsMissingScenarios, steplessFindings, } from "../core/spec.js";
 import { readOpenapi } from "../core/openapi.js";
-import { featureCoherence } from "../core/coherence.js";
+import { producersByMessage, readAsyncapi, slotsOf } from "../core/asyncapi.js";
+import { deltaServiceUnknownFinding, featureCoherence } from "../core/coherence.js";
 import { gatesArchive } from "../core/issue.js";
 import { emptySourcesMessage, expandSourceFiles, featureProvenance, missingSources, patternSources, serviceProvenance, unsafeSources, } from "../core/provenance.js";
 import { closeIds, coversCandidates, coversEdge, coversElement, entryResolves, parseCoversEntry, } from "../core/arch.js";
@@ -19,56 +19,8 @@ import { gherkinFindings } from "../core/gherkin.js";
 import { readHealth } from "../core/health.js";
 import { LOAM_VERSION } from "../core/version.js";
 import { FleetContext, documentConflictFinding, landscapeConflictFinding, } from "../core/fleet-context.js";
-/**
- * The refusal every READ command owes a `docsDir` that is not a docs repo.
- *
- * It is not a formality. `validate --all` and `list` used to answer a docsDir
- * that does not exist with a green report over zero services, which is the one
- * output a fleet gate must never produce: "nothing is wrong" and "I could not
- * look" are opposite facts, and in CI the first one merges. The two codes are
- * kept apart because the fixes point in different directions — a wrong path in
- * loam.json versus a docs repo that was never cloned or scaffolded — exactly
- * the way `no-config` and `config-invalid` are kept apart.
- *
- * "Zero services" stays reachable, and only from a REAL docs repo whose
- * `services/` is empty: that is a legitimate state (before the first
- * `loam adopt`) and it must keep exiting 0.
- *
- * `need` says how much of a docs repo this particular run has to have. A run
- * that only reads features genuinely does not need `services/` — repo.ts takes
- * the same position for `listFeatures` — and refusing there would turn one
- * diagnosis into two contradictory ones. A run that enumerates services needs
- * the directory that IS the list of services.
- *
- * It lives in validate.ts because validate is the fleet gate this doctrine is
- * about; `list` and `show` import it rather than growing two more copies that
- * could drift into three different sentences for one fact.
- */
-export function docsRepoReady(json, docsDir, need) {
-    const state = docsRepoState(docsDir);
-    if (state.kind === "ok" || (state.kind === "no-services" && need === "docs"))
-        return true;
-    if (state.kind === "missing") {
-        fail(json, "docs-missing", `The configured docs repo does not exist: ${state.path}. ` +
-            "Fix `docsDir` in loam.json, clone the docs repo there, " +
-            "or run `loam init --docs <dir> --create` to make a new one.");
-        return false;
-    }
-    fail(json, "services-missing", `${state.path} is not a docs repo — it has no services/ directory. ` +
-        "Point `docsDir` in loam.json at the shared docs repo, " +
-        "or run `loam init --docs <dir> --create` to make one.");
-    return false;
-}
-/**
- * The same refusal, reached the other way: `listServices`/`listFeatures` throw
- * `DocsRepoUnavailableError` when the repo goes away mid-run (or when a caller
- * reaches enumeration without passing the gate above). Mapping it back onto the
- * same two codes keeps one breach spelled one way, instead of surfacing as the
- * `internal` catch-all in cli.ts.
- */
-export function reportDocsRepoError(json, err) {
-    fail(json, err.state.kind === "missing" ? "docs-missing" : "services-missing", err.message);
-}
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable, } from "./docs-repo-gate.js";
+import { plural } from "./format.js";
 export function registerValidate(program) {
     program
         .command("validate")
@@ -123,7 +75,7 @@ export function registerValidate(program) {
                 // a fresh LikeC4 workspace per call, and paying that per service makes
                 // the fleet's main CI command O(services) re-parses of the same file.
                 const lp = landscapeFile(docsDir);
-                const land = existsSync(lp) ? await fleet.loadLikeC4(lp) : null;
+                const land = existsSync(lp) ? await readLandscape(() => fleet.loadLikeC4(lp)) : null;
                 // The fleet-level cross-check first: it frames everything below it, and a
                 // service nobody drew is worth knowing before its own findings scroll past.
                 targets.push(await validateLandscape(docsDir, land, fleet));
@@ -134,7 +86,7 @@ export function registerValidate(program) {
                 // binary means agents are branching on tables the binary no longer
                 // honours. It grades the repo, not any service, so it rides on the
                 // landscape target.
-                const agentsPath = join(docsDir, "AGENTS.md");
+                const agentsPath = agentsFile(docsDir);
                 const agents = agentsStaleFinding(existsSync(agentsPath) ? await readFile(agentsPath, "utf8") : null, LOAM_VERSION);
                 if (agents !== null)
                     landscape.findings.push(agents);
@@ -193,7 +145,7 @@ export function registerValidate(program) {
             else {
                 const service = opts.service ?? config.service;
                 if (!service) {
-                    fail(json, "invalid-option", "No service. Pass --service <id> or set it in loam.json.");
+                    fail(json, "invalid-option", NO_SERVICE_MESSAGE);
                     return;
                 }
                 targets.push(await guarded({ kind: "service", id: service }, () => validateService({
@@ -218,10 +170,7 @@ export function registerValidate(program) {
             // that are fine. Say which file, and refuse; the one thing that must
             // not happen is a stack trace on stdout's sibling stream and an
             // `internal` envelope that names nothing.
-            const path = err.path;
-            if (path === undefined)
-                throw err;
-            fail(json, "repository-unavailable", `${path} could not be read, so the service list itself is unknown and nothing was validated. ${err instanceof Error ? err.message : String(err)}`);
+            reportRepositoryUnavailable(json, err, "the service list itself is unknown and nothing was validated", docsDir);
             return;
         }
         // Counted off the findings rather than alongside them, so the rollup line
@@ -262,42 +211,6 @@ export function registerValidate(program) {
             process.exitCode = 1;
     });
 }
-/**
- * How many targets `--all` may have in flight at once.
- *
- * Capped as well as scaled: each in-flight target holds a whole LikeC4/Langium
- * workspace, so a 64-core box would open sixty-four of them at once and buy
- * memory pressure rather than throughput (peak RSS on an 80-service fleet:
- * 385 MB serial, ~500 MB pooled).
- *
- * Do not quote a speedup for this. The measured cost of `--all` is CPU inside
- * the Langium parse, which one thread cannot divide however the loop is
- * shaped; what the pool overlaps is the I/O half — the spec, contract and
- * health reads around each parse. On an 80-service fleet it measures as a wash
- * (11–13 s either way, on a box that was itself loaded). The number that moves
- * this command is workspaces per run, not awaits per loop.
- */
-const TARGET_CONCURRENCY = Math.max(1, Math.min(cpus().length, 8));
-/**
- * Run `work` over `items` with a bounded number in flight, returning the
- * results in INPUT order.
- *
- * The order is the contract, not an accident: the text report and the `--json`
- * envelope are diffed between runs and between machines, so a concurrent run
- * has to be byte-identical to the serial one for the same input. That is why
- * results are written by index — nothing is appended as it finishes, and a slow
- * service cannot reorder the fleet around it.
- */
-async function inOrder(items, work) {
-    const out = [];
-    let next = 0;
-    const workers = Math.min(TARGET_CONCURRENCY, items.length);
-    await Promise.all(Array.from({ length: workers }, async () => {
-        for (let i = next++; i < items.length; i = next++)
-            out[i] = await work(items[i]);
-    }));
-    return out;
-}
 function summary(targets) {
     return {
         services: targets.filter((t) => t.kind === "service").length,
@@ -396,6 +309,57 @@ function ambiguousTarget(arg, chosen) {
 const ACTOR_KINDS = new Set(["person", "actor", "user"]);
 /** Tag marking an element as somebody else's system — undocumented on purpose. */
 const EXTERNAL_TAG = "external";
+/**
+ * A landscape that could not be READ, shaped as one that did not PARSE.
+ *
+ * The landscape is the one artifact no target owns: it is read once for the
+ * whole run and it is graded on a target of its own, which runs OUTSIDE
+ * `guarded`. So a landscape.likec4 that is a directory, or that carries a
+ * permission bit this process cannot open, escaped every per-target catch and
+ * became the whole run's `repository-unavailable` — one file, and a fleet gate
+ * that said nothing about the ninety-nine services that are fine. A DANGLING
+ * symlink is not one of those shapes and never was: every read of the file is
+ * gated on an `existsSync` that follows the link, so a broken one resolves as
+ * `landscape.missing` long before anything opens it.
+ *
+ * What this contains is the FLEET-level reads, and only those: the `--all`
+ * preload, and both reads inside `validateLandscape` — the conflict-marker
+ * `readFile` and the parse. `loam validate --service <id>` and
+ * `loam validate --feature <id>` hand in no preloaded doc, so `validateService`
+ * and `validateFeature` open the same file again on demand, unwrapped and
+ * INSIDE `guarded`: an EISDIR there is still reported as `service.unreadable`
+ * or `feature.unreadable`, which files the fleet map's failure against the one
+ * target the caller happened to name. That is the wrong subject on a finding
+ * that does at least carry the offending path, and it costs those runs nothing
+ * further — they grade a single target either way, so there is no report left
+ * unwritten — which is why the remainder was left for the change that gives the
+ * landscape one load path instead of three.
+ *
+ * `guarded` is deliberately NOT widened to cover the landscape target instead.
+ * Its code ternary knows only services and features, so it would file the fleet
+ * map's failure as `feature.unreadable`; and a guarded failure yields no
+ * document, so all N services would go on to re-open the same broken file
+ * inside their own guards and emit N copies of it. Containing the IO here needs
+ * no new code and no new sentence: "could not be read" and "did not parse" have
+ * the same consequence — nothing may be concluded from this file — and
+ * `landscape.invalid` is already how that is said.
+ */
+function unreadableLandscape(err) {
+    return {
+        errors: [{ message: err instanceof Error ? err.message : String(err) }],
+        elements: [],
+        relationships: [],
+    };
+}
+/** One landscape load, answering with `unreadableLandscape` rather than throwing. */
+async function readLandscape(load) {
+    try {
+        return await load();
+    }
+    catch (err) {
+        return unreadableLandscape(err);
+    }
+}
 /**
  * The fleet cross-check: `services/` and the landscape both claim to name the
  * fleet, and nothing used to compare them. A directory nobody drew and an element
@@ -458,12 +422,23 @@ async function validateLandscape(docsDir, preloaded, fleet) {
     // Read plainly rather than through FleetContext: this target runs outside
     // `guarded`, and a document refused for its encoding would surface here as
     // the whole run's `repository-unavailable` instead of one finding.
-    const conflict = landscapeConflictFinding("architecture/landscape.likec4", await readFile(path, "utf8"));
-    if (conflict !== null) {
-        findings.push(conflict);
-        return report;
+    //
+    // Both reads are contained for that same reason — see `unreadableLandscape`.
+    // The conflict-marker read is the FIRST touch of the file, so it is the one
+    // that fails when the file cannot be opened at all, and it runs before
+    // `preloaded ??` can spare it.
+    let land;
+    try {
+        const conflict = landscapeConflictFinding("architecture/landscape.likec4", await readFile(path, "utf8"));
+        if (conflict !== null) {
+            findings.push(conflict);
+            return report;
+        }
+        land = preloaded ?? (fleet === undefined ? await loadFile(path) : await fleet.loadLikeC4(path));
+    }
+    catch (err) {
+        land = unreadableLandscape(err);
     }
-    const land = preloaded ?? (fleet === undefined ? await loadFile(path) : await fleet.loadLikeC4(path));
     if (land.errors.length > 0) {
         // Nothing may be concluded from a document that did not parse — in particular
         // not that every service is unmodelled.
@@ -713,6 +688,17 @@ async function validateService(check) {
             message: `No living spec at ${paths.spec} — requirement coverage and API governance are unchecked`,
         });
     }
+    // The requirements that still govern anything. A REMOVED requirement is on
+    // its way out together with the operations it names: it makes no claim on the
+    // contract and governs nothing once the retiring feature archives — the same
+    // position coherence.ts takes on the delta side.
+    //
+    // Spelled once because it was spelled three times and dropped on the fourth:
+    // `governedOps` filtered, `spec-api.op-undefined` filtered, and the
+    // `api.covered` join did not — so an operation whose only requirement was
+    // REMOVED counted as governed, and the one operation about to be left without
+    // a requirement was the one the report called covered.
+    const livingReqs = reqs.filter((r) => r.kind !== "REMOVED");
     // 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);
@@ -733,7 +719,7 @@ async function validateService(check) {
         : land.relationships.filter((r) => r.op !== undefined && landSvcOf(r.target) === service);
     // 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 = reqs.filter((r) => r.kind !== "REMOVED").flatMap((r) => r.operations);
+    const governedOps = livingReqs.flatMap((r) => r.operations);
     /** No contract to read: deleted, renamed, or never written. */
     const contractMissing = !existsSync(paths.openapi);
     if (contractMissing) {
@@ -835,9 +821,7 @@ async function validateService(check) {
         // green forever, and every downstream join through that id silently empty.
         // Same code and severity as the feature-scope check on purpose: one breach,
         // one name, wherever it is found.
-        for (const r of reqs) {
-            if (r.kind === "REMOVED")
-                continue;
+        for (const r of livingReqs) {
             for (const op of r.operations) {
                 if (defined.has(op))
                     continue;
@@ -852,7 +836,7 @@ async function validateService(check) {
             }
         }
         if (ops.length > 0) {
-            const governed = new Set(reqs.flatMap((r) => r.operations));
+            const governed = new Set(livingReqs.flatMap((r) => r.operations));
             const orphans = ops.filter((op) => !governed.has(op));
             if (orphans.length === 0) {
                 findings.push({
@@ -983,15 +967,23 @@ async function validateService(check) {
             }
         }
     }
-    // The architecture spec axis — the obligations a business spec never carries
-    // (the transactional outbox, retries, metrics, alerts). arch.spec.md is
-    // optional and its ABSENCE is not a finding (partial adoption is supported);
-    // what exists must hold together: every requirement needs a scenario, every
-    // `Covers:` entry must resolve (covers.unknown), and every alert/SLI that
-    // health.yaml declares wants a covering requirement (health.uncovered) — the
-    // moment health.yaml stops being inert. Warnings, never gates: `--strict` is
-    // the CI escalation.
-    const health = await readHealth(paths.health);
+    /* ------------------------------------------------------------------ */
+    /* The async contract axis — AsyncAPI messages on the landscape spine  */
+    /* ------------------------------------------------------------------ */
+    //
+    // The HTTP spine above 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.
+    // The architecture spec, read HERE rather than with the rest of its axis
+    // below, because the event links are a requirement-level join and both
+    // requirement files carry them. Events are architecture as often as they are
+    // business — the outbox requirement in a service's arch.spec.md is the
+    // canonical place a `Publishes:` line belongs — so reading only spec.md would
+    // silently ignore the lines most authors write.
     const archText = existsSync(paths.archSpec)
         ? fleet === undefined
             ? await readFile(paths.archSpec, "utf8")
@@ -1002,6 +994,179 @@ async function validateService(check) {
         : fleet === undefined
             ? parseRequirements(archText)
             : await fleet.readRequirements(paths.archSpec);
+    // 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. 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
+        ? []
+        : land.relationships.flatMap((r) => {
+            const bound = [];
+            if (r.publishes !== undefined && landSvcOf(r.source) === service) {
+                bound.push({ direction: "publishes", message: r.publishes, other: landSvcOf(r.target) });
+            }
+            if (r.consumes !== undefined && landSvcOf(r.target) === service) {
+                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) => [
+        ...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 ${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 parse — the event spine is unchecked for this service`,
+            ...(events.error === undefined ? {} : { details: [events.error] }),
+        });
+    }
+    else {
+        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`,
+            });
+        }
+        // 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`,
+            });
+        }
+    }
+    // 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.
+    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();
+    if (consumed.length > 0) {
+        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 contested answer below rests on positive evidence and needs no such
+            // guard.
+            if (who.length === 0 && producers.unreadable.length === 0) {
+                findings.push({
+                    severity: "error",
+                    code: "spine.message-unproduced",
+                    subject: service,
+                    message: `${service}: consumes '${message}', but no service in the fleet declares an operation with action: send for it — the message has no producer, 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`,
+                });
+            }
+        }
+    }
+    // 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)`,
+        });
+    }
+    // The architecture spec axis — the obligations a business spec never carries
+    // (the transactional outbox, retries, metrics, alerts). arch.spec.md is
+    // optional and its ABSENCE is not a finding (partial adoption is supported);
+    // what exists must hold together: every requirement needs a scenario, every
+    // `Covers:` entry must resolve (covers.unknown), and every alert/SLI that
+    // health.yaml declares wants a covering requirement (health.uncovered) — the
+    // moment health.yaml stops being inert. Warnings, never gates: `--strict` is
+    // the CI escalation.
+    const health = await readHealth(paths.health);
     if (archText !== null) {
         // The arch axis is advisory in what it ASKS for (covers.unknown,
         // health.uncovered are warnings) but not in whether the file is readable:
@@ -1251,17 +1416,10 @@ async function validateFeature(docsDir, feature, preloadedLand, fleet) {
     const closeTo = unknownServices.length > 0 && docsRepoState(docsDir).kind === "ok"
         ? (await listServices(docsDir, fleet)).map((s) => s.id)
         : [];
-    for (const svc of unknownServices) {
-        const close = closeIds(svc, closeTo);
-        findings.push({
-            severity: "error",
-            code: "delta.service-unknown",
-            subject: svc,
-            message: `specs/${svc}/ addresses a service that does not exist: there is no services/${svc}/ and this feature's ` +
-                `delta.likec4 does not introduce one — archiving would create it out of the typo.` +
-                (close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : " `loam list services` shows what exists."),
-        });
-    }
+    // The finding is coherence.ts's — the same words archive refuses with, because
+    // it is the same conclusion about the same directory.
+    for (const svc of unknownServices)
+        findings.push(deltaServiceUnknownFinding(svc, closeTo));
     // Requirement coverage across every per-service delta — the business spec and
     // the arch spec through the same check — and collect scenario text.
     let scenarioText = "";
@@ -1299,15 +1457,23 @@ async function validateFeature(docsDir, feature, preloadedLand, fleet) {
             findings.push(...repeatedListLineFindings(reqs, `${svc}: arch.spec.md`, svc));
         }
     }
+    // The delta's own element→service resolver, built once for the whole feature.
+    // `serviceOf` is a one-shot wrapper that rebuilds its index on every call, and
+    // the two loops below ask it up to five times per tagged edge — so a delta
+    // over a large model paid for one Map of every element per question asked.
+    // Identical answers by construction: `serviceOf(elements, id)` IS
+    // `serviceResolver(elements)(id)`, and nothing reassigns `elements` after the
+    // delta parse.
+    const svcOf = serviceResolver(elements);
     // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.
     for (const r of taggedRels) {
-        const target = serviceOf(elements, r.target);
+        const target = svcOf(r.target);
         const covered = edgeCovered(target, r.title, scenarioText);
         findings.push({
             severity: covered ? "ok" : "warn",
             code: covered ? "archedge.covered" : "archedge.uncovered",
             subject: target,
-            message: `${serviceOf(elements, r.source)} → ${target}  "${r.title ?? ""}"${covered ? "" : "  — no scenario names it"}`,
+            message: `${svcOf(r.source)} → ${target}  "${r.title ?? ""}"${covered ? "" : "  — no scenario names it"}`,
             text: { indent: 4, header: "arch-edge coverage (heuristic):" },
         });
     }
@@ -1380,15 +1546,15 @@ async function validateFeature(docsDir, feature, preloadedLand, fleet) {
         });
     }
     for (const r of taggedRels) {
-        if (baseEdges.has(edgeKey(serviceOf(elements, r.source), serviceOf(elements, r.target))))
+        if (baseEdges.has(edgeKey(svcOf(r.source), svcOf(r.target))))
             continue;
         if (activeCovers.some((c) => coversEdge(c, r, elements)))
             continue;
         findings.push({
             severity: "warn",
             code: "c4.uncovered",
-            subject: serviceOf(elements, r.target),
-            message: `delta adds edge ${serviceOf(elements, r.source)} → ${serviceOf(elements, r.target)} ("${r.title ?? ""}") but no arch requirement covers it — add 'Covers: ${r.source} -> ${r.target}' to a specs/<svc>/arch.spec.md delta`,
+            subject: svcOf(r.target),
+            message: `delta adds edge ${svcOf(r.source)} → ${svcOf(r.target)} ("${r.title ?? ""}") but no arch requirement covers it — add 'Covers: ${r.source} -> ${r.target}' to a specs/<svc>/arch.spec.md delta`,
         });
     }
     // covers.unknown, feature scope. Resolution looks at the delta itself, the
@@ -1471,7 +1637,6 @@ function coverageFinding(label, reqs) {
 /* ------------------------------------------------------------------ */
 /* Text renderer                                                       */
 /* ------------------------------------------------------------------ */
-const MARKER = { ok: "✓", warn: "⚠", error: "✗" };
 /**
  * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code
  * lever: neither changes the report, and the `--json` payload is unaffected by
@@ -1499,7 +1664,7 @@ function renderText(targets, all, unverifiable, errorsOnly) {
             // onto stderr meant a piped stdout silently lost them from the middle of
             // the report and 2>&1 could reorder it; the exit code carries failure,
             // and stderr stays reserved for refusals (the fail() path).
-            const marker = hint.marker === false ? "" : `${MARKER[f.severity]} `;
+            const marker = hint.marker === false ? "" : `${SEVERITY_MARK[f.severity]} `;
             console.log(`${" ".repeat(hint.indent ?? 0)}${marker}${f.message}`);
             for (const d of f.details ?? [])
                 console.log(`    ${hint.detailPrefix ?? ""}${d}`);
@@ -1515,7 +1680,6 @@ function renderText(targets, all, unverifiable, errorsOnly) {
         return;
     }
     const s = summary(targets);
-    const plural = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
     console.log(`\n${plural(s.services, "service")}, ${plural(s.features, "feature")} — ` +
         `${plural(s.errors, "error")}, ${plural(s.warnings, "warning")}`);
     // One line for the whole fleet, never one per service: honest about the blind
@@ -1551,10 +1715,10 @@ function renderText(targets, all, unverifiable, errorsOnly) {
 async function sourceScopeFindings(docsDir, service, repoDir) {
     const paths = servicePaths(docsDir, service);
     const out = [];
-    for (const { path, file } of [
-        { path: paths.spec, file: "spec.md" },
-        { path: paths.archSpec, file: "arch.spec.md" },
-    ]) {
+    // The axis pair is SPEC_AXES', not this function's: `serviceProvenance` grades
+    // the same two files from the same list, and a scope check that walked a
+    // shorter list than the grading would go quiet on the axis it forgot.
+    for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {
         if (!existsSync(path))
             continue;
         const sources = listField(await readFrontmatter(path), "sources");