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

package/dist/commands/validate/fleet/views/projects.js

@@ -0,0 +1,278 @@
+/**
+ * The four ways a service's `model.likec4` and the renderer's project files can
+ * disagree, graded as one warning per service on the fleet target — plus the
+ * one way the same root config can hide the fleet MAP, graded once for the
+ * fleet (`landscape.excluded`, at the foot of this module).
+ *
+ * They are one walk because they are one question — "can the renderer actually
+ * show what this model says?" — asked of the two shapes a model has. A model
+ * that STANDS ALONE (declares its own element kinds) is parsed alone: it needs a
+ * project file of its own, and the root project must exclude its directory. A
+ * model that EXTENDS the fleet map declares no kinds and lives IN the root
+ * project: it must NOT be excluded, and a project file beside it TAKES it out of
+ * there — measured at the 1.59.2 pin, the nested project claims the model, which
+ * then does not resolve (the map's kinds are not in there with it) and the fleet
+ * project loses the service's interior. Each shape therefore owes the opposite of
+ * the other, and each of the four codes below is one half of one of those pairs:
+ *
+ *  - `service.likec4-config-missing` — standalone, no project file.
+ *  - `service.likec4-config-stray`   — extending, project file present.
+ *  - `service.model-excluded`        — extending, root `exclude` covers it. Two
+ *    questions, not one: the DIRECTORY (`excludingEntry`, which `subsystem sync`
+ *    can repair) and, where that says no, the model FILE (`excludingPath`, which
+ *    it cannot — the message says so).
+ *  - `service.model-unexcluded`      — standalone, root `exclude` does not.
+ *
+ * `landscape.excluded` is the fifth, and it is the same question asked one
+ * level up: the root `exclude` covering `architecture/landscape.likec4` itself.
+ *
+ * WHY WARNINGS. Every fact loam grades about a model — its parse, its bindings,
+ * its edges into the spine — holds exactly as it did in all five states, so
+ * nothing here may gate. The fifth is only true because the architecture loader
+ * keeps the map whatever the root `exclude` says (`core/c4/project/architecture.ts`);
+ * before it did, an excluded map blanked every cross-service grade in the run. ROADMAP's clause that rendering "must stay outside
+ * validation so view computation cannot slow or change the gate" is about
+ * computing views; this check computes nothing: one `existsSync` per service and
+ * one read of the root config. And the sibling that grades the ROOT file's
+ * absence (`doctor.likec4-config-missing`, `core/doctor/doctor.ts`) calls a repo
+ * without it "only unrenderable" and warns; these are the same condition one
+ * directory down and earn the same severity.
+ *
+ * WHY `validate --all` AND NOT `doctor`. `doctor` is the step-0 preflight of the
+ * adopt protocol — wiring, the config, the fleet map's readability — and the
+ * protocol's step 5 is the `validate --all` run whose findings the agent
+ * branches on. The report that motivated the first of these codes had its own
+ * `doctor --json` answer `healthy: true` with 0 findings on a tree where every
+ * adopted model was unrenderable from the root: the model is written in step 3,
+ * so its renderability is a fact that first exists at step 5, and a preflight
+ * that ran before the model did could not have said otherwise. Never in
+ * `validate --service`, `status` or `doctor`: the writer is a fleet verb
+ * (`subsystem sync`) and the findings belong beside the files that verb owns.
+ *
+ * WHY PER SERVICE. `subject` is the service id so a `--json` worklist filters by
+ * team the way `landscape.service-unmodelled` already lets it — one fleet
+ * finding listing every gap would have to be re-parsed to find out whose it is.
+ * The `scope` location is the service's tree path, through `serviceTreePath` on
+ * the ENTRY the survey hands back — never a join by id: these grades are emitted
+ * before the map's early returns precisely so they hold on a broken tree, and a
+ * tree with two services sharing a leaf name under different subsystems
+ * (`subsystem.name-collision`) is exactly such a tree, still enumerated in full.
+ * Joined by id, both findings named the first directory while `subsystem sync`
+ * wrote both files at the right paths.
+ *
+ * WHY THE ROOT GATE, and it does double duty. Semantically: `subsystem sync`
+ * writes nothing — no per-service file, no rewritten `exclude` — until the root
+ * `likec4.config.json` exists (the docs root is then a LikeC4 workspace and a
+ * nested project is registered inside it — measured at the 1.59.2 pin), so a
+ * repo without the root file has `doctor` telling it to write that first and
+ * nothing to sync into; grading a gap the writer would not fill is a loop no
+ * command can clear. The same rule silences a directory whose name is not a
+ * legal service id: the survey skips it (`render/projects.ts` says why),
+ * `service.id-invalid` already names it, and a warning here would advertise a
+ * repair `sync` refuses to perform. Fixture-wise: `makeProject` writes NO root
+ * file, so every existing fixture stays silent under this gate, and the suites
+ * that pin a fleet's warning set exactly (`test/examples.test.ts`,
+ * `test/self-model.test.ts`) ship the files their shapes call for and keep their
+ * counts.
+ *
+ * The exclude half has a SECOND gate, inside `readRootExclude`: a root config
+ * loam cannot read an `exclude` list out of answers `null`, and both grades that
+ * read it stay silent. loam does not know what the renderer will do with a file
+ * it could not parse, and asserting an exclusion on evidence it does not have is
+ * worse than saying nothing.
+ */
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { excludingEntry, excludingPath, readRootExclude } from "../../../../core/c4/root-project/exclude.js";
+import { serviceTreePath } from "../../../../core/kernel/ids/dirs.js";
+import { ARTIFACT_FILES, landscapePath, LIKEC4_PROJECT_FILENAME, rootProjectPath, serviceRenderPaths } from "../../../../core/repo/paths.js";
+import { surveyProjects } from "../../../../core/repo/tree/render/projects.js";
+/**
+ * `entries` is the fleet enumeration at whatever depth each service lives, and
+ * `shapes` is the shape of every model in it, keyed by resolved path
+ * (`FleetContext.modelShapes`). The shape map is built over the FULL enumeration
+ * rather than a `--base` narrowing: a model missing from it would read as
+ * standalone, which is the wrong half of every pair above.
+ *
+ * The predicate handed into the survey is the ONE spelling of "has a model,
+ * lacks a project file" that `subsystem sync` also fills, so the grader can
+ * never name a gap the writer would leave.
+ */
+export async function projectFindings(docsDir, entries, shapes) {
+    // No root project file, no root project — and no `exclude` list either, so the
+    // map is not excluded by anything loam can see. `false` here is a fact, not a
+    // default: `readRootExclude` would answer `null` one line down and every grade
+    // below it stays silent for the same reason.
+    if (!existsSync(rootProjectPath(docsDir)))
+        return { findings: [], mapExcluded: false };
+    const survey = surveyProjects(entries, serviceRenderPaths, (model) => shapes.get(resolve(model)) !== "extending");
+    const exclude = await readRootExclude(docsDir);
+    const findings = [];
+    // The ONE derivation. The boolean is read off the finding rather than computed
+    // beside it, so a fleet where `c4.fleet-project-invalid` is suspended is by
+    // construction a fleet where `landscape.excluded` says why.
+    const excluded = mapExcluded(docsDir, exclude);
+    findings.push(...excluded);
+    for (const model of survey.models) {
+        const tree = serviceTreePath(model.service);
+        // Everything the four share, so each push below is its code and its
+        // sentence and nothing else. `scope`, not `primary`: two of the four are
+        // about a file that does not exist yet, and the actionable place is the
+        // directory either way.
+        const at = {
+            severity: "warn",
+            subject: model.service.id,
+            locations: [{ path: tree, role: "scope" }],
+        };
+        if (model.standalone && !model.configured) {
+            findings.push({
+                ...at,
+                code: "service.likec4-config-missing",
+                message: `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} exists and ${tree}/${LIKEC4_PROJECT_FILENAME} does not — ` +
+                    "a model that stands alone (declares its own `specification`) renders only as a project of its own, " +
+                    "and nothing renders it from the docs root now. Run `loam subsystem sync`; it writes the file (create-only) — never write it by hand.",
+            });
+        }
+        if (!model.standalone && model.configured) {
+            findings.push({
+                ...at,
+                code: "service.likec4-config-stray",
+                message: `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} extends the fleet map and ${tree}/${LIKEC4_PROJECT_FILENAME} ` +
+                    "sits beside it — the renderer registers that file as a project of its own rooted at that directory, so " +
+                    "the docs root stops being a one-project workspace (`likec4 validate .` then refuses without `--project`), " +
+                    "and wherever that nested project claims the model it parses alone, out of the root project where the " +
+                    "map's kinds are: the model does not resolve and `export json --project fleet` loses this service's " +
+                    "containers (measured, likec4 1.59.2 — which of the two happens depends on the workspace, and neither is " +
+                    "a state this file buys anything in). Run `loam subsystem sync`; it deletes the file (or delete it " +
+                    "yourself). loam never writes one beside an extending model",
+            });
+        }
+        // `excludingEntry` reports the entry VERBATIM because the repair is to
+        // delete or narrow THAT line, and a fleet that files its services under
+        // subsystems is excluded by `services/platform/**` rather than by anything
+        // naming the service — a message that did not quote the entry would send
+        // its reader looking for a line that is not there.
+        const entry = exclude === null ? null : excludingEntry(exclude, tree);
+        // THE SECOND QUESTION, and the state that was silent until it was asked:
+        // an entry shaped like a FILE hides the model without covering the
+        // directory. `services/**/model.likec4` and the bare `**/model.likec4` each
+        // took every extending model out of the renderer on `examples/docs` — 3
+        // source files of 8, five drill-down views gone from the export — with the
+        // whole run reporting 0 errors and not one line containing the word
+        // "exclude" (re-verification 2026-09-04, area C item 5). It is asked ONLY
+        // where the directory question said no, because that arm names an entry
+        // `subsystem sync` can take back and this one names an entry it cannot.
+        const fileEntry = exclude === null || entry !== null ? null : excludingPath(exclude, `${tree}/${ARTIFACT_FILES.model}`);
+        const hiding = entry ?? fileEntry;
+        if (exclude !== null && !model.standalone && hiding !== null) {
+            findings.push({
+                ...at,
+                code: "service.model-excluded",
+                message: `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} extends the fleet map and the root ` +
+                    `${LIKEC4_PROJECT_FILENAME} excludes it ('${hiding}') — the renderer never loads it, so the service is ` +
+                    "a box with nothing inside it from the docs root. " +
+                    (entry === null
+                        ? // The repair is an EDIT, not a command, and saying otherwise is the
+                            // loop `landscape.excluded` already refuses to open: sync recomputes
+                            // only the `services/<tree>/**` entries and would report success
+                            // having changed nothing.
+                            "That entry hides the model file without covering " +
+                                `${tree}/, so \`loam subsystem sync\` cannot repair it: sync maintains only the ` +
+                                "`services/` directory entries and leaves every other line exactly as the team wrote it. Narrow that " +
+                                "entry to the paths it was written for, or delete it"
+                        : "Run `loam subsystem sync`: it rewrites the root project's `exclude` to cover exactly the models " +
+                            "that stand alone"),
+            });
+        }
+        if (exclude !== null && model.standalone && entry === null) {
+            findings.push({
+                ...at,
+                code: "service.model-unexcluded",
+                message: `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} stands alone (declares its own specification) and ` +
+                    `the root ${LIKEC4_PROJECT_FILENAME} does not exclude ${tree}/ — the renderer merges it into the map ` +
+                    "and reports every kind and element it declares as a duplicate, blanking the whole root project. " +
+                    `Run \`loam subsystem sync\`: it adds ${tree}/** to the root project's \`exclude\``,
+            });
+        }
+    }
+    return { findings, mapExcluded: excluded.length > 0 };
+}
+/**
+ * `landscape.excluded` — the root `exclude` covers the fleet MAP itself.
+ *
+ * WHY IT EXISTS AT ALL, and why only now. The architecture loader used to apply
+ * the root `exclude` with no floor under it, so an entry covering
+ * `architecture/landscape.likec4` — an `architecture/*.likec4` written for a
+ * palette, say — left that project EMPTY, and an empty project parses with zero
+ * errors. Every reader downstream took that for "the map declares nothing":
+ * `landscape.service-unmodelled` on every service, `c4.invalid` on every
+ * extending model, `subsystem sync` cutting a good generated file back to a
+ * title (verification 2026-09-04, review C). The loader now keeps the map
+ * whatever the list says, so loam has stopped asserting those falsehoods — but
+ * the RENDERER still applies the entry, and it has no floor. Nothing told the
+ * author that the fleet map they are grading is a map nobody can open. This is
+ * that sentence, and it is the only finding in the run that names it.
+ *
+ * WARN, NEVER GATING, for the reason the module banner gives: with the loader's
+ * floor in place, every fact loam grades holds identically either way. The gap
+ * is a renderer gap, exactly like the four per-service grades above.
+ *
+ * THE SAME ROOT GATE covers it — the caller returns early with no root
+ * `likec4.config.json`, and a config loam cannot read an `exclude` list out of
+ * answers `null`, which says nothing rather than guessing. It is gated on the
+ * map EXISTING as well: with no file there, `landscape.missing` is the finding
+ * and an entry covering a path nobody wrote is not a repair anyone owes.
+ *
+ * `excludingPath`, not `excludingEntry`: the map is a FILE, and this must fire
+ * exactly when `architectureProjectDocuments` would have dropped it — same
+ * list, same matcher, same argument. Asking the directory question instead
+ * would answer for `architecture/` as a whole and miss `architecture/*.likec4`,
+ * which is the spelling that caused the defect.
+ *
+ * The repair is NOT `loam subsystem sync`, and the message says so where the
+ * four grades above name it: sync recomputes only the `services/<tree>/**`
+ * entries and leaves every other line in the order the team wrote it, so it
+ * would report success and change nothing. The four had a writer; this one has
+ * an author.
+ *
+ * AND IT SUSPENDS `c4.fleet-project-invalid`, which is the cascade discipline
+ * `permissions.invalid` and `capability.invalid` already state: a grade that
+ * RESOLVES against a document nobody loaded is not a diagnosis. That check
+ * builds the fleet project the way the renderer does — no floor under the map —
+ * so the very entry named here takes the map out of it and every `extend` in
+ * every extending model then resolves against nothing. Measured on
+ * `examples/docs` with `architecture/*.likec4` in the list: one
+ * `landscape.excluded` and **161** `c4.fleet-project-invalid`, all of them one
+ * line's fault. The message carries that clause so the reader knows the fleet
+ * project is unread rather than clean, and the caller reads the same fact off
+ * `ProjectGrade.mapExcluded` — see `./fleet-project.ts`'s `mapExcluded` gate.
+ */
+function mapExcluded(docsDir, exclude) {
+    const map = landscapePath(docsDir);
+    if (exclude === null || !existsSync(map))
+        return [];
+    const rel = relative(docsDir, map).split(/[\\/]/).join("/");
+    const entry = excludingPath(exclude, rel);
+    if (entry === null)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "landscape.excluded",
+            // Quoted VERBATIM, for `service.model-excluded`'s reason one level down:
+            // the repair is to edit THAT line, and an entry loam re-spelled is a line
+            // its author would go looking for and not find.
+            message: `landscape: the root ${LIKEC4_PROJECT_FILENAME}'s \`exclude\` covers ${rel} ('${entry}') — the renderer never ` +
+                "loads the fleet map, so it draws no map at all and every model that EXTENDS the map resolves against " +
+                "nothing in the root project, while loam goes on grading the map it reads from disk. `c4.fleet-project-invalid` " +
+                "is NOT graded while this entry stands: that check loads the fleet project the way the renderer does, so it " +
+                "would report the same one line as an unresolved reference in every extending model rather than as this. " +
+                "Remove that entry, or " +
+                `narrow it to the paths it was written for, and the fleet project is graded again. \`loam subsystem sync\` ` +
+                "will not do it: that command maintains " +
+                "only the `services/` entries in the list and leaves every other line exactly as the team wrote it",
+            locations: [{ path: rel, role: "primary" }],
+        },
+    ];
+}
+//# sourceMappingURL=projects.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projects.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/projects.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The four ways a service's `model.likec4` and the renderer's project files can\n * disagree, graded as one warning per service on the fleet target — plus the\n * one way the same root config can hide the fleet MAP, graded once for the\n * fleet (`landscape.excluded`, at the foot of this module).\n *\n * They are one walk because they are one question — \"can the renderer actually\n * show what this model says?\" — asked of the two shapes a model has. A model\n * that STANDS ALONE (declares its own element kinds) is parsed alone: it needs a\n * project file of its own, and the root project must exclude its directory. A\n * model that EXTENDS the fleet map declares no kinds and lives IN the root\n * project: it must NOT be excluded, and a project file beside it TAKES it out of\n * there — measured at the 1.59.2 pin, the nested project claims the model, which\n * then does not resolve (the map's kinds are not in there with it) and the fleet\n * project loses the service's interior. Each shape therefore owes the opposite of\n * the other, and each of the four codes below is one half of one of those pairs:\n *\n *  - `service.likec4-config-missing` — standalone, no project file.\n *  - `service.likec4-config-stray`   — extending, project file present.\n *  - `service.model-excluded`        — extending, root `exclude` covers it. Two\n *    questions, not one: the DIRECTORY (`excludingEntry`, which `subsystem sync`\n *    can repair) and, where that says no, the model FILE (`excludingPath`, which\n *    it cannot — the message says so).\n *  - `service.model-unexcluded`      — standalone, root `exclude` does not.\n *\n * `landscape.excluded` is the fifth, and it is the same question asked one\n * level up: the root `exclude` covering `architecture/landscape.likec4` itself.\n *\n * WHY WARNINGS. Every fact loam grades about a model — its parse, its bindings,\n * its edges into the spine — holds exactly as it did in all five states, so\n * nothing here may gate. The fifth is only true because the architecture loader\n * keeps the map whatever the root `exclude` says (`core/c4/project/architecture.ts`);\n * before it did, an excluded map blanked every cross-service grade in the run. ROADMAP's clause that rendering \"must stay outside\n * validation so view computation cannot slow or change the gate\" is about\n * computing views; this check computes nothing: one `existsSync` per service and\n * one read of the root config. And the sibling that grades the ROOT file's\n * absence (`doctor.likec4-config-missing`, `core/doctor/doctor.ts`) calls a repo\n * without it \"only unrenderable\" and warns; these are the same condition one\n * directory down and earn the same severity.\n *\n * WHY `validate --all` AND NOT `doctor`. `doctor` is the step-0 preflight of the\n * adopt protocol — wiring, the config, the fleet map's readability — and the\n * protocol's step 5 is the `validate --all` run whose findings the agent\n * branches on. The report that motivated the first of these codes had its own\n * `doctor --json` answer `healthy: true` with 0 findings on a tree where every\n * adopted model was unrenderable from the root: the model is written in step 3,\n * so its renderability is a fact that first exists at step 5, and a preflight\n * that ran before the model did could not have said otherwise. Never in\n * `validate --service`, `status` or `doctor`: the writer is a fleet verb\n * (`subsystem sync`) and the findings belong beside the files that verb owns.\n *\n * WHY PER SERVICE. `subject` is the service id so a `--json` worklist filters by\n * team the way `landscape.service-unmodelled` already lets it — one fleet\n * finding listing every gap would have to be re-parsed to find out whose it is.\n * The `scope` location is the service's tree path, through `serviceTreePath` on\n * the ENTRY the survey hands back — never a join by id: these grades are emitted\n * before the map's early returns precisely so they hold on a broken tree, and a\n * tree with two services sharing a leaf name under different subsystems\n * (`subsystem.name-collision`) is exactly such a tree, still enumerated in full.\n * Joined by id, both findings named the first directory while `subsystem sync`\n * wrote both files at the right paths.\n *\n * WHY THE ROOT GATE, and it does double duty. Semantically: `subsystem sync`\n * writes nothing — no per-service file, no rewritten `exclude` — until the root\n * `likec4.config.json` exists (the docs root is then a LikeC4 workspace and a\n * nested project is registered inside it — measured at the 1.59.2 pin), so a\n * repo without the root file has `doctor` telling it to write that first and\n * nothing to sync into; grading a gap the writer would not fill is a loop no\n * command can clear. The same rule silences a directory whose name is not a\n * legal service id: the survey skips it (`render/projects.ts` says why),\n * `service.id-invalid` already names it, and a warning here would advertise a\n * repair `sync` refuses to perform. Fixture-wise: `makeProject` writes NO root\n * file, so every existing fixture stays silent under this gate, and the suites\n * that pin a fleet's warning set exactly (`test/examples.test.ts`,\n * `test/self-model.test.ts`) ship the files their shapes call for and keep their\n * counts.\n *\n * The exclude half has a SECOND gate, inside `readRootExclude`: a root config\n * loam cannot read an `exclude` list out of answers `null`, and both grades that\n * read it stay silent. loam does not know what the renderer will do with a file\n * it could not parse, and asserting an exclusion on evidence it does not have is\n * worse than saying nothing.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative, resolve } from \"node:path\";\nimport type { ModelShape } from \"../../../../core/c4/service-model/shape.js\";\nimport { excludingEntry, excludingPath, readRootExclude } from \"../../../../core/c4/root-project/exclude.js\";\nimport { serviceTreePath, type DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { ServiceEntry } from \"../../../../core/repo/entries.js\";\nimport { ARTIFACT_FILES, landscapePath, LIKEC4_PROJECT_FILENAME, rootProjectPath, serviceRenderPaths } from \"../../../../core/repo/paths.js\";\nimport { surveyProjects } from \"../../../../core/repo/tree/render/projects.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/**\n * The five grades, and the one FACT out of them a second check has to branch on.\n *\n * `mapExcluded` is `landscape.excluded`'s own condition, handed out rather than\n * re-derived: `c4.fleet-project-invalid` loads the fleet project the way the\n * RENDERER does — without the architecture loader's floor under the map — so the\n * same entry that hides the map makes every extending model's `extend` fail to\n * resolve, and one bad line in `exclude` came back as 161 warnings on a\n * five-service fleet. Two spellings of \"is the map excluded\" would be two\n * chances for the cause and its cascade to disagree about whether they are\n * looking at the same state, which is exactly the pairing the boolean exists to\n * keep.\n */\nexport interface ProjectGrade {\n  findings: Finding[];\n  /** True when the root `exclude` covers `architecture/landscape.likec4` — see above. */\n  mapExcluded: boolean;\n}\n\n/**\n * `entries` is the fleet enumeration at whatever depth each service lives, and\n * `shapes` is the shape of every model in it, keyed by resolved path\n * (`FleetContext.modelShapes`). The shape map is built over the FULL enumeration\n * rather than a `--base` narrowing: a model missing from it would read as\n * standalone, which is the wrong half of every pair above.\n *\n * The predicate handed into the survey is the ONE spelling of \"has a model,\n * lacks a project file\" that `subsystem sync` also fills, so the grader can\n * never name a gap the writer would leave.\n */\nexport async function projectFindings(\n  docsDir: DocsDir,\n  entries: readonly ServiceEntry[],\n  shapes: ReadonlyMap<string, ModelShape>,\n): Promise<ProjectGrade> {\n  // No root project file, no root project — and no `exclude` list either, so the\n  // map is not excluded by anything loam can see. `false` here is a fact, not a\n  // default: `readRootExclude` would answer `null` one line down and every grade\n  // below it stays silent for the same reason.\n  if (!existsSync(rootProjectPath(docsDir))) return { findings: [], mapExcluded: false };\n  const survey = surveyProjects(entries, serviceRenderPaths, (model) => shapes.get(resolve(model)) !== \"extending\");\n  const exclude = await readRootExclude(docsDir);\n  const findings: Finding[] = [];\n  // The ONE derivation. The boolean is read off the finding rather than computed\n  // beside it, so a fleet where `c4.fleet-project-invalid` is suspended is by\n  // construction a fleet where `landscape.excluded` says why.\n  const excluded = mapExcluded(docsDir, exclude);\n  findings.push(...excluded);\n  for (const model of survey.models) {\n    const tree = serviceTreePath(model.service);\n    // Everything the four share, so each push below is its code and its\n    // sentence and nothing else. `scope`, not `primary`: two of the four are\n    // about a file that does not exist yet, and the actionable place is the\n    // directory either way.\n    const at = {\n      severity: \"warn\" as const,\n      subject: model.service.id,\n      locations: [{ path: tree, role: \"scope\" as const }],\n    };\n    if (model.standalone && !model.configured) {\n      findings.push({\n        ...at,\n        code: \"service.likec4-config-missing\",\n        message:\n          `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} exists and ${tree}/${LIKEC4_PROJECT_FILENAME} does not — ` +\n          \"a model that stands alone (declares its own `specification`) renders only as a project of its own, \" +\n          \"and nothing renders it from the docs root now. Run `loam subsystem sync`; it writes the file (create-only) — never write it by hand.\",\n      });\n    }\n    if (!model.standalone && model.configured) {\n      findings.push({\n        ...at,\n        code: \"service.likec4-config-stray\",\n        message:\n          `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} extends the fleet map and ${tree}/${LIKEC4_PROJECT_FILENAME} ` +\n          \"sits beside it — the renderer registers that file as a project of its own rooted at that directory, so \" +\n          \"the docs root stops being a one-project workspace (`likec4 validate .` then refuses without `--project`), \" +\n          \"and wherever that nested project claims the model it parses alone, out of the root project where the \" +\n          \"map's kinds are: the model does not resolve and `export json --project fleet` loses this service's \" +\n          \"containers (measured, likec4 1.59.2 — which of the two happens depends on the workspace, and neither is \" +\n          \"a state this file buys anything in). Run `loam subsystem sync`; it deletes the file (or delete it \" +\n          \"yourself). loam never writes one beside an extending model\",\n      });\n    }\n    // `excludingEntry` reports the entry VERBATIM because the repair is to\n    // delete or narrow THAT line, and a fleet that files its services under\n    // subsystems is excluded by `services/platform/**` rather than by anything\n    // naming the service — a message that did not quote the entry would send\n    // its reader looking for a line that is not there.\n    const entry = exclude === null ? null : excludingEntry(exclude, tree);\n    // THE SECOND QUESTION, and the state that was silent until it was asked:\n    // an entry shaped like a FILE hides the model without covering the\n    // directory. `services/**/model.likec4` and the bare `**/model.likec4` each\n    // took every extending model out of the renderer on `examples/docs` — 3\n    // source files of 8, five drill-down views gone from the export — with the\n    // whole run reporting 0 errors and not one line containing the word\n    // \"exclude\" (re-verification 2026-09-04, area C item 5). It is asked ONLY\n    // where the directory question said no, because that arm names an entry\n    // `subsystem sync` can take back and this one names an entry it cannot.\n    const fileEntry =\n      exclude === null || entry !== null ? null : excludingPath(exclude, `${tree}/${ARTIFACT_FILES.model}`);\n    const hiding = entry ?? fileEntry;\n    if (exclude !== null && !model.standalone && hiding !== null) {\n      findings.push({\n        ...at,\n        code: \"service.model-excluded\",\n        message:\n          `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} extends the fleet map and the root ` +\n          `${LIKEC4_PROJECT_FILENAME} excludes it ('${hiding}') — the renderer never loads it, so the service is ` +\n          \"a box with nothing inside it from the docs root. \" +\n          (entry === null\n            ? // The repair is an EDIT, not a command, and saying otherwise is the\n              // loop `landscape.excluded` already refuses to open: sync recomputes\n              // only the `services/<tree>/**` entries and would report success\n              // having changed nothing.\n              \"That entry hides the model file without covering \" +\n              `${tree}/, so \\`loam subsystem sync\\` cannot repair it: sync maintains only the ` +\n              \"`services/` directory entries and leaves every other line exactly as the team wrote it. Narrow that \" +\n              \"entry to the paths it was written for, or delete it\"\n            : \"Run `loam subsystem sync`: it rewrites the root project's `exclude` to cover exactly the models \" +\n              \"that stand alone\"),\n      });\n    }\n    if (exclude !== null && model.standalone && entry === null) {\n      findings.push({\n        ...at,\n        code: \"service.model-unexcluded\",\n        message:\n          `${model.service.id}: ${tree}/${ARTIFACT_FILES.model} stands alone (declares its own specification) and ` +\n          `the root ${LIKEC4_PROJECT_FILENAME} does not exclude ${tree}/ — the renderer merges it into the map ` +\n          \"and reports every kind and element it declares as a duplicate, blanking the whole root project. \" +\n          `Run \\`loam subsystem sync\\`: it adds ${tree}/** to the root project's \\`exclude\\``,\n      });\n    }\n  }\n  return { findings, mapExcluded: excluded.length > 0 };\n}\n\n/**\n * `landscape.excluded` — the root `exclude` covers the fleet MAP itself.\n *\n * WHY IT EXISTS AT ALL, and why only now. The architecture loader used to apply\n * the root `exclude` with no floor under it, so an entry covering\n * `architecture/landscape.likec4` — an `architecture/*.likec4` written for a\n * palette, say — left that project EMPTY, and an empty project parses with zero\n * errors. Every reader downstream took that for \"the map declares nothing\":\n * `landscape.service-unmodelled` on every service, `c4.invalid` on every\n * extending model, `subsystem sync` cutting a good generated file back to a\n * title (verification 2026-09-04, review C). The loader now keeps the map\n * whatever the list says, so loam has stopped asserting those falsehoods — but\n * the RENDERER still applies the entry, and it has no floor. Nothing told the\n * author that the fleet map they are grading is a map nobody can open. This is\n * that sentence, and it is the only finding in the run that names it.\n *\n * WARN, NEVER GATING, for the reason the module banner gives: with the loader's\n * floor in place, every fact loam grades holds identically either way. The gap\n * is a renderer gap, exactly like the four per-service grades above.\n *\n * THE SAME ROOT GATE covers it — the caller returns early with no root\n * `likec4.config.json`, and a config loam cannot read an `exclude` list out of\n * answers `null`, which says nothing rather than guessing. It is gated on the\n * map EXISTING as well: with no file there, `landscape.missing` is the finding\n * and an entry covering a path nobody wrote is not a repair anyone owes.\n *\n * `excludingPath`, not `excludingEntry`: the map is a FILE, and this must fire\n * exactly when `architectureProjectDocuments` would have dropped it — same\n * list, same matcher, same argument. Asking the directory question instead\n * would answer for `architecture/` as a whole and miss `architecture/*.likec4`,\n * which is the spelling that caused the defect.\n *\n * The repair is NOT `loam subsystem sync`, and the message says so where the\n * four grades above name it: sync recomputes only the `services/<tree>/**`\n * entries and leaves every other line in the order the team wrote it, so it\n * would report success and change nothing. The four had a writer; this one has\n * an author.\n *\n * AND IT SUSPENDS `c4.fleet-project-invalid`, which is the cascade discipline\n * `permissions.invalid` and `capability.invalid` already state: a grade that\n * RESOLVES against a document nobody loaded is not a diagnosis. That check\n * builds the fleet project the way the renderer does — no floor under the map —\n * so the very entry named here takes the map out of it and every `extend` in\n * every extending model then resolves against nothing. Measured on\n * `examples/docs` with `architecture/*.likec4` in the list: one\n * `landscape.excluded` and **161** `c4.fleet-project-invalid`, all of them one\n * line's fault. The message carries that clause so the reader knows the fleet\n * project is unread rather than clean, and the caller reads the same fact off\n * `ProjectGrade.mapExcluded` — see `./fleet-project.ts`'s `mapExcluded` gate.\n */\nfunction mapExcluded(docsDir: DocsDir, exclude: readonly string[] | null): Finding[] {\n  const map = landscapePath(docsDir);\n  if (exclude === null || !existsSync(map)) return [];\n  const rel = relative(docsDir, map).split(/[\\\\/]/).join(\"/\");\n  const entry = excludingPath(exclude, rel);\n  if (entry === null) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"landscape.excluded\",\n      // Quoted VERBATIM, for `service.model-excluded`'s reason one level down:\n      // the repair is to edit THAT line, and an entry loam re-spelled is a line\n      // its author would go looking for and not find.\n      message:\n        `landscape: the root ${LIKEC4_PROJECT_FILENAME}'s \\`exclude\\` covers ${rel} ('${entry}') — the renderer never ` +\n        \"loads the fleet map, so it draws no map at all and every model that EXTENDS the map resolves against \" +\n        \"nothing in the root project, while loam goes on grading the map it reads from disk. `c4.fleet-project-invalid` \" +\n        \"is NOT graded while this entry stands: that check loads the fleet project the way the renderer does, so it \" +\n        \"would report the same one line as an unresolved reference in every extending model rather than as this. \" +\n        \"Remove that entry, or \" +\n        `narrow it to the paths it was written for, and the fleet project is graded again. \\`loam subsystem sync\\` ` +\n        \"will not do it: that command maintains \" +\n        \"only the `services/` entries in the list and leaves every other line exactly as the team wrote it\",\n      locations: [{ path: rel, role: \"primary\" }],\n    },\n  ];\n}\n"]}

package/dist/commands/validate/fleet/views/root-documents.js

@@ -0,0 +1,83 @@
+/**
+ * The documents the RENDERER's root project loads, enumerated the way the
+ * renderer enumerates them: everything under the docs root that the root
+ * `likec4.config.json` does not exclude.
+ *
+ * It exists because `./fleet-project.ts` used to build the set BY SHAPE — the
+ * `architecture/` project, each extending `model.likec4`, and every `.likec4`
+ * inside a service directory — and that is three roots, not a tree. A `.likec4`
+ * one directory ABOVE a service (`services/platform/notes.likec4`, the parent of
+ * service directories) was in none of them: `loam validate --all` came back
+ * byte-identical to baseline and never named the file, while `npx likec4
+ * validate --project fleet .` reported Invalid over nine files and thirteen
+ * errors (verification 2026-09-04, R2). The same file one directory lower was a
+ * loud error. SCHEMA, `loam-codes` and `explain` all said loam loads "every
+ * `.likec4` the root project reads"; this is that sentence, executed.
+ *
+ * FOUR THINGS COME OUT, and each is a rule rather than a filter of convenience:
+ *
+ *  - Every GENERATED `architecture/` document — `subsystems.likec4` and
+ *    `services.likec4`, taken from the ONE list every project read shares
+ *    (`c4/project/architecture.ts`) — for `c4/project/documents.ts`'s reason:
+ *    docs/DESIGN.md rule 26 makes their staleness a byte compare, and a stale
+ *    one naming a removed element would blank this load and report a cascade
+ *    whose repair is `loam subsystem sync`.
+ *  - Anything the root `exclude` covers, read through `c4/root-project/exclude.ts`
+ *    — the renderer does not load it, so grading it would be loam reporting a
+ *    failure nobody can see. A root config loam cannot read an `exclude` list out
+ *    of covers nothing: guessing an exclusion is worse than loading one document
+ *    too many.
+ *  - Every STANDALONE service directory. Such a model declares its own kinds, so
+ *    the root project must exclude it and `service.model-unexcluded` is the grade
+ *    for a root that does not — one finding naming the entry to add, rather than
+ *    a duplicate-kind cascade under a second code.
+ *  - `features/`. A feature's `delta.likec4` carries a `specification` block of
+ *    its own and the directory is transient — the scaffolded root config excludes
+ *    it for exactly that reason, and a fleet mid-feature would otherwise read as
+ *    a fleet whose map is declared twice. loam drops it whether or not the entry
+ *    is still there; `loam validate --feature` is where a delta is graded.
+ *
+ * Dot-directories and `node_modules` are not walked at all. Those are loam's own
+ * machinery and a package tree, never authored documents — the same thing the
+ * scaffold's own `node_modules` glob says. `.loam-before` is the case that
+ * proved it: a snapshot written before layout version 4 holds a verbatim copy
+ * of the landscape under its living name, which would read as the map declared
+ * twice. Version 4 suffixes every pre-image so the RENDERER cannot take one for
+ * a document either (`core/staging/snapshot/manifest.ts`), but the older
+ * snapshots are read forever and never migrated, so this walk keeps the rule.
+ */
+import { relative, resolve, sep } from "node:path";
+import { excludingPath, readRootExclude } from "../../../../core/c4/root-project/exclude.js";
+import { generatedArchitectureDocuments } from "../../../../core/c4/project/architecture.js";
+import { likec4DocumentsUnder } from "../../../../core/c4/project/documents.js";
+/** The directory name loam never walks, beside every dot-directory. */
+const PACKAGES = "node_modules";
+/** The one subtree loam drops whatever the root config says — see the banner. */
+const FEATURES = "features";
+/**
+ * Every `.likec4` the renderer's root project reads and loam can grade, absolute
+ * and sorted. `standalone` is each standalone service's directory, absolute.
+ */
+export async function rootProjectDocuments(docsDir, standalone) {
+    const exclude = await readRootExclude(docsDir);
+    const generated = new Set(generatedArchitectureDocuments(docsDir).map((path) => resolve(path)));
+    const excluded = standalone.map((dir) => `${resolve(dir)}${sep}`);
+    const root = resolve(docsDir);
+    const keeps = (path) => {
+        if (generated.has(resolve(path)))
+            return false;
+        if (excluded.some((dir) => resolve(path).startsWith(dir)))
+            return false;
+        const rel = relative(root, path).split(/[\\/]/);
+        if (rel[0] === FEATURES)
+            return false;
+        return exclude === null || excludingPath(exclude, rel.join("/")) === null;
+    };
+    // An unreadable directory contributes nothing — `likec4DocumentsUnder`
+    // records why a grade inside `validate --all` may never fail the run.
+    return likec4DocumentsUnder(root, {
+        enters: (name) => !name.startsWith(".") && name !== PACKAGES,
+        keeps,
+    });
+}
+//# sourceMappingURL=root-documents.js.map

package/dist/commands/validate/fleet/views/root-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-documents.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/root-documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAE7F,OAAO,EAAE,8BAA8B,EAAE,MAAM,6CAA6C,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAC;AAEhF,uEAAuE;AACvE,MAAM,QAAQ,GAAG,cAAc,CAAC;AAEhC,iFAAiF;AACjF,MAAM,QAAQ,GAAG,UAAU,CAAC;AAE5B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAgB,EAAE,UAA6B;IACxF,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,8BAA8B,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,IAAY,EAAW,EAAE;QACtC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/C,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACxE,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACtC,OAAO,OAAO,KAAK,IAAI,IAAI,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;IAC5E,CAAC,CAAC;IACF,uEAAuE;IACvE,sEAAsE;IACtE,OAAO,oBAAoB,CAAC,IAAI,EAAE;QAChC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,QAAQ;QAC5D,KAAK;KACN,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * The documents the RENDERER's root project loads, enumerated the way the\n * renderer enumerates them: everything under the docs root that the root\n * `likec4.config.json` does not exclude.\n *\n * It exists because `./fleet-project.ts` used to build the set BY SHAPE — the\n * `architecture/` project, each extending `model.likec4`, and every `.likec4`\n * inside a service directory — and that is three roots, not a tree. A `.likec4`\n * one directory ABOVE a service (`services/platform/notes.likec4`, the parent of\n * service directories) was in none of them: `loam validate --all` came back\n * byte-identical to baseline and never named the file, while `npx likec4\n * validate --project fleet .` reported Invalid over nine files and thirteen\n * errors (verification 2026-09-04, R2). The same file one directory lower was a\n * loud error. SCHEMA, `loam-codes` and `explain` all said loam loads \"every\n * `.likec4` the root project reads\"; this is that sentence, executed.\n *\n * FOUR THINGS COME OUT, and each is a rule rather than a filter of convenience:\n *\n *  - Every GENERATED `architecture/` document — `subsystems.likec4` and\n *    `services.likec4`, taken from the ONE list every project read shares\n *    (`c4/project/architecture.ts`) — for `c4/project/documents.ts`'s reason:\n *    docs/DESIGN.md rule 26 makes their staleness a byte compare, and a stale\n *    one naming a removed element would blank this load and report a cascade\n *    whose repair is `loam subsystem sync`.\n *  - Anything the root `exclude` covers, read through `c4/root-project/exclude.ts`\n *    — the renderer does not load it, so grading it would be loam reporting a\n *    failure nobody can see. A root config loam cannot read an `exclude` list out\n *    of covers nothing: guessing an exclusion is worse than loading one document\n *    too many.\n *  - Every STANDALONE service directory. Such a model declares its own kinds, so\n *    the root project must exclude it and `service.model-unexcluded` is the grade\n *    for a root that does not — one finding naming the entry to add, rather than\n *    a duplicate-kind cascade under a second code.\n *  - `features/`. A feature's `delta.likec4` carries a `specification` block of\n *    its own and the directory is transient — the scaffolded root config excludes\n *    it for exactly that reason, and a fleet mid-feature would otherwise read as\n *    a fleet whose map is declared twice. loam drops it whether or not the entry\n *    is still there; `loam validate --feature` is where a delta is graded.\n *\n * Dot-directories and `node_modules` are not walked at all. Those are loam's own\n * machinery and a package tree, never authored documents — the same thing the\n * scaffold's own `node_modules` glob says. `.loam-before` is the case that\n * proved it: a snapshot written before layout version 4 holds a verbatim copy\n * of the landscape under its living name, which would read as the map declared\n * twice. Version 4 suffixes every pre-image so the RENDERER cannot take one for\n * a document either (`core/staging/snapshot/manifest.ts`), but the older\n * snapshots are read forever and never migrated, so this walk keeps the rule.\n */\nimport { relative, resolve, sep } from \"node:path\";\nimport { excludingPath, readRootExclude } from \"../../../../core/c4/root-project/exclude.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { generatedArchitectureDocuments } from \"../../../../core/c4/project/architecture.js\";\nimport { likec4DocumentsUnder } from \"../../../../core/c4/project/documents.js\";\n\n/** The directory name loam never walks, beside every dot-directory. */\nconst PACKAGES = \"node_modules\";\n\n/** The one subtree loam drops whatever the root config says — see the banner. */\nconst FEATURES = \"features\";\n\n/**\n * Every `.likec4` the renderer's root project reads and loam can grade, absolute\n * and sorted. `standalone` is each standalone service's directory, absolute.\n */\nexport async function rootProjectDocuments(docsDir: DocsDir, standalone: readonly string[]): Promise<string[]> {\n  const exclude = await readRootExclude(docsDir);\n  const generated = new Set(generatedArchitectureDocuments(docsDir).map((path) => resolve(path)));\n  const excluded = standalone.map((dir) => `${resolve(dir)}${sep}`);\n  const root = resolve(docsDir);\n  const keeps = (path: string): boolean => {\n    if (generated.has(resolve(path))) return false;\n    if (excluded.some((dir) => resolve(path).startsWith(dir))) return false;\n    const rel = relative(root, path).split(/[\\\\/]/);\n    if (rel[0] === FEATURES) return false;\n    return exclude === null || excludingPath(exclude, rel.join(\"/\")) === null;\n  };\n  // An unreadable directory contributes nothing — `likec4DocumentsUnder`\n  // records why a grade inside `validate --all` may never fail the run.\n  return likec4DocumentsUnder(root, {\n    enters: (name) => !name.startsWith(\".\") && name !== PACKAGES,\n    keeps,\n  });\n}\n"]}

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

@@ -0,0 +1,52 @@
+import { serviceViewsPath, subsystemViewsPath } from "../../../../core/repo/paths.js";
+import { serviceViewsState, viewsState } from "../../../../core/repo/tree/render/stale.js";
+export async function viewsStaleFindings(docsDir, tree, map) {
+    const subsystems = await viewsState(subsystemViewsPath(docsDir), tree, map);
+    const services = await serviceViewsState(serviceViewsPath(docsDir), tree, map);
+    return [
+        ...staleFinding(subsystems, {
+            file: "architecture/subsystems.likec4",
+            absent: "does not exist, but the tree has subsystems to mirror",
+            leftover: "exists, but the tree has no subsystems — the generated file must be absent",
+            what: "one view per subsystem, and every derived scope drawn from it is wrong until it agrees",
+        }),
+        ...staleFinding(services, {
+            file: "architecture/services.likec4",
+            absent: "does not exist, but the fleet map draws services this file must mirror",
+            leftover: "exists, but the fleet map draws none of the services under services/ — the generated file must be absent",
+            what: "one overview view per service the map draws, and every drill-down into a service goes through it, so a " +
+                "reader following the map lands on a picture that is wrong until it agrees",
+        }),
+    ];
+}
+/**
+ * One finding, or none — the shape both generated files share, spelled once so
+ * they cannot drift into two dialects of the same sentence.
+ */
+function staleFinding(state, file) {
+    if (state.agrees)
+        return [];
+    const said = state.actual === null ? file.absent : state.expected === null ? file.leftover : "does not match the tree and the map";
+    return [
+        {
+            severity: "error",
+            code: "subsystem.views-stale",
+            subject: file.file,
+            // The file the message names, so an editor jumping to the finding lands
+            // on it. Without a location the report's fallback files this under the
+            // TARGET, which is the landscape — a reader was sent to
+            // architecture/landscape.likec4 to fix a file the sentence beside it
+            // named as architecture/subsystems.likec4. A file that does not exist
+            // yet cannot be `primary`: the actionable place is then the directory
+            // the regenerator will write into.
+            locations: [
+                state.actual === null
+                    ? { path: "architecture", role: "scope" }
+                    : { path: file.file, role: "primary" },
+            ],
+            message: `subsystems: ${file.file} ${said} — it is generated, ${file.what}. ` +
+                "Run `loam subsystem sync` to regenerate it; never edit it by hand.",
+        },
+    ];
+}
+//# sourceMappingURL=stale.js.map

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

@@ -0,0 +1 @@
+{"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/links/corpus.js

@@ -0,0 +1,89 @@
+/**
+ * Where each target's link findings are filed — the ORDER, not the rule.
+ *
+ * The rule lives in `core/links/`: extract the links, resolve them, name the
+ * ones that point at nothing. WHICH documents belong to a service, a feature or
+ * the fleet lives there too (`core/links/corpus.ts`), because the glossary's
+ * backlink index reads the same list and a second enumeration would be free to
+ * disagree with this one. What is left here is the part that belongs to
+ * `validate`: reading each document, deciding which target carries the finding,
+ * and refusing to let one unreadable file take a whole target down with it.
+ */
+import { existsSync } from "node:fs";
+import { pathCaseIndex } from "../../../core/links/case.js";
+import { featureDocuments, fleetDocuments, serviceDocuments } from "../../../core/links/corpus.js";
+import { unresolvedLinkFindings } from "../../../core/links/findings.js";
+import { featureGlossaryOverlay } from "../../../core/glossary/delta.js";
+import {} from "../../../core/repo/paths.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import {} from "../../../core/vocabulary/report.js";
+/** One service's documents, graded on the service target. */
+export async function serviceLinkFindings(check, paths) {
+    return documentFindings(await serviceDocuments(paths), check);
+}
+/**
+ * One feature's documents, graded on the feature target — with the glossary
+ * terms it introduces treated as already living. See `LinkScope.overlay`: a
+ * feature cites the word it is adding at that word's future path, and an index
+ * built from the living tree alone would refuse the axis's own headline case.
+ */
+export async function featureLinkFindings(check, featureDir) {
+    return documentFindings(await featureDocuments(featureDir, check.fleet), {
+        ...check,
+        overlay: await featureGlossaryOverlay(check.docsDir, featureDir),
+    });
+}
+/**
+ * The fleet's own documents — its ADRs, the living capability tree and the
+ * glossary — graded once on the landscape target. A single-target run says
+ * nothing about them, the rule `permissions.unenforced` already follows: a
+ * finding about the fleet repeated on every service target is the report.
+ */
+export async function fleetLinkFindings(check) {
+    return documentFindings(await fleetDocuments(check.docsDir, check.fleet), check);
+}
+/**
+ * Grade a list of documents, skipping the ones that are not there.
+ *
+ * ABSENCE IS NOT THIS CHECK'S BUSINESS: `service.no-spec` already names a
+ * missing `spec.md`, and most services have no runbook and no ADRs at all.
+ *
+ * AN UNREADABLE DOCUMENT IS NAMED HERE RATHER THAN THROWN, and that is what
+ * `link.unreadable` is for. Every other reader of a service's documents is
+ * wrapped by `report.ts`'s `guarded`, which turns an IO failure into
+ * `service.unreadable` — "nothing about this service was checked". That verdict
+ * is right for `spec.md` and wrong for an ADR: this check is the first to read
+ * those files at all, and a runbook saved as UTF-16 must not be able to blank
+ * a service's entire report when the only thing that could not be graded is one
+ * document's links.
+ */
+async function documentFindings(paths, check) {
+    const findings = [];
+    // One directory-listing memo for this target's whole corpus. Built here
+    // rather than per document because a service's ADRs all resolve through the
+    // same two or three directories, and rather than at module scope because a
+    // listing that outlived the command would answer for a tree that has moved.
+    const scope = { ...check, cases: pathCaseIndex() };
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        let text;
+        try {
+            text = await check.fleet.readText(path);
+        }
+        catch (err) {
+            findings.push({
+                severity: "error",
+                code: "link.unreadable",
+                ...(check.subject === undefined ? {} : { subject: check.subject }),
+                message: `${repoPath(check.docsDir, path)} could not be read, so its links were not checked — ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        findings.push(...unresolvedLinkFindings({ path, text }, scope));
+    }
+    return findings;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/commands/validate/links/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../../src/commands/validate/links/corpus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACnG,OAAO,EAAE,sBAAsB,EAAkB,MAAM,iCAAiC,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAqB,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAalE,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAAgB,EAAE,KAAmB;IAC7E,OAAO,gBAAgB,CAAC,MAAM,gBAAgB,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,KAAgB,EAAE,UAAsB;IAChF,OAAO,gBAAgB,CAAC,MAAM,gBAAgB,CAAC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE;QACvE,GAAG,KAAK;QACR,OAAO,EAAE,MAAM,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,UAAU,CAAC;KACjE,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAgB;IACtD,OAAO,gBAAgB,CAAC,MAAM,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,gBAAgB,CAAC,KAAe,EAAE,KAAgB;IAC/D,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,wEAAwE;IACxE,4EAA4E;IAC5E,2EAA2E;IAC3E,4EAA4E;IAC5E,MAAM,KAAK,GAAc,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC;IAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,iBAAiB;gBACvB,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClE,OAAO,EACL,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,sDAAsD;oBACtF,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;aACxD,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Where each target's link findings are filed — the ORDER, not the rule.\n *\n * The rule lives in `core/links/`: extract the links, resolve them, name the\n * ones that point at nothing. WHICH documents belong to a service, a feature or\n * the fleet lives there too (`core/links/corpus.ts`), because the glossary's\n * backlink index reads the same list and a second enumeration would be free to\n * disagree with this one. What is left here is the part that belongs to\n * `validate`: reading each document, deciding which target carries the finding,\n * and refusing to let one unreadable file take a whole target down with it.\n */\nimport { existsSync } from \"node:fs\";\nimport { pathCaseIndex } from \"../../../core/links/case.js\";\nimport { featureDocuments, fleetDocuments, serviceDocuments } from \"../../../core/links/corpus.js\";\nimport { unresolvedLinkFindings, type LinkScope } from \"../../../core/links/findings.js\";\nimport { featureGlossaryOverlay } from \"../../../core/glossary/delta.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { DocsDir, FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/** Where the findings are filed, and how the documents are read. */\nexport interface LinkCheck {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  fleet: FleetContext;\n  /** Paths an in-flight feature will create — `LinkScope.overlay` says why. */\n  overlay?: ReadonlySet<string>;\n}\n\n/** One service's documents, graded on the service target. */\nexport async function serviceLinkFindings(check: LinkCheck, paths: ServicePaths): Promise<Finding[]> {\n  return documentFindings(await serviceDocuments(paths), check);\n}\n\n/**\n * One feature's documents, graded on the feature target — with the glossary\n * terms it introduces treated as already living. See `LinkScope.overlay`: a\n * feature cites the word it is adding at that word's future path, and an index\n * built from the living tree alone would refuse the axis's own headline case.\n */\nexport async function featureLinkFindings(check: LinkCheck, featureDir: FeatureDir): Promise<Finding[]> {\n  return documentFindings(await featureDocuments(featureDir, check.fleet), {\n    ...check,\n    overlay: await featureGlossaryOverlay(check.docsDir, featureDir),\n  });\n}\n\n/**\n * The fleet's own documents — its ADRs, the living capability tree and the\n * glossary — graded once on the landscape target. A single-target run says\n * nothing about them, the rule `permissions.unenforced` already follows: a\n * finding about the fleet repeated on every service target is the report.\n */\nexport async function fleetLinkFindings(check: LinkCheck): Promise<Finding[]> {\n  return documentFindings(await fleetDocuments(check.docsDir, check.fleet), check);\n}\n\n/**\n * Grade a list of documents, skipping the ones that are not there.\n *\n * ABSENCE IS NOT THIS CHECK'S BUSINESS: `service.no-spec` already names a\n * missing `spec.md`, and most services have no runbook and no ADRs at all.\n *\n * AN UNREADABLE DOCUMENT IS NAMED HERE RATHER THAN THROWN, and that is what\n * `link.unreadable` is for. Every other reader of a service's documents is\n * wrapped by `report.ts`'s `guarded`, which turns an IO failure into\n * `service.unreadable` — \"nothing about this service was checked\". That verdict\n * is right for `spec.md` and wrong for an ADR: this check is the first to read\n * those files at all, and a runbook saved as UTF-16 must not be able to blank\n * a service's entire report when the only thing that could not be graded is one\n * document's links.\n */\nasync function documentFindings(paths: string[], check: LinkCheck): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  // One directory-listing memo for this target's whole corpus. Built here\n  // rather than per document because a service's ADRs all resolve through the\n  // same two or three directories, and rather than at module scope because a\n  // listing that outlived the command would answer for a tree that has moved.\n  const scope: LinkScope = { ...check, cases: pathCaseIndex() };\n  for (const path of paths) {\n    if (!existsSync(path)) continue;\n    let text: string;\n    try {\n      text = await check.fleet.readText(path);\n    } catch (err) {\n      findings.push({\n        severity: \"error\",\n        code: \"link.unreadable\",\n        ...(check.subject === undefined ? {} : { subject: check.subject }),\n        message:\n          `${repoPath(check.docsDir, path)} could not be read, so its links were not checked — ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      });\n      continue;\n    }\n    findings.push(...unresolvedLinkFindings({ path, text }, scope));\n  }\n  return findings;\n}\n"]}