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

package/dist/commands/validate/service/model/diverged.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diverged.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/model/diverged.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `c4.declaration-diverged` — the check the \"every shared element is declared\n * once per document\" report asked for.\n *\n * A STANDALONE model has to re-declare every element it talks about: it is\n * parsed alone, so `kafka`, `uaa` and each peer service appear a second time,\n * with a second kind, a second title, a second tag list and a second binding.\n * Nothing compared the copies. Measured on the fleet that filed the report: 78\n * double declarations across 56 services, and the copies had already drifted —\n * `#platform` was on the map's elements and missing from the models'.\n *\n * WHAT IS COMPARED, and why exactly these four. `kind`, `title`, the tag SET and\n * the `metadata { service }` binding each change what loam concludes or what a\n * view shows: the kind decides which specification rule applies and which\n * exemptions (`ACTOR_KINDS`, `#external`) fire, the title is a resolver fallback\n * when nothing is bound, a tag is graded (`#external`, `#obl-…`), and the\n * binding decides which directory an edge is filed under. `description` is\n * deliberately NOT compared: it is prose, nothing joins on it, and reporting two\n * differently-worded sentences as a divergence would train a reader to ignore\n * the code.\n *\n * WHICH TWO DECLARATIONS ARE ONE ELEMENT is `counterpart` below, and it is the\n * half the first release got wrong: it joined on the literal id, so in a GROUPED\n * map — one that nests its services under `marketplace`, as loam's own example\n * does — a model's `paymentService` never met the map's\n * `marketplace.paymentService` and the check was silent on every fleet that\n * groups (verification 2026-09-04, W3). The three rungs are ordered by how much\n * they assume: the id, then the `metadata { service }` binding both sides wrote,\n * then a unique dotted TAIL of the map's id. Ambiguity is never resolved by\n * picking one — a key two map elements answer to joins nothing, because a\n * divergence reported against the wrong peer is worse than the silence. And the\n * BARE last segment is a tail only when the map element it names is a\n * FLEET-LEVEL box: see `joinIndex`, where the first release of the tail rung\n * joined one service's `db` to another service's.\n *\n * WHAT \"FLEET-LEVEL\" MEANS, spelled once here because three pages spelled it\n * differently and all three were wrong (verification 2026-09-04, second pass):\n * a map element NO ANCESTOR of which stands for a service — `serviceLevelElements`,\n * the one predicate every fleet check asks this question with. That is a\n * top-level element, and equally a child of a plain grouping element: a map\n * that draws `infra = group 'Infra' { cache = database … }` is drawing the\n * fleet's cache, at fleet level, and a standalone model that declares its own\n * top-level `cache` IS shadowing that box — the two documents give one name two\n * meanings, which is the thing this code exists to report. What the rung must\n * never reach is an element drawn INSIDE a service's own element: that is\n * somebody's interior, it belongs to that service, and a model's private `db`\n * being told to copy another service's `db` verbatim is the wrong-join class\n * the tail rung was restricted for in the first place.\n *\n * SILENT WHEN THE MAP DOES NOT PARSE, and when the model does not: a diff\n * against half a document is invention, and both states already have a finding\n * of their own.\n *\n * The repair has two forms on purpose. Copying the map's declaration verbatim\n * keeps the standalone shape, which is legal forever; migrating the model to\n * extend the map removes the copy altogether, which is the only fix that cannot\n * drift again. Except where the first repair is a no-op, and `copyIsNoOp`\n * decides that by SIMULATING it rather than by pattern-matching one shape of it:\n * a tag difference that survives the copy comes off the two documents'\n * `specification` blocks, so the message names the block instead.\n */\nimport type { Elem, LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport type { DocSpecification } from \"../../../../core/c4/parsed/specification.js\";\nimport type { ServiceModel } from \"../../../../core/c4/service-model/load.js\";\nimport type { PathableService } from \"../../../../core/kernel/ids/service.js\";\nimport { ARTIFACT_FILES } from \"../../../../core/repo/paths.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { serviceLevelElements } from \"../../fleet/census.js\";\n\n/**\n * How the OTHER declaration is named.\n *\n * The document, not the file: `Elem` carries no source path, and the map is a\n * PROJECT — `architecture/landscape.likec4` plus every other `.likec4` under\n * `architecture/` — so naming the landscape file was a guess that sent an author\n * to a document that does not declare the element at all.\n */\nconst MAP = \"the fleet map (architecture/)\";\n\nexport interface DivergenceCheck {\n  service: PathableService;\n  model: ServiceModel;\n  /** The `architecture/` project — the map as every other fleet check reads it. Null when the repo has none. */\n  architecture: LoadedDoc | null;\n  /**\n   * Every `services/<id>/` that exists — the census's positive evidence, which\n   * is what tells a map's fleet-level box from a container drawn inside a\n   * service. Only the bare-last-segment tail join reads it; see `joinIndex`.\n   */\n  known: ReadonlySet<string>;\n}\n\nexport function divergedFindings(check: DivergenceCheck): Finding[] {\n  const { service, model, architecture, known } = check;\n  // An extending model declares each of these elements exactly once by\n  // construction — there is no copy to diverge — and the shapes' other grade\n  // (`c4.element-unowned`) is what asks its question.\n  if (model.shape !== \"standalone\") return [];\n  if (model.doc.errors.length > 0) return [];\n  if (architecture === null || architecture.errors.length > 0) return [];\n\n  const index = joinIndex(architecture.elements, known);\n  const findings: Finding[] = [];\n  for (const mine of model.doc.elements) {\n    const theirs = counterpart(index, mine);\n    if (theirs === undefined) continue;\n    const fields = differing(mine, theirs);\n    if (fields.length === 0) continue;\n    // Where \"copy the map's declaration verbatim\" is a no-op: the tag sets are\n    // all that differ (so the two kinds are equal, and the block to open can be\n    // named) and copying the map's literal tags across would leave them still\n    // differing. `fields` is checked first because copying DOES fix a title or a\n    // binding, so the verbatim remedy stays right whenever one of those differs.\n    const specs = { mine: model.doc.specification, theirs: architecture.specification };\n    const inherited =\n      fields.length === 1 && fields[0] === \"tags\" && copyIsNoOp(mine, theirs, specs)\n        ? declaringSide(mine.kind, specs)\n        : null;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.declaration-diverged\",\n      subject: service,\n      message:\n        `${service}: ${ARTIFACT_FILES.model} declares '${mine.id}' as ${describe(mine)} and ` +\n        `${MAP} declares ${theirs.id === mine.id ? \"it\" : `'${theirs.id}'`} as ${describe(theirs)} — ` +\n        remedy(fields, mine.kind, inherited),\n    });\n  }\n  return findings;\n}\n\n/**\n * What the message says after the two declarations: which fields differ, and\n * what to do about it. `inherited` is null when copying the map's declaration\n * fixes this, and otherwise the clause naming which document's `specification`\n * puts the tags on the kind — the side an author has to open.\n */\nfunction remedy(fields: string[], kind: string, inherited: string | null): string {\n  // \"the kind differs\" / \"the title differs\" / \"the tags differ\": the verb\n  // agrees with the last field named, and `tags` is the one plural noun in the\n  // set. It shipped as \"the kind differ\", and a sentence a reader trips over is\n  // one they stop reading.\n  const plural = fields.length > 1 || fields[fields.length - 1] === \"tags\";\n  const named = `the ${fields.join(\", \")} differ${plural ? \"\" : \"s\"}`;\n  // The two kinds are equal whenever `tags` is the only differing field, so the\n  // block to open can be named exactly.\n  if (inherited !== null) {\n    return (\n      `${named}, and copying the map's declaration would not clear it: the sets come apart on ` +\n      `\\`specification { element ${kind} { … } }\\`, ${inherited}. Either match the two specification ` +\n      'blocks on that kind, or migrate the model to extend the map (SCHEMA.md, \"Two shapes of a service ' +\n      'model\") so there is one specification and one declaration'\n    );\n  }\n  return (\n    `${named}, so two documents are two authorities on one element. Copy the map's declaration verbatim, or ` +\n    'migrate the model to extend the map (SCHEMA.md, \"Two shapes of a service model\") so it is declared once'\n  );\n}\n\n/** The map's elements, indexed by each key `counterpart` may join on — ambiguous keys dropped. */\ninterface JoinIndex {\n  byId: Map<string, Elem>;\n  byBinding: Map<string, Elem>;\n  bySuffix: Map<string, Elem>;\n}\n\nfunction joinIndex(elements: readonly Elem[], known: ReadonlySet<string>): JoinIndex {\n  // Which map elements are the fleet's own boxes rather than somebody's\n  // interior, by the ONE predicate every other fleet check asks it with\n  // (`fleet/census.ts`): a binding or a title naming a real services/<id>/ makes\n  // an element a service at any depth, and what sits inside one is that\n  // service's container. Everything else is fleet-level — a top-level element,\n  // or a box the map draws inside a plain grouping element — see the header.\n  const fleetLevel = new Set(serviceLevelElements([...elements], known).map((e) => e.id));\n  return {\n    byId: unique(elements, (e) => [e.id]),\n    byBinding: unique(elements, (e) => (e.service === undefined ? [] : [e.service as string])),\n    // Every DOTTED tail of the id, so a model's `paymentService.api` reaches the\n    // map's `marketplace.paymentService.api`: a tail carrying a dot names the\n    // owner as well as the leaf, so the two documents are talking about one\n    // element.\n    //\n    // The bare LAST segment names only the leaf, and it is emitted for\n    // FLEET-LEVEL boxes alone. This shipped unconditional, and the comment\n    // here claimed it was not: a standalone model's own `db`, `api` or `agent`\n    // joined whatever `<something>.<that name>` the map happened to hold — one\n    // service's private cache told to copy another service's store, verbatim.\n    // loam's own meta/docs hit it (`agent` ↔ `loam.core.agent`, a container of\n    // src/core/agent/), which is the case that made the rung wrong rather than\n    // merely risky (verification 2026-09-04).\n    //\n    // A box the map draws inside a plain GROUP still emits its bare segment,\n    // and deliberately: `infra.cache` is the fleet's cache, so a model's own\n    // top-level `cache` is a second meaning for one name and worth the warning.\n    // Grouping is a drawing convenience, not ownership — only a SERVICE owns an\n    // interior — so the guard is \"no ancestor stands for a service\" and not\n    // \"the id carries no dot\".\n    bySuffix: unique(elements, (e) => {\n      const segments = e.id.split(\".\");\n      const tails = segments.map((_, i) => segments.slice(i).join(\".\"));\n      return fleetLevel.has(e.id) ? tails : tails.slice(0, -1);\n    }),\n  };\n}\n\n/** An index holding only the keys exactly ONE element answers to — a shared key joins nothing. */\nfunction unique(elements: readonly Elem[], keys: (e: Elem) => string[]): Map<string, Elem> {\n  const claims = new Map<string, Elem[]>();\n  for (const element of elements) {\n    for (const key of keys(element)) {\n      const held = claims.get(key);\n      if (held === undefined) claims.set(key, [element]);\n      else held.push(element);\n    }\n  }\n  const index = new Map<string, Elem>();\n  for (const [key, held] of claims) if (held.length === 1) index.set(key, held[0]!);\n  return index;\n}\n\n/** The map's declaration of the element this model declares, or undefined when nothing joins. */\nfunction counterpart(index: JoinIndex, mine: Elem): Elem | undefined {\n  const byId = index.byId.get(mine.id);\n  if (byId !== undefined) return byId;\n  // The binding is the strongest evidence after the id: both documents wrote\n  // `metadata { service '<id>' }`, so both mean the same directory.\n  const bound = mine.service === undefined ? undefined : index.byBinding.get(mine.service as string);\n  if (bound !== undefined) return bound;\n  return index.bySuffix.get(mine.id);\n}\n\n/** Which of the four compared fields disagree, in a fixed order so two runs read alike. */\nfunction differing(mine: Elem, theirs: Elem): string[] {\n  const fields: string[] = [];\n  if (mine.kind !== theirs.kind) fields.push(\"kind\");\n  if (mine.title !== theirs.title) fields.push(\"title\");\n  // A SET, sorted: tag order is authoring order and means nothing, and a model\n  // that lists the map's two tags the other way round is the same declaration.\n  if (tagList(mine) !== tagList(theirs)) fields.push(\"tags\");\n  if (mine.service !== theirs.service) fields.push(\"service binding\");\n  return fields;\n}\n\nfunction tagList(e: Elem): string {\n  return [...new Set(e.tags)].sort().join(\" \");\n}\n\n/** The two documents' `specification` blocks, as `copyIsNoOp` and `declaringSide` read them. */\ninterface SpecPair {\n  mine: DocSpecification | undefined;\n  theirs: DocSpecification | undefined;\n}\n\n/**\n * Would \"copy the map's declaration verbatim\" leave the tag sets still\n * differing? Answered by SIMULATING the copy, which is the only way to be right\n * about it in both directions.\n *\n * `Elem.tags` is what LikeC4 hands over, and since 1.59.0 that includes every\n * tag the element's kind declares (`core/c4/parsed/specification.ts` says why\n * loam reads the block at all). Copying the map's DECLARATION copies its literal\n * tags into the model and nothing else — the model keeps its own specification —\n * so the model's element would come back carrying `mine's kind defaults ∪ the\n * map's literal tags`, against the map's `its kind defaults ∪ the same literal\n * tags`. Those differ exactly when the two kind defaults differ outside the\n * copied literals, and then the remedy is a no-op.\n *\n * The first version compared the two LITERAL tag lists and switched arms only\n * when they were equal, which caught one direction of the same case and missed\n * its mirror: a model writing `#external` on an element whose map twin inherits\n * `#external #platform` from `element topic { … }` was told to copy the map's\n * bare line, and doing exactly that produced the OTHER arm of this same message\n * (verification 2026-09-04, second pass, examples/docs order-service).\n */\nfunction copyIsNoOp(mine: Elem, theirs: Elem, specs: SpecPair): boolean {\n  const copied = literalTags(theirs, specs.theirs);\n  const after = union(kindTags(mine.kind, specs.mine), copied);\n  const before = union(kindTags(theirs.kind, specs.theirs), copied);\n  return after !== before;\n}\n\n/**\n * Which document's `specification` puts the tags on the kind — the half of the\n * message that tells an author which file to open. \"Both, differently\" is a real\n * state (each block declares its own tag on the same kind) and gets its own\n * words rather than a guess at one side.\n */\nfunction declaringSide(kind: string, specs: SpecPair): string {\n  const mine = kindTags(kind, specs.mine);\n  const theirs = kindTags(kind, specs.theirs);\n  if (mine.length > 0 && theirs.length > 0) return \"which the two documents declare different tags on\";\n  if (theirs.length > 0) return `which ${MAP} declares tags on and ${ARTIFACT_FILES.model} does not`;\n  if (mine.length > 0) return `which ${ARTIFACT_FILES.model} declares tags on and ${MAP} does not`;\n  // No kind declares anything and the copy still fails: not reachable from the\n  // predicate above (with equal kinds and no defaults the copy always clears\n  // it), and a sentence that names no file beats one that names the wrong file.\n  return \"which the two documents' blocks disagree on\";\n}\n\n/** The tags `spec` puts on every element of `kind`, sorted — the defaults an element cannot see. */\nfunction kindTags(kind: string, spec: DocSpecification | undefined): string[] {\n  return [...new Set(spec?.elementKindTags[kind] ?? [])].sort();\n}\n\n/** A tag SET as one comparable string; see `tagList` for why order is dropped. */\nfunction union(a: readonly string[], b: readonly string[]): string {\n  return [...new Set([...a, ...b])].sort().join(\" \");\n}\n\nfunction literalTags(e: Elem, spec: DocSpecification | undefined): string[] {\n  const inherited = new Set(kindTags(e.kind, spec));\n  return [...new Set(e.tags)].filter((tag) => !inherited.has(tag)).sort();\n}\n\n/** One element as the message names it — every compared field, in the order `differing` reports them. */\nfunction describe(e: Elem): string {\n  const tags = tagList(e);\n  return `${e.kind} '${e.title}' [${tags === \"\" ? \"no tags\" : tags}, bound to ${e.service ?? \"unbound\"}]`;\n}\n"]}

package/dist/commands/validate/service/model/grade.js

@@ -0,0 +1,163 @@
+/**
+ * How a service's `model.likec4` is GRADED, once `c4/service-model/` has
+ * decided how to read it.
+ *
+ * A package of its own beside `../service.ts` because that module is the ORDER
+ * — it reads what more than one axis joins through and pushes findings in the
+ * sequence the report is read in — and this is one axis's verdicts. Splitting it
+ * out is what let the model gain three arms without the order module gaining
+ * any: the four states below are the loader's four, and each one has exactly one
+ * right answer here.
+ *
+ *  - the map is unreadable (an extending model only): NOTHING. The model could
+ *    not be read, so neither `c4.invalid` nor `c4.valid` is a claim anybody may
+ *    make about it, and blaming N services for one broken document is the
+ *    report. `spine.landscape-invalid` already fires per service and gains a
+ *    clause saying the model went unread with it (`../spine.ts`).
+ *  - errors: `c4.invalid`, exactly as before. For an extending model the details
+ *    name the FILE as well as the line, because a duplicate declaration is
+ *    reported against the map as well as the model, and a bare `L8:` then points
+ *    at somebody else's text.
+ *  - clean, and nothing in the map resolves to this directory:
+ *    `landscape.service-unmodelled` on the SERVICE target. An extending model
+ *    says what is inside an element the map binds; with no such element there is
+ *    nothing to be inside, and every count below would be zero for a file full
+ *    of architecture.
+ *  - clean: `c4.valid`, and one `c4.element-unowned` per element the model
+ *    declared outside its own.
+ */
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { maskSource } from "../../../../core/c4/source-mask.js";
+import { serviceResolver } from "../../../../core/c4/resolve/service.js";
+import { ARTIFACT_FILES } from "../../../../core/repo/paths.js";
+import { errorText } from "../../../../core/c4/likec4.js";
+export async function modelFindings(grade) {
+    const { service, model } = grade;
+    // The map did not parse, so the model was never read. Silence here is the
+    // whole point: `spine.landscape-invalid` is the one finding, and it names the
+    // map rather than blaming a file nobody opened.
+    if (model.mapUnreadable)
+        return [];
+    if (model.doc.errors.length > 0) {
+        return [
+            {
+                severity: "error",
+                code: "c4.invalid",
+                message: `${service}: C4 model has ${model.doc.errors.length} error(s)`,
+                // The hint FIRST, the errors after it: `capDetails` keeps the first ten
+                // lines and drops the rest, and a model written in both shapes at once
+                // stops resolving every kind and every reference in the file — dozens of
+                // cascading errors — so appending the one line that diagnoses it put it
+                // past the cap in exactly the case it exists for (verification
+                // 2026-09-04). It is the diagnosis; the errors are the evidence.
+                details: [...(await extendHint(grade)), ...model.doc.errors.map((err) => detail(err, grade))],
+            },
+        ];
+    }
+    if (model.shape === "extending" && !mapBindsAnElement(grade)) {
+        return [
+            {
+                severity: "error",
+                code: "landscape.service-unmodelled",
+                subject: service,
+                message: `${service}: ${ARTIFACT_FILES.model} extends the fleet map, and no element in ` +
+                    `architecture/landscape.likec4 resolves to ${grade.treePath}/ — nothing in the model can be graded ` +
+                    `until the map binds one (metadata { service '${service}' })`,
+            },
+        ];
+    }
+    const findings = [
+        {
+            severity: "ok",
+            code: "c4.valid",
+            message: `${service}: C4 model valid (` +
+                (model.shape === "extending" ? "extends the fleet map — " : "") +
+                `${model.doc.elements.length} elements · ${model.doc.relationships.length} relationships)` +
+                // Outside the parentheses because the counts inside are facts about
+                // model.likec4 alone and the flows are read from the whole project.
+                (grade.gradedFlows === 0 ? "" : ` · ${grade.gradedFlows} tagged flow(s) graded`),
+        },
+    ];
+    for (const element of model.unowned) {
+        findings.push({
+            severity: "warn",
+            code: "c4.element-unowned",
+            subject: service,
+            message: `${service}: ${ARTIFACT_FILES.model} declares '${element.id}' (${element.kind}) outside this service's ` +
+                "own element — an extending model adds elements under the element that resolves to " +
+                `${service} only. Three remedies, and the FIRST is the one a store or a component usually ` +
+                // The nested arm led the other two from 2026-09-04: a private store's own
+                // remedy was missing here, so following what this printed moved a store
+                // to fleet level and earned `landscape.service-undocumented` (#01/W8).
+                `wants: a store or component this service owns goes INSIDE the \`extend <fqn> { }\` block, ` +
+                "where its id becomes `<fqn>.<name>`; a system this service reaches belongs in " +
+                "architecture/landscape.likec4, declared once; and another service's internals belong in " +
+                "that service's model",
+        });
+    }
+    return findings;
+}
+/**
+ * Does anything in the per-service project resolve to this service?
+ *
+ * The same question `sliceForService` asks to build `own`, asked again rather
+ * than carried on the `ServiceModel`: the slice publishes what a check READS
+ * (the elements, the edges, the strays), and "was the set empty" is a fact
+ * about the map's bindings rather than a fourth list. Resolved over the
+ * PROJECT's elements, because that is the index the slice used and a
+ * nearest-ancestor binding must win here exactly as it does there.
+ *
+ * A standalone model never reaches this: it declares its own elements and
+ * answers for them whether or not the map has heard of the directory — the
+ * fleet target's own `landscape.service-unmodelled` is where that is said.
+ */
+function mapBindsAnElement(grade) {
+    const project = grade.model.project;
+    if (project === null)
+        return true;
+    const resolve = serviceResolver(project.elements, grade.known);
+    return project.elements.some((e) => resolve(e.id) === grade.service);
+}
+/**
+ * One parse error, spelled for the shape it came from.
+ *
+ * A standalone model is one file, so its errors keep the bare `L8: …` form they
+ * have always had — every fixture and every reader of that message is pinned to
+ * it. An extending model is a PROJECT, and LikeC4 reports a duplicate
+ * declaration against BOTH documents: without the file name the reader is sent
+ * to a line number in a file they were never told about, which is the exact
+ * failure `landscape.invalid` fixed one altitude up.
+ */
+function detail(err, grade) {
+    if (grade.model.shape === "standalone" || err.sourceFsPath === undefined)
+        return errorText(err);
+    return `${relative(grade.docsDir, err.sourceFsPath).split(/[\\/]/).join("/")} ${errorText(err)}`;
+}
+/** An `extend` in a masked model — the bytes, not a parse, because the parse is what failed. */
+const EXTENDS = /\bextend\s+[A-Za-z_][\w.-]*\s*\{/;
+/**
+ * The one line that explains a model written in BOTH shapes at once.
+ *
+ * A file declaring an element kind is standalone (SCHEMA.md, "Two shapes of a
+ * service model"), so it is parsed alone — and every `extend <fqn>` in it then
+ * resolves nothing, because the fqn belongs to a map this load never opened.
+ * LikeC4 says `Could not resolve reference to Element named '<fqn>'`, which
+ * reads as a typo; nothing said which of the two lines the author has to drop
+ * (verification 2026-09-04, D10). Emitted only for the standalone shape, where
+ * the diagnosis is certain; an unreadable file adds nothing, since the loader
+ * already answered `standalone` for the same reason and `c4.invalid` names it.
+ */
+async function extendHint(grade) {
+    if (grade.model.shape !== "standalone")
+        return [];
+    const text = await readFile(grade.modelPath, "utf8").catch(() => null);
+    if (text === null || !EXTENDS.test(maskSource(text).code))
+        return [];
+    return [
+        `${ARTIFACT_FILES.model} declares an element kind in \`specification { }\`, so it is read as the ` +
+            "standalone shape — parsed alone, where `extend` resolves nothing. Drop the kind declaration to " +
+            "extend the fleet map, or drop the `extend` and declare the elements here",
+    ];
+}
+//# sourceMappingURL=grade.js.map

package/dist/commands/validate/service/model/grade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grade.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/model/grade.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How a service's `model.likec4` is GRADED, once `c4/service-model/` has\n * decided how to read it.\n *\n * A package of its own beside `../service.ts` because that module is the ORDER\n * — it reads what more than one axis joins through and pushes findings in the\n * sequence the report is read in — and this is one axis's verdicts. Splitting it\n * out is what let the model gain three arms without the order module gaining\n * any: the four states below are the loader's four, and each one has exactly one\n * right answer here.\n *\n *  - the map is unreadable (an extending model only): NOTHING. The model could\n *    not be read, so neither `c4.invalid` nor `c4.valid` is a claim anybody may\n *    make about it, and blaming N services for one broken document is the\n *    report. `spine.landscape-invalid` already fires per service and gains a\n *    clause saying the model went unread with it (`../spine.ts`).\n *  - errors: `c4.invalid`, exactly as before. For an extending model the details\n *    name the FILE as well as the line, because a duplicate declaration is\n *    reported against the map as well as the model, and a bare `L8:` then points\n *    at somebody else's text.\n *  - clean, and nothing in the map resolves to this directory:\n *    `landscape.service-unmodelled` on the SERVICE target. An extending model\n *    says what is inside an element the map binds; with no such element there is\n *    nothing to be inside, and every count below would be zero for a file full\n *    of architecture.\n *  - clean: `c4.valid`, and one `c4.element-unowned` per element the model\n *    declared outside its own.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { maskSource } from \"../../../../core/c4/source-mask.js\";\nimport type { ServiceModel } from \"../../../../core/c4/service-model/load.js\";\nimport { serviceResolver } from \"../../../../core/c4/resolve/service.js\";\nimport type { LikeC4Error } from \"../../../../core/c4/likec4.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { PathableService } from \"../../../../core/kernel/ids/service.js\";\nimport { ARTIFACT_FILES } from \"../../../../core/repo/paths.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { errorText } from \"../../../../core/c4/likec4.js\";\n\nexport interface ModelGrade {\n  service: PathableService;\n  /** Repo-relative, `/`-separated — the directory the map has to bind, named in the unmodelled arm. */\n  treePath: string;\n  docsDir: DocsDir;\n  model: ServiceModel;\n  /** Absolute path of `model.likec4` — read only to explain a parse error, see `extendHint`. */\n  modelPath: string;\n  /** Every service directory that exists — the resolver's positive evidence, exactly as the slice used it. */\n  known: ReadonlySet<string>;\n  /**\n   * How many of this service's own `dynamic view`s carried a reserved tag and\n   * were graded (`core/usecases/service/flows.ts`), counted by the caller\n   * because the scan is the use-case axis's and this is the model's.\n   *\n   * It rides on `c4.valid` and nowhere else. A healthy intra-service flow used\n   * to be invisible on every loam surface — the axis reports only what is wrong\n   * with one — so a team that wrote the slot correctly could not tell it from a\n   * team whose views were never read (verification 2026-09-04, D10).\n   */\n  gradedFlows: number;\n}\n\nexport async function modelFindings(grade: ModelGrade): Promise<Finding[]> {\n  const { service, model } = grade;\n  // The map did not parse, so the model was never read. Silence here is the\n  // whole point: `spine.landscape-invalid` is the one finding, and it names the\n  // map rather than blaming a file nobody opened.\n  if (model.mapUnreadable) return [];\n\n  if (model.doc.errors.length > 0) {\n    return [\n      {\n        severity: \"error\",\n        code: \"c4.invalid\",\n        message: `${service}: C4 model has ${model.doc.errors.length} error(s)`,\n        // The hint FIRST, the errors after it: `capDetails` keeps the first ten\n        // lines and drops the rest, and a model written in both shapes at once\n        // stops resolving every kind and every reference in the file — dozens of\n        // cascading errors — so appending the one line that diagnoses it put it\n        // past the cap in exactly the case it exists for (verification\n        // 2026-09-04). It is the diagnosis; the errors are the evidence.\n        details: [...(await extendHint(grade)), ...model.doc.errors.map((err) => detail(err, grade))],\n      },\n    ];\n  }\n\n  if (model.shape === \"extending\" && !mapBindsAnElement(grade)) {\n    return [\n      {\n        severity: \"error\",\n        code: \"landscape.service-unmodelled\",\n        subject: service,\n        message:\n          `${service}: ${ARTIFACT_FILES.model} extends the fleet map, and no element in ` +\n          `architecture/landscape.likec4 resolves to ${grade.treePath}/ — nothing in the model can be graded ` +\n          `until the map binds one (metadata { service '${service}' })`,\n      },\n    ];\n  }\n\n  const findings: Finding[] = [\n    {\n      severity: \"ok\",\n      code: \"c4.valid\",\n      message:\n        `${service}: C4 model valid (` +\n        (model.shape === \"extending\" ? \"extends the fleet map — \" : \"\") +\n        `${model.doc.elements.length} elements · ${model.doc.relationships.length} relationships)` +\n        // Outside the parentheses because the counts inside are facts about\n        // model.likec4 alone and the flows are read from the whole project.\n        (grade.gradedFlows === 0 ? \"\" : ` · ${grade.gradedFlows} tagged flow(s) graded`),\n    },\n  ];\n  for (const element of model.unowned) {\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.element-unowned\",\n      subject: service,\n      message:\n        `${service}: ${ARTIFACT_FILES.model} declares '${element.id}' (${element.kind}) outside this service's ` +\n        \"own element — an extending model adds elements under the element that resolves to \" +\n        `${service} only. Three remedies, and the FIRST is the one a store or a component usually ` +\n        // The nested arm led the other two from 2026-09-04: a private store's own\n        // remedy was missing here, so following what this printed moved a store\n        // to fleet level and earned `landscape.service-undocumented` (#01/W8).\n        `wants: a store or component this service owns goes INSIDE the \\`extend <fqn> { }\\` block, ` +\n        \"where its id becomes `<fqn>.<name>`; a system this service reaches belongs in \" +\n        \"architecture/landscape.likec4, declared once; and another service's internals belong in \" +\n        \"that service's model\",\n    });\n  }\n  return findings;\n}\n\n/**\n * Does anything in the per-service project resolve to this service?\n *\n * The same question `sliceForService` asks to build `own`, asked again rather\n * than carried on the `ServiceModel`: the slice publishes what a check READS\n * (the elements, the edges, the strays), and \"was the set empty\" is a fact\n * about the map's bindings rather than a fourth list. Resolved over the\n * PROJECT's elements, because that is the index the slice used and a\n * nearest-ancestor binding must win here exactly as it does there.\n *\n * A standalone model never reaches this: it declares its own elements and\n * answers for them whether or not the map has heard of the directory — the\n * fleet target's own `landscape.service-unmodelled` is where that is said.\n */\nfunction mapBindsAnElement(grade: ModelGrade): boolean {\n  const project = grade.model.project;\n  if (project === null) return true;\n  const resolve = serviceResolver(project.elements, grade.known);\n  return project.elements.some((e) => resolve(e.id) === (grade.service as string));\n}\n\n/**\n * One parse error, spelled for the shape it came from.\n *\n * A standalone model is one file, so its errors keep the bare `L8: …` form they\n * have always had — every fixture and every reader of that message is pinned to\n * it. An extending model is a PROJECT, and LikeC4 reports a duplicate\n * declaration against BOTH documents: without the file name the reader is sent\n * to a line number in a file they were never told about, which is the exact\n * failure `landscape.invalid` fixed one altitude up.\n */\nfunction detail(err: LikeC4Error, grade: ModelGrade): string {\n  if (grade.model.shape === \"standalone\" || err.sourceFsPath === undefined) return errorText(err);\n  return `${relative(grade.docsDir, err.sourceFsPath).split(/[\\\\/]/).join(\"/\")} ${errorText(err)}`;\n}\n\n/** An `extend` in a masked model — the bytes, not a parse, because the parse is what failed. */\nconst EXTENDS = /\\bextend\\s+[A-Za-z_][\\w.-]*\\s*\\{/;\n\n/**\n * The one line that explains a model written in BOTH shapes at once.\n *\n * A file declaring an element kind is standalone (SCHEMA.md, \"Two shapes of a\n * service model\"), so it is parsed alone — and every `extend <fqn>` in it then\n * resolves nothing, because the fqn belongs to a map this load never opened.\n * LikeC4 says `Could not resolve reference to Element named '<fqn>'`, which\n * reads as a typo; nothing said which of the two lines the author has to drop\n * (verification 2026-09-04, D10). Emitted only for the standalone shape, where\n * the diagnosis is certain; an unreadable file adds nothing, since the loader\n * already answered `standalone` for the same reason and `c4.invalid` names it.\n */\nasync function extendHint(grade: ModelGrade): Promise<string[]> {\n  if (grade.model.shape !== \"standalone\") return [];\n  const text = await readFile(grade.modelPath, \"utf8\").catch(() => null);\n  if (text === null || !EXTENDS.test(maskSource(text).code)) return [];\n  return [\n    `${ARTIFACT_FILES.model} declares an element kind in \\`specification { }\\`, so it is read as the ` +\n      \"standalone shape — parsed alone, where `extend` resolves nothing. Drop the kind declaration to \" +\n      \"extend the fleet map, or drop the `extend` and declare the elements here\",\n  ];\n}\n"]}

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

@@ -11,35 +11,38 @@
  */
 import { existsSync } from "node:fs";
 import { relative } from "node:path";
-import { loadFile } from "../../../core/c4/likec4.js";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/c4/service-model/load.js";
 import { serviceResolver } from "../../../core/c4/resolve/service.js";
 import {} from "../../../core/kernel/ids/service.js";
 import { landscapePath as landscapeFile, permissionsPath } from "../../../core/repo/paths.js";
 import { locateServicePaths } from "../../../core/repo/service-target.js";
 import { readVocabulary } from "../../../core/permissions/permissions.js";
-import { readCapabilityVocabulary } from "../../../core/capabilities/capabilities.js";
-import { capabilityRequirementIndex, capabilityUnknownFindings } from "../../../core/capabilities/findings.js";
-import { realizesStaleFindings, realizesUnknownFindings } from "../../../core/capabilities/realizes/findings.js";
-import { parseRequirements, readRequirementsDocument } from "../../../core/document/parse.js";
+import { capabilityRequirementIndex, capabilityUnknownIssues } from "../../../core/capabilities/findings.js";
+import { realizesStaleFindings, realizesUnknownIssues } from "../../../core/capabilities/realizes/findings.js";
 import { requiresUnknownFindings } from "../checks/requirements.js";
 import { listServices } from "../../../core/repo/repo.js";
-import {} from "../../../core/c4/likec4.js";
 import {} from "../../../core/vocabulary/report.js";
-import { closeIds } from "../../../core/c4/arch.js";
 import { serviceProvenance } from "../../../core/provenance/findings.js";
 import { gherkinFindings } from "../../../core/gherkin/stale.js";
 import { gherkinRoot } from "../../../core/gherkin/stamp.js";
 import { UnsafePathError } from "../../../core/kernel/path-safety.js";
+import { repoPath } from "../../../core/envelope/json.js";
 import { interruptedCommitFinding } from "../../../core/staging/recovery/finding.js";
 import { FleetContext } from "../../../core/fleet-context.js";
-import { errorText } from "../checks/vocabulary.js";
 import { serviceLinkFindings } from "../links/corpus.js";
 import { sourceScopeFindings } from "../checks/sources.js";
-import { apiAxisFindings, generatedContractFindings } from "./api.js";
+import { unknownServiceFinding } from "../checks/introduced.js";
+import { apiAxisFindings } from "./api.js";
+import { generatedContractFindings } from "./contracts/generated.js";
 import { evidencePinFindings } from "./evidence-pins.js";
 import { spineFindings } from "./spine.js";
 import { eventAxisFindings } from "./events/events.js";
 import { archAxisFindings, readServiceSpecs } from "./specs.js";
+import { modelFindings } from "./model/grade.js";
+import { divergedFindings } from "./model/diverged.js";
+import { requirementIdsOf, serviceUseCaseFindings } from "./usecases/usecases.js";
+import { readServiceFlows } from "../../../core/usecases/service/flows.js";
 import { unknownDirectiveFindings } from "../../../core/document/grammar/directives.js";
 export async function validateService(check) {
     const { docsDir, service, repoDir, preloaded, gherkinDir, contracts, fleet } = check;
@@ -53,27 +56,32 @@ export async function validateService(check) {
     const me = service;
     const findings = [];
     const paths = await locateServicePaths(docsDir, service, fleet);
+    // Repo-relative, `/`-separated: the report's own scope, and the spelling
+    // every service-local use-case finding opens with.
+    const treePath = relative(docsDir, paths.dir).replaceAll("\\", "/");
     const report = {
         kind: "service",
         id: service,
-        path: relative(docsDir, paths.dir).replaceAll("\\", "/"),
+        path: treePath,
         findings,
     };
     // A directory that does not exist is a different fact from a directory with
-    // everything missing: validating a typo must say "typo", not "unadopted".
+    // everything missing: validating a typo must say "typo", not "unadopted" —
+    // and a service a feature in flight introduces is neither (checks/introduced.ts).
     if (!existsSync(paths.dir)) {
-        const close = closeIds(service, (await listServices(docsDir, fleet)).map((s) => s.id));
-        findings.push({
-            severity: "error",
-            code: "service.unknown",
-            message: `No service directory at ${paths.dir}.` +
-                (close.length > 0
-                    ? ` Did you mean: ${close.join(", ")}?`
-                    : " `loam list services` shows what exists."),
-            text: { marker: false },
-        });
+        findings.push(await unknownServiceFinding(docsDir, service, treePath, fleet));
         return report;
     }
+    // Which service directories actually exist — the positive evidence
+    // `serviceOf` needs to resolve an edge drawn into a modelled CONTAINER
+    // (`paymentService.api`) back to the service that owns it. Without it every
+    // such edge resolves to the container's own title, i.e. to a service nobody
+    // has ever adopted, and drops out of the spine unnoticed.
+    //
+    // Read before the model rather than after it, because the model is now read
+    // through the same resolver: an extending model's own slice is exactly the
+    // elements this set makes resolvable.
+    const known = new Set((await listServices(docsDir, fleet)).map((s) => s.id));
     // C4 model. Its absence is an error — this is where `adopt` comes in — but it
     // must NOT silence the rest of the gate stack: `loam archive` of a feature
     // introducing a new service creates exactly this state (spec.md, arch.spec.md,
@@ -85,58 +93,84 @@ export async function validateService(check) {
     const hasModel = existsSync(paths.model);
     let elements = [];
     let relationships = [];
+    // The model as its own SHAPE demands it be read — a file parsed alone, or a
+    // slice of the project it extends (`core/c4/service-model/load.ts`). Kept for
+    // the service's own use cases below, which need both its views and which
+    // shape produced them.
+    let model = null;
+    // The service's OWN use cases, scanned here rather than beside the grades it
+    // feeds: `c4.valid` reports how many were graded, and that count is the only
+    // surface a HEALTHY flow appears on. Null means no scan was made — the model
+    // does not parse (`c4.invalid` owns that, and a second load repeats its
+    // cascade under a use-case code) or its map does not (an extending model then
+    // comes back with no errors AND no model, and the flow project would be
+    // staged over the same broken map).
+    let flows = null;
     if (!hasModel) {
         findings.push({
             severity: "error",
             code: "service.no-model",
-            message: `No C4 model at ${paths.model}. Run \`loam adopt\` for '${service}' first.`,
-            text: { marker: false },
+            message: `No C4 model at ${repoPath(docsDir, paths.model)}. Run \`loam adopt\` for '${service}' first.`,
         });
     }
     else {
-        const model = fleet === undefined ? await loadFile(paths.model) : await fleet.loadLikeC4(paths.model);
-        elements = model.elements;
-        relationships = model.relationships;
-        if (model.errors.length > 0) {
-            findings.push({
-                severity: "error",
-                code: "c4.invalid",
-                message: `${service}: C4 model has ${model.errors.length} error(s)`,
-                details: model.errors.map(errorText),
-            });
-        }
-        else {
-            findings.push({
-                severity: "ok",
-                code: "c4.valid",
-                message: `${service}: C4 model valid (${elements.length} elements · ${relationships.length} relationships)`,
+        model = await fleet.serviceModel(docsDir, paths);
+        elements = model.doc.elements;
+        relationships = model.doc.relationships;
+        if (!model.mapUnreadable && model.doc.errors.length === 0) {
+            flows = await readServiceFlows({
+                paths,
+                model: model.doc,
+                known,
+                // An extending model's siblings resolve against the fleet map, so their
+                // project is the docs root's, never the service directory. The project
+                // the model was READ in travels with it because that is the scope of a
+                // view written inside model.likec4: `model.doc` is the service's own
+                // slice, and a hop backed by one of the map's edges is backed wherever
+                // the view sits.
+                ...(model.shape === "extending" && model.project !== null
+                    ? { extending: { docsDir, project: model.project } }
+                    : {}),
             });
         }
+        findings.push(...(await modelFindings({
+            service,
+            treePath,
+            docsDir,
+            model,
+            modelPath: paths.model,
+            known,
+            gradedFlows: flows?.kind === "read" ? flows.views.length : 0,
+        })));
     }
-    // The living landscape, parsed at most once per run: under --all the caller
-    // hands in the doc it already loaded, single-service runs load on demand. It
-    // serves two checks below — the no-openapi grace and the spine.
-    const land = preloaded ??
-        (existsSync(landscapeFile(docsDir))
-            ? fleet === undefined
-                ? await loadFile(landscapeFile(docsDir))
-                : await fleet.loadLikeC4(landscapeFile(docsDir))
-            : null);
-    // Which service directories actually exist — the positive evidence
-    // `serviceOf` needs to resolve an edge drawn into a modelled CONTAINER
-    // (`paymentService.api`) back to the service that owns it. Without it every
-    // such edge resolves to the container's own title, i.e. to a service nobody
-    // has ever adopted, and drops out of the spine unnoticed.
-    const known = new Set((await listServices(docsDir, fleet)).map((s) => s.id));
+    // The fleet map as the PROJECT it is, in EVERY mode — landscape plus every
+    // `architecture/**/*.likec4` minus the generated views file. Single-service
+    // runs used to read `landscape.likec4` alone, which made three answers depend
+    // on which flag the caller happened to pass: a use-case file that does not
+    // parse was `spine.landscape-invalid` under `--all` and silence under
+    // `--service`, an extending model was readable under one and not the other,
+    // and `c4.declaration-diverged` would have compared against a different
+    // document. Under `--all` the caller hands in the doc it already loaded.
+    //
+    // Still gated on the landscape FILE existing: `land === null` means "this repo
+    // draws no fleet", and a repo with an `architecture/usecases/` and no map is
+    // that state, not a map that loaded empty.
+    const land = preloaded ?? (existsSync(landscapeFile(docsDir)) ? await fleet.architecture(docsDir) : null);
+    // Where a standalone model's copies of the map's elements have drifted. After
+    // `c4.valid` because it is a claim about a model that parsed, and silent for
+    // an extending model, which has no copy to diverge.
+    if (model !== null)
+        findings.push(...divergedFindings({ service, model, architecture: land, known }));
     // The living landscape's element→service resolver, container-aware and
     // memoized. Every question below that asks "does this edge point at me?"
     // asks it through this one function, so the no-openapi grace, the HTTP spine
     // and the event spine can never disagree about which edges are inbound.
     const landSvcOf = land === null ? null : serviceResolver(land.elements, known);
-    const specs = await readServiceSpecs({ service, paths, fleet });
+    const specs = await readServiceSpecs({ docsDir, service, paths, fleet });
     findings.push(...specs.findings);
     const { reqs, livingReqs, archText, archReqs } = specs;
     const api = await apiAxisFindings({
+        docsDir,
         service,
         me,
         paths,
@@ -149,11 +183,16 @@ export async function validateService(check) {
     findings.push(...api.findings);
     findings.push(...spineFindings({
         service,
+        docsDir,
+        treePath,
         me,
         land,
         landSvcOf,
         contract: api.contract,
         landscapeReported: check.landscapeReported,
+        // An unreadable map takes an extending model with it, and the spine
+        // finding is where that is said — see `Spine.modelExtends`.
+        modelExtends: model?.shape === "extending",
     }));
     findings.push(...(await eventAxisFindings({
         docsDir,
@@ -175,29 +214,50 @@ export async function validateService(check) {
         archReqs,
         elements,
         relationships,
+        // The one fact that tells "this service models nothing" apart from "this
+        // service's model could not be read" — its map does not parse, or it does
+        // not itself (`c4.invalid` above): both arrive here as empty lists, and
+        // only the second one must silence `covers.unknown`.
+        modelUnreadable: model !== null && (model.mapUnreadable || model.doc.errors.length > 0),
         land,
         known,
+        docsDir,
+        fleet,
     })));
+    // The service's own use cases, GRADED — scanned beside the model above. Here
+    // rather than on the fleet target because the hops name this service's
+    // containers, which only its project resolves; after the arch axis because a
+    // `#req-` tag resolves against the ids both spec documents declare.
+    if (flows !== null) {
+        findings.push(...serviceUseCaseFindings({
+            service,
+            treePath,
+            docsDir,
+            scan: flows,
+            services: known,
+            requirementIds: requirementIdsOf(paths, livingReqs, archReqs),
+        }));
+    }
     // The authorization axis. Both requirement documents are graded against one
     // fleet vocabulary — a permission is a fleet fact, and an arch requirement
     // gates on one exactly as a business requirement does. The capability axis
     // rides the same loop against ITS fleet vocabulary; under --all the fleet
     // memo makes that one parse for the whole run.
     const vocabulary = await readVocabulary(permissionsPath(docsDir));
-    const capabilities = fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);
+    const capabilities = await fleet.capabilities(docsDir);
     // The requirement-level index behind `Realizes:`. Built once for both axes,
-    // and behind the same ladder `capabilityUnknownFindings` applies — an absent
+    // and behind the same ladder `capabilityUnknownIssues` applies — an absent
     // or unreadable vocabulary means no reads and no grades at all, so a fleet
     // that has not adopted the axis pays nothing for a line it never wrote.
-    const capabilityReqs = await capabilityRequirementIndex(capabilities, fleet === undefined ? async (p) => parseRequirements(await readRequirementsDocument(p)) : (p) => fleet.readRequirements(p));
+    const capabilityReqs = await capabilityRequirementIndex(capabilities, (p) => fleet.readRequirements(p));
     for (const [label, docReqs] of [
         ["spec.md", reqs],
         ["arch.spec.md", archReqs],
     ]) {
         const target = { where: `${service}: ${label}`, subject: service };
         findings.push(...requiresUnknownFindings(docReqs, target, vocabulary));
-        findings.push(...capabilityUnknownFindings(docReqs, target, capabilities));
-        findings.push(...realizesUnknownFindings(docReqs, target, capabilityReqs));
+        findings.push(...capabilityUnknownIssues(docReqs, target, capabilities));
+        findings.push(...realizesUnknownIssues(docReqs, target, capabilityReqs));
         findings.push(...realizesStaleFindings(docReqs, target, capabilityReqs));
         // The grammar guard, last in the loop: it grades the KEYS the three checks
         // above resolve values from, so a line none of them saw is reported here
@@ -210,7 +270,7 @@ export async function validateService(check) {
     // document checks and adds no input any of them depend on.
     findings.push(...(await serviceLinkFindings({ docsDir, subject: service, fleet }, paths)));
     // Provenance last: who vouched for this, and what code it was written from.
-    findings.push(...(await serviceProvenance(docsDir, service, { repoDir, fleet })));
+    findings.push(...(await serviceProvenance(docsDir, service, { repoDir, loamOwned: check.loamOwned, fleet })));
     findings.push(...(await sourceScopeFindings(docsDir, service, repoDir, fleet)));
     // The build's own contract against the committed copy. Service-repo only:
     // from the docs repo there is no build output to read, and the family stays