@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/commands/validate/fleet/views/stale.js.map

@@ -1 +1 @@
-{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/stale.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAIxE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgB,EAChB,IAAe,EACf,QAAgB;IAEhB,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnG,IAAI,MAAM;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,KAAK,GACT,MAAM,KAAK,IAAI;QACb,CAAC,CAAC,uDAAuD;QACzD,CAAC,CAAC,QAAQ,KAAK,IAAI;YACjB,CAAC,CAAC,4EAA4E;YAC9E,CAAC,CAAC,yBAAyB,CAAC;IAClC,OAAO;QACL;YACE,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,gCAAgC;YACzC,wEAAwE;YACxE,uEAAuE;YACvE,wDAAwD;YACxD,qEAAqE;YACrE,sEAAsE;YACtE,sEAAsE;YACtE,mCAAmC;YACnC,SAAS,EAAE;gBACT,MAAM,KAAK,IAAI;oBACb,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,OAAgB,EAAE;oBAClD,CAAC,CAAC,EAAE,IAAI,EAAE,gCAAgC,EAAE,IAAI,EAAE,SAAkB,EAAE;aACzE;YACD,OAAO,EACL,8CAA8C,KAAK,KAAK;gBACxD,2GAA2G;gBAC3G,oEAAoE;SACvE;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Staleness of the GENERATED `architecture/subsystems.likec4` against the\n * tree: exactly ONE error on exactly one file, repaired by exactly one\n * command (`loam subsystem sync`).\n *\n * A content compare, deliberately — never a parse. A views-only document does\n * not parse standalone (its `include` lines reference elements the landscape\n * defines; the spike in `core/repo/tree/render/views.ts` records it), and no check\n * anywhere reads the file's MEANING: the file is a scoping convenience for\n * the LikeC4 renderer, so the only question loam owes it is \"is this what the\n * tree renders to\". Rule 26 leaves this untouched: what loam may\n * read is a `dynamic view`'s declared steps out of a document it already\n * parses — never a static view's `include` predicates, and never this\n * generated file at all. Absent counts as a state of its own: a fleet\n * with subsystems and no file is stale, and a fleet with NO subsystems and a\n * leftover file is stale too — the render contract says the file must then\n * not exist, or a group deleted months ago keeps a view forever.\n *\n * The compare is over CONTENT, not BYTES, and `viewsAgree` in\n * `core/repo/tree/render/views.ts` both performs it and records why: an ordinary\n * Windows clone hands this file back with CRLF and not one fact in it changed,\n * and under a byte compare the advertised repair is a loop rather than a\n * diagnosis. The rule lives beside the generator because the module that mints\n * the bytes is the one that owes an answer about them.\n *\n * Graded only when the landscape PARSED (the caller holds that gate): the\n * expected bytes resolve members through the landscape's element→service\n * join, and grading them against a map that is missing or unreadable would\n * cascade a second error behind `landscape.missing`/`landscape.invalid`,\n * pointing at a file whose repair command would only re-derive the same\n * incomplete answer.\n */\nimport type { Elem } from \"../../../../core/c4/likec4.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { subsystemViewsPath } from \"../../../../core/repo/paths.js\";\nimport { viewsState } from \"../../../../core/repo/tree/render/stale.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\nexport async function viewsStaleFindings(\n  docsDir: DocsDir,\n  tree: FleetTree,\n  elements: Elem[],\n): Promise<Finding[]> {\n  const { actual, expected, agrees } = await viewsState(subsystemViewsPath(docsDir), tree, elements);\n  if (agrees) return [];\n  const state =\n    actual === null\n      ? \"does not exist, but the tree has subsystems to mirror\"\n      : expected === null\n        ? \"exists, but the tree has no subsystems — the generated file must be absent\"\n        : \"does not match the tree\";\n  return [\n    {\n      severity: \"error\",\n      code: \"subsystem.views-stale\",\n      subject: \"architecture/subsystems.likec4\",\n      // The file the message names, so an editor jumping to the finding lands\n      // on it. Without a location the report's fallback files this under the\n      // TARGET, which is the landscape — a reader was sent to\n      // architecture/landscape.likec4 to fix a file the sentence beside it\n      // named as architecture/subsystems.likec4. A file that does not exist\n      // yet cannot be `primary`: the actionable place is then the directory\n      // the regenerator will write into.\n      locations: [\n        actual === null\n          ? { path: \"architecture\", role: \"scope\" as const }\n          : { path: \"architecture/subsystems.likec4\", role: \"primary\" as const },\n      ],\n      message:\n        `subsystems: architecture/subsystems.likec4 ${state} — ` +\n        `it is generated, one view per subsystem, and every derived scope drawn from it is wrong until it agrees. ` +\n        \"Run `loam subsystem sync` to regenerate it; never edit it by hand.\",\n    },\n  ];\n}\n"]}
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/stale.ts"],"names":[],"mappings":"AAmDA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAmB,MAAM,4CAA4C,CAAC;AAK5G,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAgB,EAAE,IAAe,EAAE,GAAa;IACvF,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/E,OAAO;QACL,GAAG,YAAY,CAAC,UAAU,EAAE;YAC1B,IAAI,EAAE,gCAAgC;YACtC,MAAM,EAAE,uDAAuD;YAC/D,QAAQ,EAAE,4EAA4E;YACtF,IAAI,EAAE,wFAAwF;SAC/F,CAAC;QACF,GAAG,YAAY,CAAC,QAAQ,EAAE;YACxB,IAAI,EAAE,8BAA8B;YACpC,MAAM,EAAE,wEAAwE;YAChF,QAAQ,EACN,0GAA0G;YAC5G,IAAI,EACF,yGAAyG;gBACzG,2EAA2E;SAC9E,CAAC;KACH,CAAC;AACJ,CAAC;AAcD;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAiB,EAAE,IAAe;IACtD,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAC5B,MAAM,IAAI,GACR,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,qCAAqC,CAAC;IACxH,OAAO;QACL;YACE,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,wEAAwE;YACxE,uEAAuE;YACvE,wDAAwD;YACxD,qEAAqE;YACrE,sEAAsE;YACtE,sEAAsE;YACtE,mCAAmC;YACnC,SAAS,EAAE;gBACT,KAAK,CAAC,MAAM,KAAK,IAAI;oBACnB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,OAAgB,EAAE;oBAClD,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,SAAkB,EAAE;aAClD;YACD,OAAO,EACL,eAAe,IAAI,CAAC,IAAI,IAAI,IAAI,uBAAuB,IAAI,CAAC,IAAI,IAAI;gBACpE,oEAAoE;SACvE;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Staleness of the GENERATED documents under `architecture/` against the tree\n * and the map: ONE error per stale file, naming that file, repaired by exactly\n * one command (`loam subsystem sync`).\n *\n * TWO FILES, ONE CODE, and that is a decision rather than an omission.\n * `subsystems.likec4` (one view per subsystem) and `services.likec4` (one\n * overview view per service the map draws) are written by the same command in\n * the same commit, drift for overlapping reasons — a `subsystem move` restales\n * both, because a per-service view's title is `<subsystem path> / <service\n * id>` — and are repaired by the same run. A second code would buy a reader\n * nothing the `subject` and the message do not already say, and every code costs\n * a row in `core/agent/workflows/check.ts`, a `loam explain` entry and a place in\n * the vocabulary. What DOES have to stay apart is which file drifted, so the two\n * are graded separately and each finding carries its own path — folding them\n * into one finding would lose the only thing the message has to say.\n *\n * A content compare, deliberately — never a parse. A views-only document does\n * not parse standalone (its `include` lines reference elements the landscape\n * defines; the spike in `core/repo/tree/render/views.ts` records it), and no check\n * anywhere reads the file's MEANING: the file is a scoping convenience for\n * the LikeC4 renderer, so the only question loam owes it is \"is this what the\n * tree renders to\". Rule 26 leaves this untouched: what loam may\n * read is a `dynamic view`'s declared steps out of a document it already\n * parses — never a static view's `include` predicates, and never this\n * generated file at all. Absent counts as a state of its own: a fleet\n * with subsystems and no file is stale, and a fleet with NO subsystems and a\n * leftover file is stale too — the render contract says the file must then\n * not exist, or a group deleted months ago keeps a view forever.\n *\n * The compare is over CONTENT, not BYTES, and `viewsAgree` in\n * `core/repo/tree/render/views.ts` both performs it and records why: an ordinary\n * Windows clone hands this file back with CRLF and not one fact in it changed,\n * and under a byte compare the advertised repair is a loop rather than a\n * diagnosis. The rule lives beside the generator because the module that mints\n * the bytes is the one that owes an answer about them.\n *\n * Graded only when the landscape PARSED (the caller holds that gate): the\n * expected bytes resolve members through the landscape's element→service\n * join, and grading them against a map that is missing or unreadable would\n * cascade a second error behind `landscape.missing`/`landscape.invalid`,\n * pointing at a file whose repair command would only re-derive the same\n * incomplete answer.\n *\n * The map arrives as the parsed document's facts — its elements AND the\n * global style ids it declares — because the expected bytes now depend on\n * both: a view references `global style subsystems` exactly when the project\n * declares that id, so a fleet that declares it sees this finding once, until\n * the next `sync` writes the line.\n */\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { serviceViewsPath, subsystemViewsPath } from \"../../../../core/repo/paths.js\";\nimport { serviceViewsState, viewsState, type ViewsState } from \"../../../../core/repo/tree/render/stale.js\";\nimport type { MapFacts } from \"../../../../core/repo/tree/render/views.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\nexport async function viewsStaleFindings(docsDir: DocsDir, tree: FleetTree, map: MapFacts): Promise<Finding[]> {\n  const subsystems = await viewsState(subsystemViewsPath(docsDir), tree, map);\n  const services = await serviceViewsState(serviceViewsPath(docsDir), tree, map);\n  return [\n    ...staleFinding(subsystems, {\n      file: \"architecture/subsystems.likec4\",\n      absent: \"does not exist, but the tree has subsystems to mirror\",\n      leftover: \"exists, but the tree has no subsystems — the generated file must be absent\",\n      what: \"one view per subsystem, and every derived scope drawn from it is wrong until it agrees\",\n    }),\n    ...staleFinding(services, {\n      file: \"architecture/services.likec4\",\n      absent: \"does not exist, but the fleet map draws services this file must mirror\",\n      leftover:\n        \"exists, but the fleet map draws none of the services under services/ — the generated file must be absent\",\n      what:\n        \"one overview view per service the map draws, and every drill-down into a service goes through it, so a \" +\n        \"reader following the map lands on a picture that is wrong until it agrees\",\n    }),\n  ];\n}\n\n/** The four sentences one file's finding differs by — the rest of it is shared. */\ninterface StaleFile {\n  /** The docs-relative path, which is the subject, the location and the head of the message. */\n  file: string;\n  /** Why an absent file is stale. */\n  absent: string;\n  /** Why a present file that must not exist is stale. */\n  leftover: string;\n  /** What the file holds, and what is wrong while it disagrees. */\n  what: string;\n}\n\n/**\n * One finding, or none — the shape both generated files share, spelled once so\n * they cannot drift into two dialects of the same sentence.\n */\nfunction staleFinding(state: ViewsState, file: StaleFile): Finding[] {\n  if (state.agrees) return [];\n  const said =\n    state.actual === null ? file.absent : state.expected === null ? file.leftover : \"does not match the tree and the map\";\n  return [\n    {\n      severity: \"error\",\n      code: \"subsystem.views-stale\",\n      subject: file.file,\n      // The file the message names, so an editor jumping to the finding lands\n      // on it. Without a location the report's fallback files this under the\n      // TARGET, which is the landscape — a reader was sent to\n      // architecture/landscape.likec4 to fix a file the sentence beside it\n      // named as architecture/subsystems.likec4. A file that does not exist\n      // yet cannot be `primary`: the actionable place is then the directory\n      // the regenerator will write into.\n      locations: [\n        state.actual === null\n          ? { path: \"architecture\", role: \"scope\" as const }\n          : { path: file.file, role: \"primary\" as const },\n      ],\n      message:\n        `subsystems: ${file.file} ${said} — it is generated, ${file.what}. ` +\n        \"Run `loam subsystem sync` to regenerate it; never edit it by hand.\",\n    },\n  ];\n}\n"]}

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

@@ -0,0 +1,226 @@
+import { ARTIFACT_FILES } from "../../../../core/repo/paths.js";
+import { serviceLevelElements } from "../../fleet/census.js";
+/**
+ * How the OTHER declaration is named.
+ *
+ * The document, not the file: `Elem` carries no source path, and the map is a
+ * PROJECT — `architecture/landscape.likec4` plus every other `.likec4` under
+ * `architecture/` — so naming the landscape file was a guess that sent an author
+ * to a document that does not declare the element at all.
+ */
+const MAP = "the fleet map (architecture/)";
+export function divergedFindings(check) {
+    const { service, model, architecture, known } = check;
+    // An extending model declares each of these elements exactly once by
+    // construction — there is no copy to diverge — and the shapes' other grade
+    // (`c4.element-unowned`) is what asks its question.
+    if (model.shape !== "standalone")
+        return [];
+    if (model.doc.errors.length > 0)
+        return [];
+    if (architecture === null || architecture.errors.length > 0)
+        return [];
+    const index = joinIndex(architecture.elements, known);
+    const findings = [];
+    for (const mine of model.doc.elements) {
+        const theirs = counterpart(index, mine);
+        if (theirs === undefined)
+            continue;
+        const fields = differing(mine, theirs);
+        if (fields.length === 0)
+            continue;
+        // Where "copy the map's declaration verbatim" is a no-op: the tag sets are
+        // all that differ (so the two kinds are equal, and the block to open can be
+        // named) and copying the map's literal tags across would leave them still
+        // differing. `fields` is checked first because copying DOES fix a title or a
+        // binding, so the verbatim remedy stays right whenever one of those differs.
+        const specs = { mine: model.doc.specification, theirs: architecture.specification };
+        const inherited = fields.length === 1 && fields[0] === "tags" && copyIsNoOp(mine, theirs, specs)
+            ? declaringSide(mine.kind, specs)
+            : null;
+        findings.push({
+            severity: "warn",
+            code: "c4.declaration-diverged",
+            subject: service,
+            message: `${service}: ${ARTIFACT_FILES.model} declares '${mine.id}' as ${describe(mine)} and ` +
+                `${MAP} declares ${theirs.id === mine.id ? "it" : `'${theirs.id}'`} as ${describe(theirs)} — ` +
+                remedy(fields, mine.kind, inherited),
+        });
+    }
+    return findings;
+}
+/**
+ * What the message says after the two declarations: which fields differ, and
+ * what to do about it. `inherited` is null when copying the map's declaration
+ * fixes this, and otherwise the clause naming which document's `specification`
+ * puts the tags on the kind — the side an author has to open.
+ */
+function remedy(fields, kind, inherited) {
+    // "the kind differs" / "the title differs" / "the tags differ": the verb
+    // agrees with the last field named, and `tags` is the one plural noun in the
+    // set. It shipped as "the kind differ", and a sentence a reader trips over is
+    // one they stop reading.
+    const plural = fields.length > 1 || fields[fields.length - 1] === "tags";
+    const named = `the ${fields.join(", ")} differ${plural ? "" : "s"}`;
+    // The two kinds are equal whenever `tags` is the only differing field, so the
+    // block to open can be named exactly.
+    if (inherited !== null) {
+        return (`${named}, and copying the map's declaration would not clear it: the sets come apart on ` +
+            `\`specification { element ${kind} { … } }\`, ${inherited}. Either match the two specification ` +
+            'blocks on that kind, or migrate the model to extend the map (SCHEMA.md, "Two shapes of a service ' +
+            'model") so there is one specification and one declaration');
+    }
+    return (`${named}, so two documents are two authorities on one element. Copy the map's declaration verbatim, or ` +
+        'migrate the model to extend the map (SCHEMA.md, "Two shapes of a service model") so it is declared once');
+}
+function joinIndex(elements, known) {
+    // Which map elements are the fleet's own boxes rather than somebody's
+    // interior, by the ONE predicate every other fleet check asks it with
+    // (`fleet/census.ts`): a binding or a title naming a real services/<id>/ makes
+    // an element a service at any depth, and what sits inside one is that
+    // service's container. Everything else is fleet-level — a top-level element,
+    // or a box the map draws inside a plain grouping element — see the header.
+    const fleetLevel = new Set(serviceLevelElements([...elements], known).map((e) => e.id));
+    return {
+        byId: unique(elements, (e) => [e.id]),
+        byBinding: unique(elements, (e) => (e.service === undefined ? [] : [e.service])),
+        // Every DOTTED tail of the id, so a model's `paymentService.api` reaches the
+        // map's `marketplace.paymentService.api`: a tail carrying a dot names the
+        // owner as well as the leaf, so the two documents are talking about one
+        // element.
+        //
+        // The bare LAST segment names only the leaf, and it is emitted for
+        // FLEET-LEVEL boxes alone. This shipped unconditional, and the comment
+        // here claimed it was not: a standalone model's own `db`, `api` or `agent`
+        // joined whatever `<something>.<that name>` the map happened to hold — one
+        // service's private cache told to copy another service's store, verbatim.
+        // loam's own meta/docs hit it (`agent` ↔ `loam.core.agent`, a container of
+        // src/core/agent/), which is the case that made the rung wrong rather than
+        // merely risky (verification 2026-09-04).
+        //
+        // A box the map draws inside a plain GROUP still emits its bare segment,
+        // and deliberately: `infra.cache` is the fleet's cache, so a model's own
+        // top-level `cache` is a second meaning for one name and worth the warning.
+        // Grouping is a drawing convenience, not ownership — only a SERVICE owns an
+        // interior — so the guard is "no ancestor stands for a service" and not
+        // "the id carries no dot".
+        bySuffix: unique(elements, (e) => {
+            const segments = e.id.split(".");
+            const tails = segments.map((_, i) => segments.slice(i).join("."));
+            return fleetLevel.has(e.id) ? tails : tails.slice(0, -1);
+        }),
+    };
+}
+/** An index holding only the keys exactly ONE element answers to — a shared key joins nothing. */
+function unique(elements, keys) {
+    const claims = new Map();
+    for (const element of elements) {
+        for (const key of keys(element)) {
+            const held = claims.get(key);
+            if (held === undefined)
+                claims.set(key, [element]);
+            else
+                held.push(element);
+        }
+    }
+    const index = new Map();
+    for (const [key, held] of claims)
+        if (held.length === 1)
+            index.set(key, held[0]);
+    return index;
+}
+/** The map's declaration of the element this model declares, or undefined when nothing joins. */
+function counterpart(index, mine) {
+    const byId = index.byId.get(mine.id);
+    if (byId !== undefined)
+        return byId;
+    // The binding is the strongest evidence after the id: both documents wrote
+    // `metadata { service '<id>' }`, so both mean the same directory.
+    const bound = mine.service === undefined ? undefined : index.byBinding.get(mine.service);
+    if (bound !== undefined)
+        return bound;
+    return index.bySuffix.get(mine.id);
+}
+/** Which of the four compared fields disagree, in a fixed order so two runs read alike. */
+function differing(mine, theirs) {
+    const fields = [];
+    if (mine.kind !== theirs.kind)
+        fields.push("kind");
+    if (mine.title !== theirs.title)
+        fields.push("title");
+    // A SET, sorted: tag order is authoring order and means nothing, and a model
+    // that lists the map's two tags the other way round is the same declaration.
+    if (tagList(mine) !== tagList(theirs))
+        fields.push("tags");
+    if (mine.service !== theirs.service)
+        fields.push("service binding");
+    return fields;
+}
+function tagList(e) {
+    return [...new Set(e.tags)].sort().join(" ");
+}
+/**
+ * Would "copy the map's declaration verbatim" leave the tag sets still
+ * differing? Answered by SIMULATING the copy, which is the only way to be right
+ * about it in both directions.
+ *
+ * `Elem.tags` is what LikeC4 hands over, and since 1.59.0 that includes every
+ * tag the element's kind declares (`core/c4/parsed/specification.ts` says why
+ * loam reads the block at all). Copying the map's DECLARATION copies its literal
+ * tags into the model and nothing else — the model keeps its own specification —
+ * so the model's element would come back carrying `mine's kind defaults ∪ the
+ * map's literal tags`, against the map's `its kind defaults ∪ the same literal
+ * tags`. Those differ exactly when the two kind defaults differ outside the
+ * copied literals, and then the remedy is a no-op.
+ *
+ * The first version compared the two LITERAL tag lists and switched arms only
+ * when they were equal, which caught one direction of the same case and missed
+ * its mirror: a model writing `#external` on an element whose map twin inherits
+ * `#external #platform` from `element topic { … }` was told to copy the map's
+ * bare line, and doing exactly that produced the OTHER arm of this same message
+ * (verification 2026-09-04, second pass, examples/docs order-service).
+ */
+function copyIsNoOp(mine, theirs, specs) {
+    const copied = literalTags(theirs, specs.theirs);
+    const after = union(kindTags(mine.kind, specs.mine), copied);
+    const before = union(kindTags(theirs.kind, specs.theirs), copied);
+    return after !== before;
+}
+/**
+ * Which document's `specification` puts the tags on the kind — the half of the
+ * message that tells an author which file to open. "Both, differently" is a real
+ * state (each block declares its own tag on the same kind) and gets its own
+ * words rather than a guess at one side.
+ */
+function declaringSide(kind, specs) {
+    const mine = kindTags(kind, specs.mine);
+    const theirs = kindTags(kind, specs.theirs);
+    if (mine.length > 0 && theirs.length > 0)
+        return "which the two documents declare different tags on";
+    if (theirs.length > 0)
+        return `which ${MAP} declares tags on and ${ARTIFACT_FILES.model} does not`;
+    if (mine.length > 0)
+        return `which ${ARTIFACT_FILES.model} declares tags on and ${MAP} does not`;
+    // No kind declares anything and the copy still fails: not reachable from the
+    // predicate above (with equal kinds and no defaults the copy always clears
+    // it), and a sentence that names no file beats one that names the wrong file.
+    return "which the two documents' blocks disagree on";
+}
+/** The tags `spec` puts on every element of `kind`, sorted — the defaults an element cannot see. */
+function kindTags(kind, spec) {
+    return [...new Set(spec?.elementKindTags[kind] ?? [])].sort();
+}
+/** A tag SET as one comparable string; see `tagList` for why order is dropped. */
+function union(a, b) {
+    return [...new Set([...a, ...b])].sort().join(" ");
+}
+function literalTags(e, spec) {
+    const inherited = new Set(kindTags(e.kind, spec));
+    return [...new Set(e.tags)].filter((tag) => !inherited.has(tag)).sort();
+}
+/** One element as the message names it — every compared field, in the order `differing` reports them. */
+function describe(e) {
+    const tags = tagList(e);
+    return `${e.kind} '${e.title}' [${tags === "" ? "no tags" : tags}, bound to ${e.service ?? "unbound"}]`;
+}
+//# sourceMappingURL=diverged.js.map

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"]}