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

package/dist/commands/validate/checks/fleet-shape.js

@@ -0,0 +1,296 @@
+/**
+ * Fleet-shape advisories over the parsed landscape: the two ways a fleet map
+ * stops answering questions as it grows, caught while the map is already in
+ * memory.
+ *
+ * Both shapes become visible at service three rather than service two.
+ * Ubiquitous infrastructure — logging Kafka, an identity provider, service
+ * discovery — takes one inbound edge per modelled service until the map is a
+ * hairball around it; deleting the element fixes the picture and loses "who
+ * depends on the Identity Provider", which is the question the map exists to
+ * answer during an incident. Tagging keeps both: the fleet view excludes
+ * `#platform`, and a platform view keeps the dependents. And a datastore drawn as a fleet-level
+ * peer makes a claim its consumer count either supports or refutes: one
+ * consumer means the drawing is false — the store is that service's
+ * internals, not a system in its own right — while two or more mean the
+ * strongest coupling two services can have, which deserves to be stated
+ * rather than inferred.
+ *
+ * Everything here is O(relationships) over data the fleet target already
+ * holds. loam still reads no code and decides no policy: the team chooses
+ * what counts as platform and which data is truly shared — these warnings
+ * only name the shapes that are usually wrong.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/vocabulary/report.js";
+import {} from "../../../core/repo/entries.js";
+import { permissionsPath, servicePathsAt } from "../../../core/repo/paths.js";
+import { readVocabulary } from "../../../core/permissions/permissions.js";
+import { readCapabilityVocabulary } from "../../../core/capabilities/capabilities.js";
+import { capabilityDocFindings, capabilityRequirementIndex, docMissingFindings, gradableCapabilityIds, invalidVocabularyFinding, unrealizedFindings, } from "../../../core/capabilities/findings.js";
+import { useCaseRequirementClaims } from "../../../core/usecases/capability.js";
+import { capabilityRollup, usedCapabilities } from "../../../core/capabilities/rollup.js";
+import { requirementUnrealizedFindings } from "../../../core/capabilities/realizes/findings.js";
+import { parseRequirements } from "../../../core/document/parse.js";
+import {} from "../../../core/document/spec.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { EXTERNAL_TAG, PLATFORM_TAG } from "../../../core/vocabulary/maturity.js";
+/**
+ * Consumers at which an untagged external hub starts to warn. Three, not two:
+ * two services sharing a dependency is a fact about those two services, the
+ * same edge from three is a pattern about the element — and three is where
+ * the shared hub starts making the map unreadable.
+ */
+export const PLATFORM_CANDIDATE_MIN_CONSUMERS = 3;
+/** The element kind read as a datastore, compared case-insensitively. */
+const DATASTORE_KIND = "database";
+export function fleetShapeFindings(shape) {
+    const { drawn, relationships, services, resolve } = shape;
+    const findings = [];
+    // Distinct consumer SERVICES of an element, its nested children included: an
+    // edge into `kafka.paymentEvents` is consumption of `kafka`. Persons, other
+    // external systems and unresolved sources never count — a consumer is a
+    // source the shared resolver files under a real services/<id>/, so two edges
+    // from one service are one consumer.
+    const consumersOf = (e) => {
+        const out = new Set();
+        for (const r of relationships) {
+            if (r.target !== e.id && !r.target.startsWith(`${e.id}.`))
+                continue;
+            const svc = resolve(r.source);
+            if (services.has(svc))
+                out.add(svc);
+        }
+        return [...out].sort();
+    };
+    for (const e of drawn) {
+        // An element that stands for a real service is the fleet itself, not its
+        // shape: many consumers is what a well-used service looks like, and a
+        // datastore bound to a directory is graded by the binding checks instead.
+        if (e.service !== undefined || services.has(e.title))
+            continue;
+        const consumers = consumersOf(e);
+        if (e.tags.includes(EXTERNAL_TAG) &&
+            !e.tags.includes(PLATFORM_TAG) &&
+            consumers.length >= PLATFORM_CANDIDATE_MIN_CONSUMERS) {
+            findings.push({
+                severity: "warn",
+                code: "landscape.platform-candidate",
+                subject: e.title,
+                message: `landscape: '${e.title}' is consumed by ${consumers.length} services (${consumers.join(", ")}) ` +
+                    `and is not tagged #platform — a hub like this takes one more edge per modelled service until ` +
+                    `the fleet view is unreadable. Declare \`tag platform\` in the specification block and tag the ` +
+                    `element (LikeC4 refuses an undeclared tag, so both steps are needed): the fleet view then ` +
+                    `excludes it, and a platform view over \`include * -> element.tag = #platform\` keeps ` +
+                    `"who depends on it" answerable`,
+            });
+        }
+        if (e.kind.toLowerCase() !== DATASTORE_KIND || consumers.length === 0)
+            continue;
+        if (consumers.length === 1) {
+            findings.push({
+                severity: "warn",
+                code: "landscape.datastore-private",
+                subject: e.title,
+                message: `landscape: '${e.title}' is a datastore with a single consumer at fleet level ` +
+                    `('${consumers[0]}') — drawn as a peer it reads as a system in its own right, available to ` +
+                    `be depended on. Move it into ${shape.pathOf(consumers[0])}/model.likec4 as a nested container ` +
+                    `and delete it here, or add the second consumer's edge if another service really reaches ` +
+                    `the same data`,
+            });
+        }
+        else {
+            findings.push({
+                severity: "warn",
+                code: "landscape.datastore-shared",
+                subject: e.title,
+                message: `landscape: '${e.title}' is a datastore shared by ${consumers.length} services ` +
+                    `(${consumers.join(", ")}) — the strongest coupling two services can have, and the hardest ` +
+                    `to undo. Shared means the same DATA: if they read the same tables or keys, keep it drawn ` +
+                    `and let this warning state the coupling; if they only share a host or cluster (two schemas, ` +
+                    `two lock paths), that is operational blast radius — a runbook fact — and the honest model ` +
+                    `is one private store per service`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * The #external element that declares it PUBLISHES this message, or null —
+ * the landscape-side half of the event spine's fleet question, beside the
+ * other checks that read tags off the drawn map.
+ *
+ * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`
+ * whose source element — itself or a declared ancestor, since the edge may
+ * point out of a topic nested inside the broker — is tagged #external and
+ * resolves to no known service directory. The resolution guard is what keeps
+ * a mis-tagged internal service reading as unproduced: a tag is cheap to
+ * write, and a services/<id>/ directory outranks it.
+ */
+/**
+ * The authorization vocabulary graded against the fleet that uses it — the half
+ * of the axis no single service can answer.
+ *
+ * `permissions.invalid` is an error and it is the only one reported when it
+ * fires: a vocabulary nobody can read resolves nothing, so every `Requires:`
+ * line in the fleet would follow it as `permissions.unknown`, and a hundred
+ * findings about one broken file is a cascade, not a diagnosis.
+ *
+ * `permissions.unenforced` is the mirror of `api.ungoverned`, and it earns its
+ * place for the same reason: a vocabulary is only worth what cites it. A
+ * permission nothing requires is either a rule that was removed and left its
+ * word behind, or a word nobody adopted — both are drift, and neither is
+ * visible from inside the file. Warn, because the honest answer is sometimes
+ * "not modelled yet".
+ */
+export async function permissionFindings(docsDir, services, fleet) {
+    const vocabulary = await readVocabulary(permissionsPath(docsDir));
+    if (!vocabulary.present)
+        return [];
+    if (vocabulary.invalid !== undefined) {
+        return [
+            {
+                severity: "error",
+                code: "permissions.invalid",
+                message: `landscape: architecture/permissions.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +
+                    "Every `Requires:` line in the fleet resolves against this file, so none of them can be graded until it parses. " +
+                    "The shape is `subjects: {<kind>: {description}}` then `permissions: {<kind>: {<name>: {description, owned_by, enforced_by}}}`.",
+            },
+        ];
+    }
+    const used = new Set();
+    for (const entry of services) {
+        const paths = servicePathsAt(entry.dir);
+        for (const path of [paths.spec, paths.archSpec]) {
+            // Existence first, and for BOTH readers: arch.spec.md is optional (most
+            // of a legacy fleet has none) and spec.md is missing on a half-adopted
+            // service. `FleetContext.readRequirements` throws ENOENT, which surfaces
+            // as `repository-unavailable` and takes the whole `--all` run down — an
+            // absent optional artifact must never be able to do that.
+            if (!existsSync(path))
+                continue;
+            const reqs = fleet === undefined ? await readRequirementsAt(path) : await fleet.readRequirements(path);
+            for (const r of reqs) {
+                if (r.kind !== "REMOVED")
+                    for (const p of r.requires)
+                        used.add(p);
+            }
+        }
+    }
+    const unenforced = [...vocabulary.byId.keys()].filter((id) => !used.has(id));
+    if (unenforced.length === 0)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "permissions.unenforced",
+            message: `landscape: ${unenforced.length} declared permission(s) that no requirement's \`Requires:\` line names — write the requirement that gates on each, or drop the declaration`,
+            details: unenforced,
+        },
+    ];
+}
+/** The uncached read, for the `--service` path where no fleet context exists. */
+async function readRequirementsAt(path) {
+    if (!existsSync(path))
+        return [];
+    return parseRequirements(await readFile(path, "utf8"));
+}
+/**
+ * The capability vocabulary graded against the fleet that realizes it — the
+ * axis's fleet half, beside permissionFindings and shaped by the same two
+ * verdicts. `capability.invalid` is a `validate --all` run's ONE finding about
+ * an unreadable file — fleet scope, so single-target runs stay silent about
+ * it — and it suppresses the rest of the family (the unknown
+ * grades at every service target return [] for the same vocabulary — one
+ * breach, one finding, never a cascade). `capability.unrealized` is one warn
+ * PER declared-but-unnamed capability, subject = the id, because the roadmap's
+ * criterion is 'one warning per capability, not one per service'. Holding
+ * NEITHER `architecture/capabilities.yaml` nor `capabilities/` is total
+ * silence: the fleet's own files are this axis's opt-in, either of them.
+ *
+ * The used set comes through capabilityRollup with the fleet's own cached
+ * reader, so under --all the walk re-parses nothing the service targets have
+ * not already paid for — and the rollup, the warn and `loam list capabilities`
+ * can never disagree about what "realized" means.
+ *
+ * The AUTHORED documents are graded here too, and they ride this function
+ * rather than a target of their own for `viewsStaleFindings`' reason one tree
+ * over: a capability belongs to no service, so only the fleet run has the whole
+ * vocabulary and the enumerated tree in view at once. Their reads are NOT
+ * wrapped, deliberately — a `capabilities/<id>/spec.md` that is not UTF-8 takes
+ * the run down exactly as a `services/<id>/spec.md` does, because a document
+ * loam cannot decode is a refusal everywhere else in the product and a quiet
+ * "zero requirements" here would grade a whole capability green on bytes
+ * nobody read.
+ */
+export async function capabilityFleetFindings(docsDir, services, fleet, flows) {
+    const vocab = fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);
+    if (!vocab.present)
+        return [];
+    const read = fleet === undefined ? readRequirementsAt : (p) => fleet.readRequirements(p);
+    const authored = docMissingFindings(vocab.tree);
+    for (const doc of vocab.tree.docs)
+        authored.push(...capabilityDocFindings(await read(doc.spec), doc.id));
+    const invalid = invalidVocabularyFinding(vocab);
+    if (invalid !== null)
+        return [invalid, ...authored];
+    // A USE CASE IS THE OTHER WAY TO KEEP A PROMISE, and it is the only carrier a
+    // cross-service criterion has: "I enter a login and a password and I am in"
+    // belongs to no single service's spec, so a fleet could satisfy it perfectly
+    // through a `#cap-`/`#req-` tagged flow and still be told nobody realizes it.
+    //
+    // The claims go INTO the rollup rather than beside it, so both unrealized
+    // grades and `loam list capabilities` read one set of rows. `flows === null`
+    // means loam could not READ the flows (no preload, or an `architecture/` that
+    // did not parse); the key is then OMITTED rather than empty, and every
+    // `keptBy` below is `undefined` — the three-state contract `rollup.ts` states.
+    const index = await capabilityRequirementIndex(vocab, read);
+    const keptByFlows = flows === null
+        ? undefined
+        : useCaseRequirementClaims(flows, gradableCapabilityIds(vocab), (c) => index.byCapability.get(c));
+    const rows = await capabilityRollup({ services, vocab, read, ...(keptByFlows === undefined ? {} : { keptByFlows }) });
+    // The two unrealized grades read the SAME rollup, which is what keeps them
+    // from disagreeing about the word: a capability is unrealized when nothing
+    // names it by any join, and one of its requirements is unrealized when nothing
+    // keeps that promise. Both are warnings, and the second is the one that
+    // survives a healthy-looking row — a capability with four requirements and
+    // three kept reports nothing at all through the first.
+    //
+    // The suspension falls out of the DATA rather than a branch: `keptBy` absent
+    // means nobody looked, and a promise nobody looked for is not a promise
+    // reported unkept.
+    const unrealizedRequirements = rows.flatMap((row) => (row.requirements ?? [])
+        .filter((req) => req.realizedBy.length === 0 && req.keptBy?.length === 0)
+        .map((req) => ({ capability: row.id, id: req.id, name: req.name })));
+    return [
+        ...authored,
+        ...unrealizedFindings(vocab, usedCapabilities(rows)),
+        ...requirementUnrealizedFindings(unrealizedRequirements),
+    ];
+}
+export function externalProducerOf(message, land, landSvcOf, known) {
+    if (land === null || land.errors.length > 0 || landSvcOf === null)
+        return null;
+    const knownIds = known;
+    const byId = new Map(land.elements.map((e) => [e.id, e]));
+    for (const r of land.relationships) {
+        if (r.publishes !== message)
+            continue;
+        if (knownIds.has(landSvcOf(r.source)))
+            continue;
+        for (let id = r.source;;) {
+            const e = byId.get(id);
+            if (e !== undefined && e.tags.includes(EXTERNAL_TAG))
+                return e.title;
+            const dot = id.lastIndexOf(".");
+            if (dot === -1)
+                break;
+            id = id.slice(0, dot);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=fleet-shape.js.map

package/dist/commands/validate/checks/fleet-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-shape.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/fleet-shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Fleet-shape advisories over the parsed landscape: the two ways a fleet map\n * stops answering questions as it grows, caught while the map is already in\n * memory.\n *\n * Both shapes become visible at service three rather than service two.\n * Ubiquitous infrastructure — logging Kafka, an identity provider, service\n * discovery — takes one inbound edge per modelled service until the map is a\n * hairball around it; deleting the element fixes the picture and loses \"who\n * depends on the Identity Provider\", which is the question the map exists to\n * answer during an incident. Tagging keeps both: the fleet view excludes\n * `#platform`, and a platform view keeps the dependents. And a datastore drawn as a fleet-level\n * peer makes a claim its consumer count either supports or refutes: one\n * consumer means the drawing is false — the store is that service's\n * internals, not a system in its own right — while two or more mean the\n * strongest coupling two services can have, which deserves to be stated\n * rather than inferred.\n *\n * Everything here is O(relationships) over data the fleet target already\n * holds. loam still reads no code and decides no policy: the team chooses\n * what counts as platform and which data is truly shared — these warnings\n * only name the shapes that are usually wrong.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../../core/c4/likec4.js\";\nimport { type DeclaredService, type RawServiceId } from \"../../../core/kernel/ids/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { type ServiceEntry } from \"../../../core/repo/entries.js\";\nimport { permissionsPath, servicePathsAt } from \"../../../core/repo/paths.js\";\nimport { readVocabulary } from \"../../../core/permissions/permissions.js\";\nimport { readCapabilityVocabulary } from \"../../../core/capabilities/capabilities.js\";\nimport {\n  capabilityDocFindings,\n  capabilityRequirementIndex,\n  docMissingFindings,\n  gradableCapabilityIds,\n  invalidVocabularyFinding,\n  unrealizedFindings,\n} from \"../../../core/capabilities/findings.js\";\nimport { useCaseRequirementClaims } from \"../../../core/usecases/capability.js\";\nimport type { ParsedView } from \"../../../core/c4/parsed/dynamic-views.js\";\nimport { capabilityRollup, usedCapabilities } from \"../../../core/capabilities/rollup.js\";\nimport { requirementUnrealizedFindings } from \"../../../core/capabilities/realizes/findings.js\";\nimport { parseRequirements } from \"../../../core/document/parse.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { EXTERNAL_TAG, PLATFORM_TAG } from \"../../../core/vocabulary/maturity.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/**\n * Consumers at which an untagged external hub starts to warn. Three, not two:\n * two services sharing a dependency is a fact about those two services, the\n * same edge from three is a pattern about the element — and three is where\n * the shared hub starts making the map unreadable.\n */\nexport const PLATFORM_CANDIDATE_MIN_CONSUMERS = 3;\n\n/** The element kind read as a datastore, compared case-insensitively. */\nconst DATASTORE_KIND = \"database\";\n\nexport interface FleetShape {\n  /** Service-LEVEL elements — the fleet map's own boxes (landscape.ts `drawn`). */\n  drawn: Elem[];\n  relationships: Rel[];\n  /** The services/<id>/ directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * Where a service id's directory actually sits, repo-relative and without a\n   * trailing slash. Injected rather than joined: only the enumeration knows\n   * whether a service is filed under a subsystem, and a fix instruction naming\n   * the wrong directory is worse than one naming none.\n   */\n  pathOf: (id: string) => string;\n}\n\nexport function fleetShapeFindings(shape: FleetShape): Finding[] {\n  const { drawn, relationships, services, resolve } = shape;\n  const findings: Finding[] = [];\n\n  // Distinct consumer SERVICES of an element, its nested children included: an\n  // edge into `kafka.paymentEvents` is consumption of `kafka`. Persons, other\n  // external systems and unresolved sources never count — a consumer is a\n  // source the shared resolver files under a real services/<id>/, so two edges\n  // from one service are one consumer.\n  const consumersOf = (e: Elem): string[] => {\n    const out = new Set<string>();\n    for (const r of relationships) {\n      if (r.target !== e.id && !r.target.startsWith(`${e.id}.`)) continue;\n      const svc = resolve(r.source);\n      if (services.has(svc)) out.add(svc);\n    }\n    return [...out].sort();\n  };\n\n  for (const e of drawn) {\n    // An element that stands for a real service is the fleet itself, not its\n    // shape: many consumers is what a well-used service looks like, and a\n    // datastore bound to a directory is graded by the binding checks instead.\n    if (e.service !== undefined || services.has(e.title)) continue;\n    const consumers = consumersOf(e);\n\n    if (\n      e.tags.includes(EXTERNAL_TAG) &&\n      !e.tags.includes(PLATFORM_TAG) &&\n      consumers.length >= PLATFORM_CANDIDATE_MIN_CONSUMERS\n    ) {\n      findings.push({\n        severity: \"warn\",\n        code: \"landscape.platform-candidate\",\n        subject: e.title,\n        message:\n          `landscape: '${e.title}' is consumed by ${consumers.length} services (${consumers.join(\", \")}) ` +\n          `and is not tagged #platform — a hub like this takes one more edge per modelled service until ` +\n          `the fleet view is unreadable. Declare \\`tag platform\\` in the specification block and tag the ` +\n          `element (LikeC4 refuses an undeclared tag, so both steps are needed): the fleet view then ` +\n          `excludes it, and a platform view over \\`include * -> element.tag = #platform\\` keeps ` +\n          `\"who depends on it\" answerable`,\n      });\n    }\n\n    if (e.kind.toLowerCase() !== DATASTORE_KIND || consumers.length === 0) continue;\n    if (consumers.length === 1) {\n      findings.push({\n        severity: \"warn\",\n        code: \"landscape.datastore-private\",\n        subject: e.title,\n        message:\n          `landscape: '${e.title}' is a datastore with a single consumer at fleet level ` +\n          `('${consumers[0]!}') — drawn as a peer it reads as a system in its own right, available to ` +\n          `be depended on. Move it into ${shape.pathOf(consumers[0]!)}/model.likec4 as a nested container ` +\n          `and delete it here, or add the second consumer's edge if another service really reaches ` +\n          `the same data`,\n      });\n    } else {\n      findings.push({\n        severity: \"warn\",\n        code: \"landscape.datastore-shared\",\n        subject: e.title,\n        message:\n          `landscape: '${e.title}' is a datastore shared by ${consumers.length} services ` +\n          `(${consumers.join(\", \")}) — the strongest coupling two services can have, and the hardest ` +\n          `to undo. Shared means the same DATA: if they read the same tables or keys, keep it drawn ` +\n          `and let this warning state the coupling; if they only share a host or cluster (two schemas, ` +\n          `two lock paths), that is operational blast radius — a runbook fact — and the honest model ` +\n          `is one private store per service`,\n      });\n    }\n  }\n  return findings;\n}\n\n/**\n * The #external element that declares it PUBLISHES this message, or null —\n * the landscape-side half of the event spine's fleet question, beside the\n * other checks that read tags off the drawn map.\n *\n * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`\n * whose source element — itself or a declared ancestor, since the edge may\n * point out of a topic nested inside the broker — is tagged #external and\n * resolves to no known service directory. The resolution guard is what keeps\n * a mis-tagged internal service reading as unproduced: a tag is cheap to\n * write, and a services/<id>/ directory outranks it.\n */\n/**\n * The authorization vocabulary graded against the fleet that uses it — the half\n * of the axis no single service can answer.\n *\n * `permissions.invalid` is an error and it is the only one reported when it\n * fires: a vocabulary nobody can read resolves nothing, so every `Requires:`\n * line in the fleet would follow it as `permissions.unknown`, and a hundred\n * findings about one broken file is a cascade, not a diagnosis.\n *\n * `permissions.unenforced` is the mirror of `api.ungoverned`, and it earns its\n * place for the same reason: a vocabulary is only worth what cites it. A\n * permission nothing requires is either a rule that was removed and left its\n * word behind, or a word nobody adopted — both are drift, and neither is\n * visible from inside the file. Warn, because the honest answer is sometimes\n * \"not modelled yet\".\n */\nexport async function permissionFindings(\n  docsDir: DocsDir,\n  services: ServiceEntry[],\n  fleet: FleetContext | undefined,\n): Promise<Finding[]> {\n  const vocabulary = await readVocabulary(permissionsPath(docsDir));\n  if (!vocabulary.present) return [];\n  if (vocabulary.invalid !== undefined) {\n    return [\n      {\n        severity: \"error\",\n        code: \"permissions.invalid\",\n        message:\n          `landscape: architecture/permissions.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +\n          \"Every `Requires:` line in the fleet resolves against this file, so none of them can be graded until it parses. \" +\n          \"The shape is `subjects: {<kind>: {description}}` then `permissions: {<kind>: {<name>: {description, owned_by, enforced_by}}}`.\",\n      },\n    ];\n  }\n  const used = new Set<string>();\n  for (const entry of services) {\n    const paths = servicePathsAt(entry.dir);\n    for (const path of [paths.spec, paths.archSpec]) {\n      // Existence first, and for BOTH readers: arch.spec.md is optional (most\n      // of a legacy fleet has none) and spec.md is missing on a half-adopted\n      // service. `FleetContext.readRequirements` throws ENOENT, which surfaces\n      // as `repository-unavailable` and takes the whole `--all` run down — an\n      // absent optional artifact must never be able to do that.\n      if (!existsSync(path)) continue;\n      const reqs = fleet === undefined ? await readRequirementsAt(path) : await fleet.readRequirements(path);\n      for (const r of reqs) {\n        if (r.kind !== \"REMOVED\") for (const p of r.requires) used.add(p);\n      }\n    }\n  }\n  const unenforced = [...vocabulary.byId.keys()].filter((id) => !used.has(id));\n  if (unenforced.length === 0) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"permissions.unenforced\",\n      message: `landscape: ${unenforced.length} declared permission(s) that no requirement's \\`Requires:\\` line names — write the requirement that gates on each, or drop the declaration`,\n      details: unenforced,\n    },\n  ];\n}\n\n/** The uncached read, for the `--service` path where no fleet context exists. */\nasync function readRequirementsAt(path: string): Promise<Requirement[]> {\n  if (!existsSync(path)) return [];\n  return parseRequirements(await readFile(path, \"utf8\"));\n}\n\n/**\n * The capability vocabulary graded against the fleet that realizes it — the\n * axis's fleet half, beside permissionFindings and shaped by the same two\n * verdicts. `capability.invalid` is a `validate --all` run's ONE finding about\n * an unreadable file — fleet scope, so single-target runs stay silent about\n * it — and it suppresses the rest of the family (the unknown\n * grades at every service target return [] for the same vocabulary — one\n * breach, one finding, never a cascade). `capability.unrealized` is one warn\n * PER declared-but-unnamed capability, subject = the id, because the roadmap's\n * criterion is 'one warning per capability, not one per service'. Holding\n * NEITHER `architecture/capabilities.yaml` nor `capabilities/` is total\n * silence: the fleet's own files are this axis's opt-in, either of them.\n *\n * The used set comes through capabilityRollup with the fleet's own cached\n * reader, so under --all the walk re-parses nothing the service targets have\n * not already paid for — and the rollup, the warn and `loam list capabilities`\n * can never disagree about what \"realized\" means.\n *\n * The AUTHORED documents are graded here too, and they ride this function\n * rather than a target of their own for `viewsStaleFindings`' reason one tree\n * over: a capability belongs to no service, so only the fleet run has the whole\n * vocabulary and the enumerated tree in view at once. Their reads are NOT\n * wrapped, deliberately — a `capabilities/<id>/spec.md` that is not UTF-8 takes\n * the run down exactly as a `services/<id>/spec.md` does, because a document\n * loam cannot decode is a refusal everywhere else in the product and a quiet\n * \"zero requirements\" here would grade a whole capability green on bytes\n * nobody read.\n */\nexport async function capabilityFleetFindings(\n  docsDir: DocsDir,\n  services: ServiceEntry[],\n  fleet: FleetContext | undefined,\n  flows: readonly ParsedView[] | null,\n): Promise<Finding[]> {\n  const vocab = fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);\n  if (!vocab.present) return [];\n  const read = fleet === undefined ? readRequirementsAt : (p: string) => fleet.readRequirements(p);\n  const authored: Finding[] = docMissingFindings(vocab.tree);\n  for (const doc of vocab.tree.docs) authored.push(...capabilityDocFindings(await read(doc.spec), doc.id));\n\n  const invalid = invalidVocabularyFinding(vocab);\n  if (invalid !== null) return [invalid, ...authored];\n  // A USE CASE IS THE OTHER WAY TO KEEP A PROMISE, and it is the only carrier a\n  // cross-service criterion has: \"I enter a login and a password and I am in\"\n  // belongs to no single service's spec, so a fleet could satisfy it perfectly\n  // through a `#cap-`/`#req-` tagged flow and still be told nobody realizes it.\n  //\n  // The claims go INTO the rollup rather than beside it, so both unrealized\n  // grades and `loam list capabilities` read one set of rows. `flows === null`\n  // means loam could not READ the flows (no preload, or an `architecture/` that\n  // did not parse); the key is then OMITTED rather than empty, and every\n  // `keptBy` below is `undefined` — the three-state contract `rollup.ts` states.\n  const index = await capabilityRequirementIndex(vocab, read);\n  const keptByFlows =\n    flows === null\n      ? undefined\n      : useCaseRequirementClaims(flows, gradableCapabilityIds(vocab), (c) => index.byCapability.get(c));\n  const rows = await capabilityRollup({ services, vocab, read, ...(keptByFlows === undefined ? {} : { keptByFlows }) });\n\n  // The two unrealized grades read the SAME rollup, which is what keeps them\n  // from disagreeing about the word: a capability is unrealized when nothing\n  // names it by any join, and one of its requirements is unrealized when nothing\n  // keeps that promise. Both are warnings, and the second is the one that\n  // survives a healthy-looking row — a capability with four requirements and\n  // three kept reports nothing at all through the first.\n  //\n  // The suspension falls out of the DATA rather than a branch: `keptBy` absent\n  // means nobody looked, and a promise nobody looked for is not a promise\n  // reported unkept.\n  const unrealizedRequirements = rows.flatMap((row) =>\n    (row.requirements ?? [])\n      .filter((req) => req.realizedBy.length === 0 && req.keptBy?.length === 0)\n      .map((req) => ({ capability: row.id, id: req.id, name: req.name })),\n  );\n  return [\n    ...authored,\n    ...unrealizedFindings(vocab, usedCapabilities(rows)),\n    ...requirementUnrealizedFindings(unrealizedRequirements),\n  ];\n}\n\nexport function externalProducerOf(\n  message: string,\n  land: LoadedDoc | null,\n  landSvcOf: ((id: string) => DeclaredService) | null,\n  known: ReadonlySet<RawServiceId>,\n): string | null {\n  if (land === null || land.errors.length > 0 || landSvcOf === null) return null;\n  const knownIds: ReadonlySet<string> = known;\n  const byId = new Map(land.elements.map((e) => [e.id, e]));\n  for (const r of land.relationships) {\n    if (r.publishes !== message) continue;\n    if (knownIds.has(landSvcOf(r.source))) continue;\n    for (let id = r.source; ; ) {\n      const e = byId.get(id);\n      if (e !== undefined && e.tags.includes(EXTERNAL_TAG)) return e.title;\n      const dot = id.lastIndexOf(\".\");\n      if (dot === -1) break;\n      id = id.slice(0, dot);\n    }\n  }\n  return null;\n}\n"]}

package/dist/commands/validate/checks/health-deps.js

@@ -0,0 +1,55 @@
+/**
+ * The health.yaml → model reconciliation: every id the `dependencies:` block
+ * declares must be something this service's OWN model answers to.
+ *
+ * Without this reconciliation, a disabled optional service registry can leave
+ * the model, landscape, arch spec and runbook corrected while health.yaml still
+ * declares `serviceRegistry` as a `critical: startup` dependency under a green
+ * validator — in the file an on-call engineer reaches for first. Its
+ * dependencies block was otherwise free text as far as validation was
+ * concerned.
+ *
+ * Resolution is against the SERVICE'S OWN model — deliberately never the
+ * landscape. A private datastore lives nested inside the service element
+ * (`landscape.datastore-private` is the check pushing it there), so the
+ * landscape carries only what crosses the service boundary, while the model
+ * carries everything the service touches — and that is the set the on-call
+ * file has to agree with. An id resolves by the same names every other join
+ * uses: the element's likec4 id, its `metadata { service }` binding, or its
+ * title. Exact match, no case folding — a fold would be a permanent
+ * equivalence semantic no other loam join has, able to silently join two
+ * genuinely different names; the did-you-mean hint bridges the typo case
+ * instead.
+ */
+import { closeIds } from "../../../core/c4/arch.js";
+import {} from "../../../core/c4/likec4.js";
+import { elementService } from "../../../core/c4/resolve/service.js";
+import {} from "../../../core/vocabulary/report.js";
+export function healthDependencyFindings(deps) {
+    const { service, dependencies, elements, modelPath } = deps;
+    // An absent or unparsable model already has its own finding, and grading
+    // health.yaml against a model nobody could read would manufacture warns out
+    // of the wrong file's breakage.
+    if (elements.length === 0)
+        return [];
+    const findings = [];
+    for (const dep of dependencies) {
+        if (elements.some((e) => e.id === dep || elementService(e) === dep))
+            continue;
+        const pool = [...new Set(elements.flatMap((e) => [e.id, elementService(e)]))];
+        const close = closeIds(dep, pool);
+        findings.push({
+            severity: "warn",
+            code: "health.dependency-unmodelled",
+            subject: service,
+            message: `${service}: health.yaml declares dependency '${dep}' but nothing in ` +
+                `${modelPath} answers to that name — either a dependency nobody ` +
+                `modelled, or one that no longer exists. Model it (an external system as its own element ` +
+                `with the edge this service actually has; a private store as a nested container), or ` +
+                `delete the entry` +
+                (close.length > 0 ? `. Did you mean: ${close.join(", ")}?` : ""),
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=health-deps.js.map

package/dist/commands/validate/checks/health-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-deps.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/health-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAa,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAkBlE,MAAM,UAAU,wBAAwB,CAAC,IAAgB;IACvD,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC5D,yEAAyE;IACzE,4EAA4E;IAC5E,gCAAgC;IAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;YAAE,SAAS;QAC9E,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,8BAA8B;YACpC,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,OAAO,sCAAsC,GAAG,mBAAmB;gBACtE,GAAG,SAAS,qDAAqD;gBACjE,0FAA0F;gBAC1F,sFAAsF;gBACtF,kBAAkB;gBAClB,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;SACnE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The health.yaml → model reconciliation: every id the `dependencies:` block\n * declares must be something this service's OWN model answers to.\n *\n * Without this reconciliation, a disabled optional service registry can leave\n * the model, landscape, arch spec and runbook corrected while health.yaml still\n * declares `serviceRegistry` as a `critical: startup` dependency under a green\n * validator — in the file an on-call engineer reaches for first. Its\n * dependencies block was otherwise free text as far as validation was\n * concerned.\n *\n * Resolution is against the SERVICE'S OWN model — deliberately never the\n * landscape. A private datastore lives nested inside the service element\n * (`landscape.datastore-private` is the check pushing it there), so the\n * landscape carries only what crosses the service boundary, while the model\n * carries everything the service touches — and that is the set the on-call\n * file has to agree with. An id resolves by the same names every other join\n * uses: the element's likec4 id, its `metadata { service }` binding, or its\n * title. Exact match, no case folding — a fold would be a permanent\n * equivalence semantic no other loam join has, able to silently join two\n * genuinely different names; the did-you-mean hint bridges the typo case\n * instead.\n */\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type Elem } from \"../../../core/c4/likec4.js\";\nimport { elementService } from \"../../../core/c4/resolve/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface HealthDeps {\n  service: string;\n  /**\n   * The resolved path of the service's own `model.likec4` — the file this\n   * check reads and the one its message names. Handed in rather than joined\n   * from the id: `services/<id>/model.likec4` is right only for an unfiled\n   * service, and every sibling finding in this command prints the resolved\n   * path of the file it means.\n   */\n  modelPath: string;\n  /** `dependencies:` ids, already muted by the caller when health.yaml is unreadable. */\n  dependencies: string[];\n  /** The service's own parsed model — empty when absent or invalid, which mutes the check. */\n  elements: Elem[];\n}\n\nexport function healthDependencyFindings(deps: HealthDeps): Finding[] {\n  const { service, dependencies, elements, modelPath } = deps;\n  // An absent or unparsable model already has its own finding, and grading\n  // health.yaml against a model nobody could read would manufacture warns out\n  // of the wrong file's breakage.\n  if (elements.length === 0) return [];\n  const findings: Finding[] = [];\n  for (const dep of dependencies) {\n    if (elements.some((e) => e.id === dep || elementService(e) === dep)) continue;\n    const pool = [...new Set(elements.flatMap((e) => [e.id, elementService(e) as string]))];\n    const close = closeIds(dep, pool);\n    findings.push({\n      severity: \"warn\",\n      code: \"health.dependency-unmodelled\",\n      subject: service,\n      message:\n        `${service}: health.yaml declares dependency '${dep}' but nothing in ` +\n        `${modelPath} answers to that name — either a dependency nobody ` +\n        `modelled, or one that no longer exists. Model it (an external system as its own element ` +\n        `with the edge this service actually has; a private store as a nested container), or ` +\n        `delete the entry` +\n        (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n    });\n  }\n  return findings;\n}\n"]}