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

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

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

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

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

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

@@ -0,0 +1,310 @@
+/**
+ * The service target: one adopted service graded across every axis it owns.
+ *
+ * This module is the ORDER, not the checks. It reads what more than one axis
+ * joins through — the C4 model, the living landscape and its resolver, the two
+ * requirement documents — hands each of those to the axis that grades it, and
+ * pushes the findings in the sequence the report is read in. The axes
+ * themselves cannot see each other, which is the point: `./api.js` decides once
+ * whether there is a contract to read, and `./spine.js` is handed the answer
+ * instead of re-deriving it against a file it would open a second time.
+ */
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/c4/service-model/load.js";
+import { serviceResolver } from "../../../core/c4/resolve/service.js";
+import {} from "../../../core/kernel/ids/service.js";
+import { landscapePath as landscapeFile, permissionsPath } from "../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
+import { readVocabulary } from "../../../core/permissions/permissions.js";
+import { capabilityRequirementIndex, capabilityUnknownIssues } from "../../../core/capabilities/findings.js";
+import { realizesStaleFindings, realizesUnknownIssues } from "../../../core/capabilities/realizes/findings.js";
+import { requiresUnknownFindings } from "../checks/requirements.js";
+import { listServices } from "../../../core/repo/repo.js";
+import {} from "../../../core/vocabulary/report.js";
+import { serviceProvenance } from "../../../core/provenance/findings.js";
+import { gherkinFindings } from "../../../core/gherkin/stale.js";
+import { gherkinRoot } from "../../../core/gherkin/stamp.js";
+import { UnsafePathError } from "../../../core/kernel/path-safety.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { interruptedCommitFinding } from "../../../core/staging/recovery/finding.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { serviceLinkFindings } from "../links/corpus.js";
+import { sourceScopeFindings } from "../checks/sources.js";
+import { unknownServiceFinding } from "../checks/introduced.js";
+import { apiAxisFindings } from "./api.js";
+import { generatedContractFindings } from "./contracts/generated.js";
+import { evidencePinFindings } from "./evidence-pins.js";
+import { spineFindings } from "./spine.js";
+import { eventAxisFindings } from "./events/events.js";
+import { archAxisFindings, readServiceSpecs } from "./specs.js";
+import { modelFindings } from "./model/grade.js";
+import { divergedFindings } from "./model/diverged.js";
+import { requirementIdsOf, serviceUseCaseFindings } from "./usecases/usecases.js";
+import { readServiceFlows } from "../../../core/usecases/service/flows.js";
+import { unknownDirectiveFindings } from "../../../core/document/grammar/directives.js";
+export async function validateService(check) {
+    const { docsDir, service, repoDir, preloaded, gherkinDir, contracts, fleet } = check;
+    // The spine and event joins below all ask the landscape's resolver one
+    // question: does this edge's endpoint resolve into the directory being
+    // validated? The resolver answers with DOCUMENT text and `service` is the
+    // repository's own name — disjoint brands, so `===` between them is TS2367.
+    // Widening to `string` is not a cast: membership questions cross the
+    // provenance line through plain-string containers by design (kernel/ids/service.ts),
+    // and nothing pathable ever comes back out of a comparison.
+    const me = service;
+    const findings = [];
+    const paths = await locateServicePaths(docsDir, service, fleet);
+    // Repo-relative, `/`-separated: the report's own scope, and the spelling
+    // every service-local use-case finding opens with.
+    const treePath = relative(docsDir, paths.dir).replaceAll("\\", "/");
+    const report = {
+        kind: "service",
+        id: service,
+        path: treePath,
+        findings,
+    };
+    // A directory that does not exist is a different fact from a directory with
+    // everything missing: validating a typo must say "typo", not "unadopted" —
+    // and a service a feature in flight introduces is neither (checks/introduced.ts).
+    if (!existsSync(paths.dir)) {
+        findings.push(await unknownServiceFinding(docsDir, service, treePath, fleet));
+        return report;
+    }
+    // Which service directories actually exist — the positive evidence
+    // `serviceOf` needs to resolve an edge drawn into a modelled CONTAINER
+    // (`paymentService.api`) back to the service that owns it. Without it every
+    // such edge resolves to the container's own title, i.e. to a service nobody
+    // has ever adopted, and drops out of the spine unnoticed.
+    //
+    // Read before the model rather than after it, because the model is now read
+    // through the same resolver: an extending model's own slice is exactly the
+    // elements this set makes resolvable.
+    const known = new Set((await listServices(docsDir, fleet)).map((s) => s.id));
+    // C4 model. Its absence is an error — this is where `adopt` comes in — but it
+    // must NOT silence the rest of the gate stack: `loam archive` of a feature
+    // introducing a new service creates exactly this state (spec.md, arch.spec.md,
+    // openapi.yaml, no model.likec4), and an early return here suspended arch
+    // coverage, health.uncovered, provenance (content_digest included) and the
+    // gherkin staleness chain for the very services vouch had just promised them
+    // to. So the finding is emitted and the walk CONTINUES; only the checks that
+    // read the model itself are guarded.
+    const hasModel = existsSync(paths.model);
+    let elements = [];
+    let relationships = [];
+    // The model as its own SHAPE demands it be read — a file parsed alone, or a
+    // slice of the project it extends (`core/c4/service-model/load.ts`). Kept for
+    // the service's own use cases below, which need both its views and which
+    // shape produced them.
+    let model = null;
+    // The service's OWN use cases, scanned here rather than beside the grades it
+    // feeds: `c4.valid` reports how many were graded, and that count is the only
+    // surface a HEALTHY flow appears on. Null means no scan was made — the model
+    // does not parse (`c4.invalid` owns that, and a second load repeats its
+    // cascade under a use-case code) or its map does not (an extending model then
+    // comes back with no errors AND no model, and the flow project would be
+    // staged over the same broken map).
+    let flows = null;
+    if (!hasModel) {
+        findings.push({
+            severity: "error",
+            code: "service.no-model",
+            message: `No C4 model at ${repoPath(docsDir, paths.model)}. Run \`loam adopt\` for '${service}' first.`,
+        });
+    }
+    else {
+        model = await fleet.serviceModel(docsDir, paths);
+        elements = model.doc.elements;
+        relationships = model.doc.relationships;
+        if (!model.mapUnreadable && model.doc.errors.length === 0) {
+            flows = await readServiceFlows({
+                paths,
+                model: model.doc,
+                known,
+                // An extending model's siblings resolve against the fleet map, so their
+                // project is the docs root's, never the service directory. The project
+                // the model was READ in travels with it because that is the scope of a
+                // view written inside model.likec4: `model.doc` is the service's own
+                // slice, and a hop backed by one of the map's edges is backed wherever
+                // the view sits.
+                ...(model.shape === "extending" && model.project !== null
+                    ? { extending: { docsDir, project: model.project } }
+                    : {}),
+            });
+        }
+        findings.push(...(await modelFindings({
+            service,
+            treePath,
+            docsDir,
+            model,
+            modelPath: paths.model,
+            known,
+            gradedFlows: flows?.kind === "read" ? flows.views.length : 0,
+        })));
+    }
+    // The fleet map as the PROJECT it is, in EVERY mode — landscape plus every
+    // `architecture/**/*.likec4` minus the generated views file. Single-service
+    // runs used to read `landscape.likec4` alone, which made three answers depend
+    // on which flag the caller happened to pass: a use-case file that does not
+    // parse was `spine.landscape-invalid` under `--all` and silence under
+    // `--service`, an extending model was readable under one and not the other,
+    // and `c4.declaration-diverged` would have compared against a different
+    // document. Under `--all` the caller hands in the doc it already loaded.
+    //
+    // Still gated on the landscape FILE existing: `land === null` means "this repo
+    // draws no fleet", and a repo with an `architecture/usecases/` and no map is
+    // that state, not a map that loaded empty.
+    const land = preloaded ?? (existsSync(landscapeFile(docsDir)) ? await fleet.architecture(docsDir) : null);
+    // Where a standalone model's copies of the map's elements have drifted. After
+    // `c4.valid` because it is a claim about a model that parsed, and silent for
+    // an extending model, which has no copy to diverge.
+    if (model !== null)
+        findings.push(...divergedFindings({ service, model, architecture: land, known }));
+    // The living landscape's element→service resolver, container-aware and
+    // memoized. Every question below that asks "does this edge point at me?"
+    // asks it through this one function, so the no-openapi grace, the HTTP spine
+    // and the event spine can never disagree about which edges are inbound.
+    const landSvcOf = land === null ? null : serviceResolver(land.elements, known);
+    const specs = await readServiceSpecs({ docsDir, service, paths, fleet });
+    findings.push(...specs.findings);
+    const { reqs, livingReqs, archText, archReqs } = specs;
+    const api = await apiAxisFindings({
+        docsDir,
+        service,
+        me,
+        paths,
+        reqs,
+        livingReqs,
+        land,
+        landSvcOf,
+        fleet,
+    });
+    findings.push(...api.findings);
+    findings.push(...spineFindings({
+        service,
+        docsDir,
+        treePath,
+        me,
+        land,
+        landSvcOf,
+        contract: api.contract,
+        landscapeReported: check.landscapeReported,
+        // An unreadable map takes an extending model with it, and the spine
+        // finding is where that is said — see `Spine.modelExtends`.
+        modelExtends: model?.shape === "extending",
+    }));
+    findings.push(...(await eventAxisFindings({
+        docsDir,
+        service,
+        me,
+        paths,
+        reqs,
+        livingReqs,
+        archReqs,
+        land,
+        landSvcOf,
+        known,
+        fleet,
+    })));
+    findings.push(...(await archAxisFindings({
+        service,
+        paths,
+        archText,
+        archReqs,
+        elements,
+        relationships,
+        // The one fact that tells "this service models nothing" apart from "this
+        // service's model could not be read" — its map does not parse, or it does
+        // not itself (`c4.invalid` above): both arrive here as empty lists, and
+        // only the second one must silence `covers.unknown`.
+        modelUnreadable: model !== null && (model.mapUnreadable || model.doc.errors.length > 0),
+        land,
+        known,
+        docsDir,
+        fleet,
+    })));
+    // The service's own use cases, GRADED — scanned beside the model above. Here
+    // rather than on the fleet target because the hops name this service's
+    // containers, which only its project resolves; after the arch axis because a
+    // `#req-` tag resolves against the ids both spec documents declare.
+    if (flows !== null) {
+        findings.push(...serviceUseCaseFindings({
+            service,
+            treePath,
+            docsDir,
+            scan: flows,
+            services: known,
+            requirementIds: requirementIdsOf(paths, livingReqs, archReqs),
+        }));
+    }
+    // The authorization axis. Both requirement documents are graded against one
+    // fleet vocabulary — a permission is a fleet fact, and an arch requirement
+    // gates on one exactly as a business requirement does. The capability axis
+    // rides the same loop against ITS fleet vocabulary; under --all the fleet
+    // memo makes that one parse for the whole run.
+    const vocabulary = await readVocabulary(permissionsPath(docsDir));
+    const capabilities = await fleet.capabilities(docsDir);
+    // The requirement-level index behind `Realizes:`. Built once for both axes,
+    // and behind the same ladder `capabilityUnknownIssues` applies — an absent
+    // or unreadable vocabulary means no reads and no grades at all, so a fleet
+    // that has not adopted the axis pays nothing for a line it never wrote.
+    const capabilityReqs = await capabilityRequirementIndex(capabilities, (p) => fleet.readRequirements(p));
+    for (const [label, docReqs] of [
+        ["spec.md", reqs],
+        ["arch.spec.md", archReqs],
+    ]) {
+        const target = { where: `${service}: ${label}`, subject: service };
+        findings.push(...requiresUnknownFindings(docReqs, target, vocabulary));
+        findings.push(...capabilityUnknownIssues(docReqs, target, capabilities));
+        findings.push(...realizesUnknownIssues(docReqs, target, capabilityReqs));
+        findings.push(...realizesStaleFindings(docReqs, target, capabilityReqs));
+        // The grammar guard, last in the loop: it grades the KEYS the three checks
+        // above resolve values from, so a line none of them saw is reported here
+        // rather than staying invisible for having produced nothing to check.
+        findings.push(...unknownDirectiveFindings(docReqs, target));
+    }
+    // The links this service's own documents write. Its place in the order is
+    // deliberate: every axis above joins through a LINE loam defined, and this one
+    // grades the join an author writes in prose — so it reads last among the
+    // document checks and adds no input any of them depend on.
+    findings.push(...(await serviceLinkFindings({ docsDir, subject: service, fleet }, paths)));
+    // Provenance last: who vouched for this, and what code it was written from.
+    findings.push(...(await serviceProvenance(docsDir, service, { repoDir, loamOwned: check.loamOwned, fleet })));
+    findings.push(...(await sourceScopeFindings(docsDir, service, repoDir, fleet)));
+    // The build's own contract against the committed copy. Service-repo only:
+    // from the docs repo there is no build output to read, and the family stays
+    // silent rather than guessing — the same rule `sources` provenance follows.
+    if (repoDir !== undefined) {
+        findings.push(...(await generatedContractFindings(service, repoDir, contracts?.openapi, paths.openapi)));
+    }
+    // The generated-gherkin freshness chain, service-repo-scoped like sources.*:
+    // it needs the repo (the suite lives there), and it stays quiet until
+    // <gherkinDir>/loam/ exists — a service that never generated has not opted in.
+    findings.push(...(await gherkinFindings({ docsDir, service, repoDir, gherkinDir, fleet })));
+    // The evidence-pin re-check, the same service-repo-scoped family: recorded
+    // verification citations graded against THIS working tree, quiet from the
+    // docs repo — sources.unverifiable-from-here already names that blind spot.
+    findings.push(...(await evidencePinFindings(docsDir, service, repoDir, fleet)));
+    // The one journal that does NOT live in the docs repo: gherkin commits into
+    // the service repo's emission root. A half-committed suite graded by the
+    // freshness chain above reads as merely stale — warn-severity, which never
+    // gates — while doctor calls the same state a blocker. Same finding, same
+    // code, led rather than appended, exactly as validate leads with the docs
+    // repo's own journal.
+    if (repoDir !== undefined) {
+        try {
+            const interrupted = await interruptedCommitFinding(gherkinRoot(repoDir, gherkinDir));
+            if (interrupted !== null)
+                findings.unshift(interrupted);
+        }
+        catch (err) {
+            // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its
+            // own sentence; grading declines to scan what it cannot trust.
+            if (!(err instanceof UnsafePathError))
+                throw err;
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The service target: one adopted service graded across every axis it owns.\n *\n * This module is the ORDER, not the checks. It reads what more than one axis\n * joins through — the C4 model, the living landscape and its resolver, the two\n * requirement documents — hands each of those to the axis that grades it, and\n * pushes the findings in the sequence the report is read in. The axes\n * themselves cannot see each other, which is the point: `./api.js` decides once\n * whether there is a contract to read, and `./spine.js` is handed the answer\n * instead of re-deriving it against a file it would open a second time.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../../core/c4/likec4.js\";\nimport { type ServiceModel } from \"../../../core/c4/service-model/load.js\";\nimport { serviceResolver } from \"../../../core/c4/resolve/service.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { landscapePath as landscapeFile, permissionsPath } from \"../../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport { readVocabulary } from \"../../../core/permissions/permissions.js\";\nimport { capabilityRequirementIndex, capabilityUnknownIssues } from \"../../../core/capabilities/findings.js\";\nimport { realizesStaleFindings, realizesUnknownIssues } from \"../../../core/capabilities/realizes/findings.js\";\nimport { requiresUnknownFindings } from \"../checks/requirements.js\";\nimport { listServices } from \"../../../core/repo/repo.js\";\nimport { type Finding, type TargetReport } from \"../../../core/vocabulary/report.js\";\nimport { serviceProvenance } from \"../../../core/provenance/findings.js\";\nimport { gherkinFindings } from \"../../../core/gherkin/stale.js\";\nimport { gherkinRoot } from \"../../../core/gherkin/stamp.js\";\nimport { UnsafePathError } from \"../../../core/kernel/path-safety.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { interruptedCommitFinding } from \"../../../core/staging/recovery/finding.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { serviceLinkFindings } from \"../links/corpus.js\";\nimport { sourceScopeFindings } from \"../checks/sources.js\";\nimport { unknownServiceFinding } from \"../checks/introduced.js\";\nimport { apiAxisFindings } from \"./api.js\";\nimport { generatedContractFindings } from \"./contracts/generated.js\";\nimport { evidencePinFindings } from \"./evidence-pins.js\";\nimport { spineFindings } from \"./spine.js\";\nimport { eventAxisFindings } from \"./events/events.js\";\nimport { archAxisFindings, readServiceSpecs } from \"./specs.js\";\nimport { modelFindings } from \"./model/grade.js\";\nimport { divergedFindings } from \"./model/diverged.js\";\nimport { requirementIdsOf, serviceUseCaseFindings } from \"./usecases/usecases.js\";\nimport { readServiceFlows, type ServiceFlowScan } from \"../../../core/usecases/service/flows.js\";\nimport { unknownDirectiveFindings } from \"../../../core/document/grammar/directives.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/**\n * A service's absences are graded by what each one proves.\n *\n * `service.unknown` (error): the directory itself does not exist — the id is a\n * typo until proven otherwise, so the hint names ids that DO exist and never\n * `loam adopt`, which would faithfully document the misspelling. The proof\n * otherwise is a feature in flight that introduces it; the hint then names\n * that feature instead (`../checks/introduced.ts`).\n * `service.no-model` (error): the directory is real but the C4 center is not —\n * adopt is the right hint. Every check that does not read the model still runs\n * (spec coverage, the arch axis, provenance, gherkin staleness): archive\n * creates exactly this state for a new service, and those signals must not go\n * quiet there.\n * `service.no-spec` / `service.no-openapi` (warn): the adopt brief marks both\n * required, but a fleet mid-rollout legitimately has part-adopted services —\n * the absence must stay visible without gating CI for months. The openapi warn\n * keeps quiet when the landscape proves nobody calls an operation on this\n * service: a worker with no API is not missing one.\n * `api.ops-unlinked` (warn): an OpenAPI and requirements that never name each\n * other pass every cross-axis check vacuously — a repo migrated from OpenSpec\n * does exactly that by default, and vacuous is not the same as checked.\n */\ninterface ServiceCheck {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service's own repo, when loam is standing in it. Undefined from the docs repo. */\n  repoDir?: string;\n  /** loam's own files in `repoDir` (`loamOwnedFiles`) — outside the walk check's denominator. */\n  loamOwned?: readonly string[];\n  /** The build outputs `loam.json` names, when this repo declares any. */\n  contracts?: { openapi?: string };\n  /** The living landscape under --all; undefined means \"load it if you need it\", null means \"there is none\". */\n  preloaded?: LoadedDoc | null;\n  gherkinDir?: string;\n  /**\n   * The read index this target reads the fleet map and the model through.\n   *\n   * Required, and every validate mode builds one before it grades anything —\n   * the single-service run included (`validate.ts`) — rather than this target\n   * keeping a second reading rule for a run that arrived without one:\n   * `serviceModel` needs the enumeration and a document memo to answer at\n   * all, and both live there. Request-scoped like every other `FleetContext`\n   * — created for the invocation, dropped with it.\n   */\n  fleet: FleetContext;\n  /**\n   * True when this run ALSO emits a `landscape` target. It decides one thing:\n   * whether a landscape parse error's details are repeated here. Under --all\n   * they are not — the landscape target already carries them once, and N copies\n   * of one parser's cascade is the whole report. Under --all --base the\n   * landscape is a target only when the branch changed `architecture/`, so the\n   * caller states this per run (`validate.ts`'s `serviceTarget`) rather than\n   * inferring it from `preloaded`: a map handed in is not a map reported.\n   */\n  landscapeReported?: boolean;\n}\n\nexport async function validateService(check: ServiceCheck): Promise<TargetReport> {\n  const { docsDir, service, repoDir, preloaded, gherkinDir, contracts, fleet } = check;\n  // The spine and event joins below all ask the landscape's resolver one\n  // question: does this edge's endpoint resolve into the directory being\n  // validated? The resolver answers with DOCUMENT text and `service` is the\n  // repository's own name — disjoint brands, so `===` between them is TS2367.\n  // Widening to `string` is not a cast: membership questions cross the\n  // provenance line through plain-string containers by design (kernel/ids/service.ts),\n  // and nothing pathable ever comes back out of a comparison.\n  const me: string = service;\n  const findings: Finding[] = [];\n  const paths = await locateServicePaths(docsDir, service, fleet);\n  // Repo-relative, `/`-separated: the report's own scope, and the spelling\n  // every service-local use-case finding opens with.\n  const treePath = relative(docsDir, paths.dir).replaceAll(\"\\\\\", \"/\");\n  const report: TargetReport = {\n    kind: \"service\",\n    id: service,\n    path: treePath,\n    findings,\n  };\n\n  // A directory that does not exist is a different fact from a directory with\n  // everything missing: validating a typo must say \"typo\", not \"unadopted\" —\n  // and a service a feature in flight introduces is neither (checks/introduced.ts).\n  if (!existsSync(paths.dir)) {\n    findings.push(await unknownServiceFinding(docsDir, service, treePath, fleet));\n    return report;\n  }\n\n  // Which service directories actually exist — the positive evidence\n  // `serviceOf` needs to resolve an edge drawn into a modelled CONTAINER\n  // (`paymentService.api`) back to the service that owns it. Without it every\n  // such edge resolves to the container's own title, i.e. to a service nobody\n  // has ever adopted, and drops out of the spine unnoticed.\n  //\n  // Read before the model rather than after it, because the model is now read\n  // through the same resolver: an extending model's own slice is exactly the\n  // elements this set makes resolvable.\n  const known = new Set((await listServices(docsDir, fleet)).map((s) => s.id));\n\n  // C4 model. Its absence is an error — this is where `adopt` comes in — but it\n  // must NOT silence the rest of the gate stack: `loam archive` of a feature\n  // introducing a new service creates exactly this state (spec.md, arch.spec.md,\n  // openapi.yaml, no model.likec4), and an early return here suspended arch\n  // coverage, health.uncovered, provenance (content_digest included) and the\n  // gherkin staleness chain for the very services vouch had just promised them\n  // to. So the finding is emitted and the walk CONTINUES; only the checks that\n  // read the model itself are guarded.\n  const hasModel = existsSync(paths.model);\n  let elements: Elem[] = [];\n  let relationships: Rel[] = [];\n  // The model as its own SHAPE demands it be read — a file parsed alone, or a\n  // slice of the project it extends (`core/c4/service-model/load.ts`). Kept for\n  // the service's own use cases below, which need both its views and which\n  // shape produced them.\n  let model: ServiceModel | null = null;\n  // The service's OWN use cases, scanned here rather than beside the grades it\n  // feeds: `c4.valid` reports how many were graded, and that count is the only\n  // surface a HEALTHY flow appears on. Null means no scan was made — the model\n  // does not parse (`c4.invalid` owns that, and a second load repeats its\n  // cascade under a use-case code) or its map does not (an extending model then\n  // comes back with no errors AND no model, and the flow project would be\n  // staged over the same broken map).\n  let flows: ServiceFlowScan | null = null;\n  if (!hasModel) {\n    findings.push({\n      severity: \"error\",\n      code: \"service.no-model\",\n      message: `No C4 model at ${repoPath(docsDir, paths.model)}. Run \\`loam adopt\\` for '${service}' first.`,\n    });\n  } else {\n    model = await fleet.serviceModel(docsDir, paths);\n    elements = model.doc.elements;\n    relationships = model.doc.relationships;\n    if (!model.mapUnreadable && model.doc.errors.length === 0) {\n      flows = await readServiceFlows({\n        paths,\n        model: model.doc,\n        known,\n        // An extending model's siblings resolve against the fleet map, so their\n        // project is the docs root's, never the service directory. The project\n        // the model was READ in travels with it because that is the scope of a\n        // view written inside model.likec4: `model.doc` is the service's own\n        // slice, and a hop backed by one of the map's edges is backed wherever\n        // the view sits.\n        ...(model.shape === \"extending\" && model.project !== null\n          ? { extending: { docsDir, project: model.project } }\n          : {}),\n      });\n    }\n    findings.push(\n      ...(await modelFindings({\n        service,\n        treePath,\n        docsDir,\n        model,\n        modelPath: paths.model,\n        known,\n        gradedFlows: flows?.kind === \"read\" ? flows.views.length : 0,\n      })),\n    );\n  }\n\n  // The fleet map as the PROJECT it is, in EVERY mode — landscape plus every\n  // `architecture/**/*.likec4` minus the generated views file. Single-service\n  // runs used to read `landscape.likec4` alone, which made three answers depend\n  // on which flag the caller happened to pass: a use-case file that does not\n  // parse was `spine.landscape-invalid` under `--all` and silence under\n  // `--service`, an extending model was readable under one and not the other,\n  // and `c4.declaration-diverged` would have compared against a different\n  // document. Under `--all` the caller hands in the doc it already loaded.\n  //\n  // Still gated on the landscape FILE existing: `land === null` means \"this repo\n  // draws no fleet\", and a repo with an `architecture/usecases/` and no map is\n  // that state, not a map that loaded empty.\n  const land =\n    preloaded ?? (existsSync(landscapeFile(docsDir)) ? await fleet.architecture(docsDir) : null);\n\n  // Where a standalone model's copies of the map's elements have drifted. After\n  // `c4.valid` because it is a claim about a model that parsed, and silent for\n  // an extending model, which has no copy to diverge.\n  if (model !== null) findings.push(...divergedFindings({ service, model, architecture: land, known }));\n\n\n  // The living landscape's element→service resolver, container-aware and\n  // memoized. Every question below that asks \"does this edge point at me?\"\n  // asks it through this one function, so the no-openapi grace, the HTTP spine\n  // and the event spine can never disagree about which edges are inbound.\n  const landSvcOf = land === null ? null : serviceResolver(land.elements, known);\n\n  const specs = await readServiceSpecs({ docsDir, service, paths, fleet });\n  findings.push(...specs.findings);\n  const { reqs, livingReqs, archText, archReqs } = specs;\n\n  const api = await apiAxisFindings({\n    docsDir,\n    service,\n    me,\n    paths,\n    reqs,\n    livingReqs,\n    land,\n    landSvcOf,\n    fleet,\n  });\n  findings.push(...api.findings);\n  findings.push(\n    ...spineFindings({\n      service,\n      docsDir,\n      treePath,\n      me,\n      land,\n      landSvcOf,\n      contract: api.contract,\n      landscapeReported: check.landscapeReported,\n      // An unreadable map takes an extending model with it, and the spine\n      // finding is where that is said — see `Spine.modelExtends`.\n      modelExtends: model?.shape === \"extending\",\n    }),\n  );\n  findings.push(\n    ...(await eventAxisFindings({\n      docsDir,\n      service,\n      me,\n      paths,\n      reqs,\n      livingReqs,\n      archReqs,\n      land,\n      landSvcOf,\n      known,\n      fleet,\n    })),\n  );\n  findings.push(\n    ...(await archAxisFindings({\n      service,\n      paths,\n      archText,\n      archReqs,\n      elements,\n      relationships,\n      // The one fact that tells \"this service models nothing\" apart from \"this\n      // service's model could not be read\" — its map does not parse, or it does\n      // not itself (`c4.invalid` above): both arrive here as empty lists, and\n      // only the second one must silence `covers.unknown`.\n      modelUnreadable: model !== null && (model.mapUnreadable || model.doc.errors.length > 0),\n      land,\n      known,\n      docsDir,\n      fleet,\n    })),\n  );\n\n  // The service's own use cases, GRADED — scanned beside the model above. Here\n  // rather than on the fleet target because the hops name this service's\n  // containers, which only its project resolves; after the arch axis because a\n  // `#req-` tag resolves against the ids both spec documents declare.\n  if (flows !== null) {\n    findings.push(\n      ...serviceUseCaseFindings({\n        service,\n        treePath,\n        docsDir,\n        scan: flows,\n        services: known,\n        requirementIds: requirementIdsOf(paths, livingReqs, archReqs),\n      }),\n    );\n  }\n\n  // The authorization axis. Both requirement documents are graded against one\n  // fleet vocabulary — a permission is a fleet fact, and an arch requirement\n  // gates on one exactly as a business requirement does. The capability axis\n  // rides the same loop against ITS fleet vocabulary; under --all the fleet\n  // memo makes that one parse for the whole run.\n  const vocabulary = await readVocabulary(permissionsPath(docsDir));\n  const capabilities = await fleet.capabilities(docsDir);\n  // The requirement-level index behind `Realizes:`. Built once for both axes,\n  // and behind the same ladder `capabilityUnknownIssues` applies — an absent\n  // or unreadable vocabulary means no reads and no grades at all, so a fleet\n  // that has not adopted the axis pays nothing for a line it never wrote.\n  const capabilityReqs = await capabilityRequirementIndex(capabilities, (p) => fleet.readRequirements(p));\n  for (const [label, docReqs] of [\n    [\"spec.md\", reqs],\n    [\"arch.spec.md\", archReqs],\n  ] as const) {\n    const target = { where: `${service}: ${label}`, subject: service };\n    findings.push(...requiresUnknownFindings(docReqs, target, vocabulary));\n    findings.push(...capabilityUnknownIssues(docReqs, target, capabilities));\n    findings.push(...realizesUnknownIssues(docReqs, target, capabilityReqs));\n    findings.push(...realizesStaleFindings(docReqs, target, capabilityReqs));\n    // The grammar guard, last in the loop: it grades the KEYS the three checks\n    // above resolve values from, so a line none of them saw is reported here\n    // rather than staying invisible for having produced nothing to check.\n    findings.push(...unknownDirectiveFindings(docReqs, target));\n  }\n\n  // The links this service's own documents write. Its place in the order is\n  // deliberate: every axis above joins through a LINE loam defined, and this one\n  // grades the join an author writes in prose — so it reads last among the\n  // document checks and adds no input any of them depend on.\n  findings.push(...(await serviceLinkFindings({ docsDir, subject: service, fleet }, paths)));\n\n  // Provenance last: who vouched for this, and what code it was written from.\n  findings.push(...(await serviceProvenance(docsDir, service, { repoDir, loamOwned: check.loamOwned, fleet })));\n  findings.push(...(await sourceScopeFindings(docsDir, service, repoDir, fleet)));\n  // The build's own contract against the committed copy. Service-repo only:\n  // from the docs repo there is no build output to read, and the family stays\n  // silent rather than guessing — the same rule `sources` provenance follows.\n  if (repoDir !== undefined) {\n    findings.push(...(await generatedContractFindings(service, repoDir, contracts?.openapi, paths.openapi)));\n  }\n\n  // The generated-gherkin freshness chain, service-repo-scoped like sources.*:\n  // it needs the repo (the suite lives there), and it stays quiet until\n  // <gherkinDir>/loam/ exists — a service that never generated has not opted in.\n  findings.push(...(await gherkinFindings({ docsDir, service, repoDir, gherkinDir, fleet })));\n\n  // The evidence-pin re-check, the same service-repo-scoped family: recorded\n  // verification citations graded against THIS working tree, quiet from the\n  // docs repo — sources.unverifiable-from-here already names that blind spot.\n  findings.push(...(await evidencePinFindings(docsDir, service, repoDir, fleet)));\n\n  // The one journal that does NOT live in the docs repo: gherkin commits into\n  // the service repo's emission root. A half-committed suite graded by the\n  // freshness chain above reads as merely stale — warn-severity, which never\n  // gates — while doctor calls the same state a blocker. Same finding, same\n  // code, led rather than appended, exactly as validate leads with the docs\n  // repo's own journal.\n  if (repoDir !== undefined) {\n    try {\n      const interrupted = await interruptedCommitFinding(gherkinRoot(repoDir, gherkinDir));\n      if (interrupted !== null) findings.unshift(interrupted);\n    } catch (err) {\n      // An unsafe gherkinDir is `loam gherkin`'s refusal to make, with its\n      // own sentence; grading declines to scan what it cannot trust.\n      if (!(err instanceof UnsafePathError)) throw err;\n    }\n  }\n\n  return report;\n}\n"]}