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

package/dist/core/verify/store/render.js

@@ -0,0 +1,57 @@
+/**
+ * The record as bytes: the header and the YAML that `store/commit.ts` swaps
+ * into place. Moved here from `../file.ts` when the contract-report validation
+ * pushed that module over the line limit — and the seam is real, not
+ * arithmetic: reading was never the inverse of rendering (a record is
+ * re-graded on the way in, because anything may have edited it since), so the
+ * two were cohabiting rather than forming a codec, while the RENDER and the
+ * COMMIT genuinely are one concern — this module produces exactly the bytes
+ * whose atomic swap that one performs. `../file.ts` keeps the reading and the
+ * grading, and its header says where the render went.
+ */
+import { stringify } from "yaml";
+import {} from "../record.js";
+/**
+ * The record as a file. The header explains what the reader is looking at,
+ * because the whole point is that this is legible to someone who has never run
+ * loam — including the part loam cannot vouch for.
+ */
+export function renderVerification(v) {
+    const header = [
+        `# Verification record for ${v.feature} — written by \`loam verify ${v.feature}\` (--results / --contract-results / --record).`,
+        "#",
+        "# Every claim below was derived mechanically from this feature's own artifacts:",
+        "# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/",
+        "# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a",
+        "# test report's digest-tagged scenarios answered it mechanically — cucumber JSON,",
+        "# or loam's own {\"loamScenarioReport\": 1, ...} shape that any runner adapts into;",
+        "# `answered_by: external-runner` means a contract-test report's operationId-matched",
+        "# entries did, and `contractReport:` records which file a --contract-results run",
+        "# read; `answered_by: agent` means somebody's word about the code, which loam did",
+        "# not check. Nothing gates on any of them.",
+        "#",
+        "# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam",
+        "# reports it as `verify.scenario-attested` and the feature does not count as",
+        "# verified until a report answers it. `report:` records the file a --results run",
+        "# read — its sha256 and mtime say WHICH file, not that it came from that commit;",
+        "# no digest can say that.",
+        "#",
+        "# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same",
+        "# one, the feature changed after this was recorded and these answers are stale.",
+        ...(v.schema === 2
+            ? [
+                "#",
+                "# Schema 2 is federated: each service entry under `attestations` binds its claim ids",
+                "# and file:line evidence to that repository's git commit. Missing claims are honestly",
+                "# unanswered; another service run may add them without rewriting existing attestations.",
+                "# `evidence_pins` records each cited file's sha256 (CRLF-normalized) and line text at",
+                "# the attested commit, so `loam validate` in that repo can convict drift later; a pin",
+                "# identifies what was cited — it does not prove the claim true.",
+            ]
+            : []),
+        "",
+    ].join("\n");
+    // lineWidth 0: never fold a claim onto a second line — these are grepped and diffed.
+    return header + stringify(v, { lineWidth: 0 });
+}
+//# sourceMappingURL=render.js.map

package/dist/core/verify/store/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../../src/core/verify/store/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAqB,MAAM,cAAc,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAe;IAChD,MAAM,MAAM,GAAG;QACb,6BAA6B,CAAC,CAAC,OAAO,+BAA+B,CAAC,CAAC,OAAO,iDAAiD;QAC/H,GAAG;QACH,iFAAiF;QACjF,gFAAgF;QAChF,mFAAmF;QACnF,mFAAmF;QACnF,qFAAqF;QACrF,qFAAqF;QACrF,kFAAkF;QAClF,mFAAmF;QACnF,4CAA4C;QAC5C,GAAG;QACH,8EAA8E;QAC9E,8EAA8E;QAC9E,kFAAkF;QAClF,kFAAkF;QAClF,2BAA2B;QAC3B,GAAG;QACH,uFAAuF;QACvF,iFAAiF;QACjF,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;YAChB,CAAC,CAAC;gBACE,GAAG;gBACH,sFAAsF;gBACtF,uFAAuF;gBACvF,yFAAyF;gBACzF,uFAAuF;gBACvF,uFAAuF;gBACvF,iEAAiE;aAClE;YACH,CAAC,CAAC,EAAE,CAAC;QACP,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,qFAAqF;IACrF,OAAO,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;AACjD,CAAC","sourcesContent":["/**\n * The record as bytes: the header and the YAML that `store/commit.ts` swaps\n * into place. Moved here from `../file.ts` when the contract-report validation\n * pushed that module over the line limit — and the seam is real, not\n * arithmetic: reading was never the inverse of rendering (a record is\n * re-graded on the way in, because anything may have edited it since), so the\n * two were cohabiting rather than forming a codec, while the RENDER and the\n * COMMIT genuinely are one concern — this module produces exactly the bytes\n * whose atomic swap that one performs. `../file.ts` keeps the reading and the\n * grading, and its header says where the render went.\n */\nimport { stringify } from \"yaml\";\nimport { type Verification } from \"../record.js\";\n\n/**\n * The record as a file. The header explains what the reader is looking at,\n * because the whole point is that this is legible to someone who has never run\n * loam — including the part loam cannot vouch for.\n */\nexport function renderVerification(v: Verification): string {\n  const header = [\n    `# Verification record for ${v.feature} — written by \\`loam verify ${v.feature}\\` (--results / --contract-results / --record).`,\n    \"#\",\n    \"# Every claim below was derived mechanically from this feature's own artifacts:\",\n    \"# delta.likec4, specs/<svc>/spec.md, specs/<svc>/arch.spec.md and specs/<svc>/\",\n    \"# openapi.yaml. Each verdict names who answered it: `answered_by: runner` means a\",\n    \"# test report's digest-tagged scenarios answered it mechanically — cucumber JSON,\",\n    \"# or loam's own {\\\"loamScenarioReport\\\": 1, ...} shape that any runner adapts into;\",\n    \"# `answered_by: external-runner` means a contract-test report's operationId-matched\",\n    \"# entries did, and `contractReport:` records which file a --contract-results run\",\n    \"# read; `answered_by: agent` means somebody's word about the code, which loam did\",\n    \"# not check. Nothing gates on any of them.\",\n    \"#\",\n    \"# A `scenario.tested` claim confirmed by an agent is ATTESTED, not run: loam\",\n    \"# reports it as `verify.scenario-attested` and the feature does not count as\",\n    \"# verified until a report answers it. `report:` records the file a --results run\",\n    \"# read — its sha256 and mtime say WHICH file, not that it came from that commit;\",\n    \"# no digest can say that.\",\n    \"#\",\n    \"# `checklist` is a digest of the claim ids. If `loam verify` stops reporting the same\",\n    \"# one, the feature changed after this was recorded and these answers are stale.\",\n    ...(v.schema === 2\n      ? [\n          \"#\",\n          \"# Schema 2 is federated: each service entry under `attestations` binds its claim ids\",\n          \"# and file:line evidence to that repository's git commit. Missing claims are honestly\",\n          \"# unanswered; another service run may add them without rewriting existing attestations.\",\n          \"# `evidence_pins` records each cited file's sha256 (CRLF-normalized) and line text at\",\n          \"# the attested commit, so `loam validate` in that repo can convict drift later; a pin\",\n          \"# identifies what was cited — it does not prove the claim true.\",\n        ]\n      : []),\n    \"\",\n  ].join(\"\\n\");\n  // lineWidth 0: never fold a claim onto a second line — these are grepped and diffed.\n  return header + stringify(v, { lineWidth: 0 });\n}\n"]}

package/dist/core/vocabulary/health.js

@@ -0,0 +1,91 @@
+/**
+ * The minimal reader for `services/<svc>/health.yaml` — the moment that file
+ * stops being inert. loam reads exactly one KIND of thing out of it: ids. The
+ * alert and SLI ids, so the architecture spec axis can ask whether a
+ * requirement covers each one (`health.uncovered`); and the dependency ids,
+ * so the same axis can weigh and reconcile them against the service's own
+ * model — otherwise the file an on-call engineer reaches for first is free text
+ * as far as validation is concerned and can hold false operational claims under
+ * a green result. Queries, thresholds, checks, criticality — everything else
+ * stays authored prose that no check reads, the same stance `operationIds`
+ * takes on OpenAPI schemas.
+ *
+ * The recognized keys (documented in SCHEMA.md, and deliberately few):
+ *
+ *   slis:         a YAML sequence; each entry contributes its `name` (or `id`
+ *   alerts:       when there is no name), and a plain string entry is its own id.
+ *   dependencies: a YAML sequence; each entry contributes its `id` (or
+ *                 `service`, or `name` — accepted inputs use all three forms),
+ *                 and a plain string entry is its own id.
+ *
+ * Tolerant about absence, honest about breakage: a health.yaml that is missing
+ * or declares nothing recognizable yields an empty set — and an empty set
+ * produces no findings, because an absent file must not manufacture
+ * obligations. A file that EXISTS but cannot be read is different evidence:
+ * its ids are unknown, not empty, so the `unreadable` flag travels alongside
+ * (parsers never diagnose — validate grades it as `health.invalid`). The old
+ * silent empty set turned every `Covers: alert:/sli:` entry of that service
+ * into a false `covers.unknown` "typo", when the truth was this file.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+const NO_HEALTH_IDS = { slis: [], alerts: [] };
+export async function readHealth(healthPath) {
+    if (!existsSync(healthPath))
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };
+    let doc;
+    try {
+        doc = parse(await readFile(healthPath, "utf8"));
+    }
+    catch (e) {
+        return {
+            ids: NO_HEALTH_IDS,
+            dependencies: [],
+            unreadable: true,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    // An empty file parses to null: it declares nothing, and says so honestly.
+    // A scalar or sequence document declares nothing READABLE — flag it.
+    if (doc === null)
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };
+    if (typeof doc !== "object" || Array.isArray(doc)) {
+        return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: true, error: "document is not a YAML mapping" };
+    }
+    const top = doc;
+    return {
+        ids: { slis: idsOf(top["slis"], NAME_KEYS), alerts: idsOf(top["alerts"], NAME_KEYS) },
+        dependencies: idsOf(top["dependencies"], DEPENDENCY_KEYS),
+        unreadable: false,
+    };
+}
+/** slis/alerts entries answer to `name` first — the key SCHEMA.md teaches. */
+const NAME_KEYS = ["name", "id"];
+/**
+ * Dependency entries answer to `id` first, because it is the explicit
+ * identity; `service` and `name` are the spellings found in the wild.
+ * Tolerance in reading is not vocabulary — SCHEMA.md still teaches one.
+ */
+const DEPENDENCY_KEYS = ["id", "service", "name"];
+/** The ids one sequence declares — first recognized key wins, deduped, document order. */
+function idsOf(section, keys) {
+    if (!Array.isArray(section))
+        return [];
+    const out = new Set();
+    for (const entry of section) {
+        if (typeof entry === "string") {
+            if (entry.trim().length > 0)
+                out.add(entry.trim());
+            continue;
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const rec = entry;
+        const id = keys.map((k) => rec[k]).find((v) => typeof v === "string" && v.trim().length > 0);
+        if (typeof id === "string")
+            out.add(id.trim());
+    }
+    return [...out];
+}
+//# sourceMappingURL=health.js.map

package/dist/core/vocabulary/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../../src/core/vocabulary/health.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The minimal reader for `services/<svc>/health.yaml` — the moment that file\n * stops being inert. loam reads exactly one KIND of thing out of it: ids. The\n * alert and SLI ids, so the architecture spec axis can ask whether a\n * requirement covers each one (`health.uncovered`); and the dependency ids,\n * so the same axis can weigh and reconcile them against the service's own\n * model — otherwise the file an on-call engineer reaches for first is free text\n * as far as validation is concerned and can hold false operational claims under\n * a green result. Queries, thresholds, checks, criticality — everything else\n * stays authored prose that no check reads, the same stance `operationIds`\n * takes on OpenAPI schemas.\n *\n * The recognized keys (documented in SCHEMA.md, and deliberately few):\n *\n *   slis:         a YAML sequence; each entry contributes its `name` (or `id`\n *   alerts:       when there is no name), and a plain string entry is its own id.\n *   dependencies: a YAML sequence; each entry contributes its `id` (or\n *                 `service`, or `name` — accepted inputs use all three forms),\n *                 and a plain string entry is its own id.\n *\n * Tolerant about absence, honest about breakage: a health.yaml that is missing\n * or declares nothing recognizable yields an empty set — and an empty set\n * produces no findings, because an absent file must not manufacture\n * obligations. A file that EXISTS but cannot be read is different evidence:\n * its ids are unknown, not empty, so the `unreadable` flag travels alongside\n * (parsers never diagnose — validate grades it as `health.invalid`). The old\n * silent empty set turned every `Covers: alert:/sli:` entry of that service\n * into a false `covers.unknown` \"typo\", when the truth was this file.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\n\nexport interface HealthIds {\n  slis: string[];\n  alerts: string[];\n}\n\nconst NO_HEALTH_IDS: HealthIds = { slis: [], alerts: [] };\n\n/** The read of one health.yaml: its declared ids, and whether the file could be read at all. */\nexport interface HealthFile {\n  ids: HealthIds;\n  /** Ids of the `dependencies:` entries — empty when the file is missing, empty, or unreadable. */\n  dependencies: string[];\n  /** True when the file exists but is not a readable YAML mapping. Missing and empty files read as empty, not broken. */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n}\n\nexport async function readHealth(healthPath: string): Promise<HealthFile> {\n  if (!existsSync(healthPath)) return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };\n  let doc: unknown;\n  try {\n    doc = parse(await readFile(healthPath, \"utf8\"));\n  } catch (e) {\n    return {\n      ids: NO_HEALTH_IDS,\n      dependencies: [],\n      unreadable: true,\n      error: e instanceof Error ? e.message : String(e),\n    };\n  }\n  // An empty file parses to null: it declares nothing, and says so honestly.\n  // A scalar or sequence document declares nothing READABLE — flag it.\n  if (doc === null) return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: false };\n  if (typeof doc !== \"object\" || Array.isArray(doc)) {\n    return { ids: NO_HEALTH_IDS, dependencies: [], unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  const top = doc as Record<string, unknown>;\n  return {\n    ids: { slis: idsOf(top[\"slis\"], NAME_KEYS), alerts: idsOf(top[\"alerts\"], NAME_KEYS) },\n    dependencies: idsOf(top[\"dependencies\"], DEPENDENCY_KEYS),\n    unreadable: false,\n  };\n}\n\n/** slis/alerts entries answer to `name` first — the key SCHEMA.md teaches. */\nconst NAME_KEYS = [\"name\", \"id\"] as const;\n/**\n * Dependency entries answer to `id` first, because it is the explicit\n * identity; `service` and `name` are the spellings found in the wild.\n * Tolerance in reading is not vocabulary — SCHEMA.md still teaches one.\n */\nconst DEPENDENCY_KEYS = [\"id\", \"service\", \"name\"] as const;\n\n/** The ids one sequence declares — first recognized key wins, deduped, document order. */\nfunction idsOf(section: unknown, keys: readonly string[]): string[] {\n  if (!Array.isArray(section)) return [];\n  const out = new Set<string>();\n  for (const entry of section) {\n    if (typeof entry === \"string\") {\n      if (entry.trim().length > 0) out.add(entry.trim());\n      continue;\n    }\n    if (entry === null || typeof entry !== \"object\" || Array.isArray(entry)) continue;\n    const rec = entry as Record<string, unknown>;\n    const id = keys.map((k) => rec[k]).find((v) => typeof v === \"string\" && v.trim().length > 0);\n    if (typeof id === \"string\") out.add(id.trim());\n  }\n  return [...out];\n}\n"]}

package/dist/core/vocabulary/issue.js

@@ -0,0 +1,58 @@
+/**
+ * A coherence breach: something that makes a feature unsafe to merge into the
+ * living docs. Shared by every check the archive gate runs.
+ */
+/** Whether `loam archive` refuses on this issue without `--approve`. */
+export function gatesArchive(i) {
+    return i.gates ?? i.severity === "error";
+}
+/** One issue in the shared validation/status finding shape. */
+export function issueFinding(i) {
+    return {
+        severity: i.severity,
+        code: i.code,
+        gates: gatesArchive(i),
+        ...(i.subject === undefined ? {} : { subject: i.subject }),
+        ...(i.locations === undefined ? {} : { locations: i.locations }),
+        message: i.message,
+    };
+}
+/**
+ * Whether `--approve` can move this issue when it gates. A third axis beside
+ * severity and gating: severity answers "is the DOCUMENT valid", gating
+ * answers "is the MERGE safe", and this one answers whose call the refusal is
+ * — a human's or the grammar's. Almost every gating issue is a judgment about
+ * the feature, which is exactly the judgment `--approve` exists to override.
+ *
+ * The exceptions are the ones where approval could not change what happens.
+ * `c4.service-binding-invalid`: the binding IS the path the merge would write,
+ * so the fix is the name, never the flag. `glossary.term-exists`: the merge is
+ * a whole-file copy over an authored definition, so approving it is approving a
+ * deletion nobody described — and the alternative the message names (edit the
+ * living definition in the same change) costs one `git mv` and loses nothing.
+ * `usecase.flow-exists` is the same act one axis over: the merge would copy a
+ * feature's flow over a living one, and an ordered hop sequence is recorded
+ * nowhere else either. `usecase.flow-invalid` is the other kind of exception —
+ * not a deletion but a BLINDNESS: loam could not read the feature's flows
+ * against the map its own merge would leave, so it graded nothing, and
+ * `--approve` overrides loam's judgment about coherence and never its ability
+ * to read an axis. That is the same line `delta.likec4`'s unparseable case is
+ * refused on, one merge over.
+ *
+ * `archive` refuses these under the same `not-coherent` envelope and spells
+ * this verdict per issue as the additive `overridable` key, so a `--json`
+ * consumer branches on data rather than on a code list.
+ */
+const NEVER_OVERRIDABLE = new Set([
+    "c4.service-binding-invalid",
+    "glossary.term-exists",
+    "usecase.flow-exists",
+    "deployment.doc-exists",
+    "deployment.doc-invalid",
+    "deployment.doc-reserved",
+    "usecase.flow-invalid",
+]);
+export function approveOverrides(i) {
+    return !NEVER_OVERRIDABLE.has(i.code);
+}
+//# sourceMappingURL=issue.js.map

package/dist/core/vocabulary/issue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../src/core/vocabulary/issue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,CAAQ;IACnC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC;AAC3C,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,CAAQ;IACnC,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;QACtB,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1D,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;QAChE,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,iBAAiB,GAA2B,IAAI,GAAG,CAAY;IACnE,4BAA4B;IAC5B,sBAAsB;IACtB,qBAAqB;IACrB,uBAAuB;IACvB,wBAAwB;IACxB,yBAAyB;IACzB,sBAAsB;CACvB,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,CAAQ;IACvC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC","sourcesContent":["/**\n * A coherence breach: something that makes a feature unsafe to merge into the\n * living docs. Shared by every check the archive gate runs.\n */\n\nimport type { Finding, FindingLocation } from \"./report.js\";\n\nexport interface Issue {\n  severity: \"error\" | \"warn\";\n  /** Stable machine identifier for the breach — see the labels below. */\n  code: IssueCode;\n  /** What the breach is about when that is narrower than the feature — usually a service. */\n  subject?: string;\n  message: string;\n  locations?: FindingLocation[];\n  /**\n   * Does this issue stop `loam archive`? Severity and gating answer two\n   * different questions: severity says whether the DOCUMENT is valid (`loam\n   * validate` fails on errors), gating says whether the MERGE is safe. They\n   * usually agree — errors gate, warnings do not — so the field is stated only\n   * where they diverge: a legal document whose merge would drop authored\n   * content is a warning that gates.\n   */\n  gates?: boolean;\n}\n\n/** Whether `loam archive` refuses on this issue without `--approve`. */\nexport function gatesArchive(i: Issue): boolean {\n  return i.gates ?? i.severity === \"error\";\n}\n\n/** One issue in the shared validation/status finding shape. */\nexport function issueFinding(i: Issue): Finding {\n  return {\n    severity: i.severity,\n    code: i.code,\n    gates: gatesArchive(i),\n    ...(i.subject === undefined ? {} : { subject: i.subject }),\n    ...(i.locations === undefined ? {} : { locations: i.locations }),\n    message: i.message,\n  };\n}\n\n/**\n * Whether `--approve` can move this issue when it gates. A third axis beside\n * severity and gating: severity answers \"is the DOCUMENT valid\", gating\n * answers \"is the MERGE safe\", and this one answers whose call the refusal is\n * — a human's or the grammar's. Almost every gating issue is a judgment about\n * the feature, which is exactly the judgment `--approve` exists to override.\n *\n * The exceptions are the ones where approval could not change what happens.\n * `c4.service-binding-invalid`: the binding IS the path the merge would write,\n * so the fix is the name, never the flag. `glossary.term-exists`: the merge is\n * a whole-file copy over an authored definition, so approving it is approving a\n * deletion nobody described — and the alternative the message names (edit the\n * living definition in the same change) costs one `git mv` and loses nothing.\n * `usecase.flow-exists` is the same act one axis over: the merge would copy a\n * feature's flow over a living one, and an ordered hop sequence is recorded\n * nowhere else either. `usecase.flow-invalid` is the other kind of exception —\n * not a deletion but a BLINDNESS: loam could not read the feature's flows\n * against the map its own merge would leave, so it graded nothing, and\n * `--approve` overrides loam's judgment about coherence and never its ability\n * to read an axis. That is the same line `delta.likec4`'s unparseable case is\n * refused on, one merge over.\n *\n * `archive` refuses these under the same `not-coherent` envelope and spells\n * this verdict per issue as the additive `overridable` key, so a `--json`\n * consumer branches on data rather than on a code list.\n */\nconst NEVER_OVERRIDABLE: ReadonlySet<IssueCode> = new Set<IssueCode>([\n  \"c4.service-binding-invalid\",\n  \"glossary.term-exists\",\n  \"usecase.flow-exists\",\n  \"deployment.doc-exists\",\n  \"deployment.doc-invalid\",\n  \"deployment.doc-reserved\",\n  \"usecase.flow-invalid\",\n]);\n\nexport function approveOverrides(i: Issue): boolean {\n  return !NEVER_OVERRIDABLE.has(i.code);\n}\n\n/**\n * The three grades a CAPABILITY DOCUMENT earns on its own terms, named as a\n * union of their own because both corpora emit them and the two must stay one\n * list: `validate --all` grades the living `capabilities/<id>/spec.md` and\n * files them as Findings, while the archive gate grades a feature's\n * `features/<FEAT>/capabilities/<id>/spec.md` and files the SAME three as\n * archive-gating Issues.\n *\n * Grading the delta is not belt-and-braces. Without it, a capability\n * requirement with no `Requirement-ID:` — or one carrying `Operations:`, the\n * service-altitude line the whole corpus exists to keep out — merges into the\n * living tree and only THEN earns its error, against a document whoever reads\n * the finding did not write. The feature-local delta must not become a second\n * way to write service requirements, and this is the rule that stops it.\n *\n * No code is added to the product here: all three already shipped, are already\n * emitted from `core/capabilities/findings.ts` with literal `code:` values, and\n * are already documented in the `/loam-check` table. What the union member adds\n * is the compiler's permission to file the same finding at the archive gate.\n */\nexport type CapabilityDocCode =\n  /** a requirement in a capability document with no `Requirement-ID:` — identity by heading, which every join to it breaks on */\n  | \"capability.requirement-unidentified\"\n  /** a capability requirement carrying `Operations:`/`Covers:`/`Publishes:`/`Consumes:` — a service requirement filed at the wrong altitude */\n  | \"capability.requirement-service-scoped\"\n  /** a capability requirement carrying `Capability:` or `Realizes:` — the axis's own joins, which point into the tree and so do nothing written inside it */\n  | \"capability.requirement-inert-join\";\n\nexport type IssueCode =\n  /* --- cross-axis: C4 <-> requirements <-> OpenAPI --- */\n  /** the architecture axis could not be read at all */\n  | \"delta.invalid\"\n  /** the delta declares elements or edges but none carry the feature tag — loam cannot see any of it */\n  | \"delta.nothing-tagged\"\n  /** E1 — a requirement governs an operation its service's OpenAPI does not define */\n  | \"spec-api.op-undefined\"\n  /** E1, softened — the operation is defined by another feature still in flight; archive that one first */\n  | \"spec-api.op-pending\"\n  /** E2 — a C4 edge calls an operation the target's OpenAPI does not define */\n  | \"c4-api.op-undefined\"\n  /** E2, softened — the operation is defined by another feature still in flight; archive that one first */\n  | \"c4-api.op-pending\"\n  /** E2's lifecycle shadow — a NEW tagged edge consumes an operation the living provider contract marks `deprecated: true`; advisory, never a gate */\n  | \"c4-api.op-deprecated\"\n  /** a NEW tagged edge consumes an operation this same feature removes */\n  | \"c4-api.op-removing\"\n  /** an operation-removal marker addresses no living path+method */\n  | \"openapi.remove-target-missing\"\n  /** an operation-removal marker's id differs from the living operation at that path+method */\n  | \"openapi.remove-target-mismatch\"\n  /** a REMOVED requirement governs an operation but the feature has no matching removal marker */\n  | \"openapi.remove-marker-missing\"\n  /** an operation-removal marker is not justified by a REMOVED requirement */\n  | \"openapi.remove-marker-unjustified\"\n  /* --- the event axis: C4 <-> requirements <-> AsyncAPI, joined on the message name --- */\n  /** the FEATURE's own asyncapi.yaml exists but does not parse — the same name validate gives a living contract in that state: every event-axis check for the service is suspended */\n  | \"asyncapi.invalid\"\n  /** an `x-loam-based-on` that is not a digest or one on a slot the living contract does not have; a malformed `x-loam-baselines` record, an entry of it naming a component surface the delta does not declare, or one whose living counterpart is gone */\n  | \"asyncapi.baseline-invalid\"\n  /** a feature slot or component surface with no baseline pin — the merge cannot tell whether the delta EDITS it or merely quotes it; warn that gates, counted per service */\n  | \"asyncapi.baseline-missing\"\n  /** the living slot or component surface changed since this delta pinned it — merging would discard whoever landed in between */\n  | \"asyncapi.baseline-stale\"\n  /** a slot-removal marker addresses a (section, key) the living contract does not have */\n  | \"asyncapi.remove-target-missing\"\n  /** a message-removal marker's name differs from the living declaration at that key */\n  | \"asyncapi.remove-target-mismatch\"\n  /** a REMOVED requirement's Publishes:/Consumes: line names a message the living contract still declares, with no matching removal marker in the feature */\n  | \"asyncapi.remove-marker-missing\"\n  /** a message-removal marker no REMOVED requirement's Publishes:/Consumes: line justifies — message slots only; channel and operation slots need exactness alone */\n  | \"asyncapi.remove-marker-unjustified\"\n  /** the feature retires a message the LIVING fleet still consumes — a landscape consumes-edge, or another service's living requirement */\n  | \"asyncapi.remove-message-consumed\"\n  /** another feature in flight adds or edits the same (service, message) — whichever archives second replaces the other's declaration wholesale */\n  | \"asyncapi.message-conflict\"\n  /** internal `$ref`(s) resolving to nothing — validate's warn on a living contract; a gating plan issue at archive when the MERGED document would carry the dangling reference */\n  | \"asyncapi.ref-unresolved\"\n  /** a tagged edge publishes/consumes a message its bound service's contract — as the feature's merge would leave it, feature ∪ living where no delta exists — declares no matching send/receive operation for */\n  | \"c4-event.message-undefined\"\n  /** softened — the message is introduced by another feature still in flight; archive that one first */\n  | \"c4-event.message-pending\"\n  /** a delta requirement's Publishes:/Consumes: line names a message the service's contract — as the feature's merge would leave it, so a retired declaration stops answering — does not declare in that direction; validate's living-side code, graded in feature scope too */\n  | \"spec-event.message-undefined\"\n  /** softened — the named message is introduced by another feature still in flight */\n  | \"spec-event.message-pending\"\n  /** W1 — an operation is called but no requirement governs it */\n  | \"c4.op-ungoverned\"\n  /** W2 — the feature adds an operation no architecture edge consumes */\n  | \"api.op-unconsumed\"\n  /** W3 — a new service arrives with no requirement delta */\n  | \"service.no-requirement-delta\"\n  /** W4 — a \"Calls\" edge carries no operation link */\n  | \"c4.op-link-missing\"\n  /** an explicit `metadata { service }` binding — a tagged element's, or one riding anywhere inside its authored block — breaks the service-id grammar; the merge would splice the name into the living landscape verbatim, and probe services/<id>/ with it; never overridable, the path is a mechanical fact */\n  | \"c4.service-binding-invalid\"\n  /* --- delta shape: does the diff apply to the living spec it claims to change? --- */\n  /** a heading that nearly matches the delta grammar — its requirements merge as nothing */\n  | \"delta.unknown-section\"\n  /** a delta file with requirements but no delta section anywhere — the whole file would merge as nothing */\n  | \"delta.no-delta-sections\"\n  /** a requirement stranded under a prose heading — archive will not merge it */\n  | \"delta.requirement-not-merged\"\n  /** a Requirement-ID in a delta violates the stable-id grammar */\n  | \"delta.requirement-id-invalid\"\n  /** one delta requirement declares Requirement-ID more than once */\n  | \"delta.requirement-id-repeated\"\n  /** one Requirement-ID identifies multiple requirements in a delta */\n  | \"delta.requirement-id-duplicate\"\n  /** the living spec has malformed/ambiguous IDs and cannot be selected safely */\n  | \"delta.living-requirement-id-invalid\"\n  /** a delta's stable ID and heading select different living requirements */\n  | \"delta.requirement-identity-collision\"\n  /** MODIFIED a requirement the living spec does not have */\n  | \"delta.modified-unknown\"\n  /** REMOVED a requirement the living spec does not have */\n  | \"delta.removed-unknown\"\n  /** ADDED a requirement the living spec already has — the merge would replace it */\n  | \"delta.added-duplicate\"\n  /** ADDED a name that differs only in case from a living requirement — the merge matches exactly, so both would coexist */\n  | \"delta.added-near-duplicate\"\n  /** MODIFIED something another feature in flight introduces — an ordering dependency */\n  | \"delta.modified-pending\"\n  /** REMOVED something another feature in flight introduces */\n  | \"delta.removed-pending\"\n  /** two features in flight add the same requirement to the same service */\n  | \"delta.added-conflict\"\n  /* --- archive plan: breaches only the merge computation itself can see --- */\n  /** a LIVING requirement outside `## Requirements` — the merge rewrites only that section, so it would land twice */\n  | \"living.requirement-outside-requirements\"\n  /** the delta redefines an operation the living OpenAPI already has — the merge overwrites it wholesale */\n  | \"openapi.op-modified\"\n  /** a component the merge carries — reached by a merged operation, or declared by a delta whose whole change is components — already exists in the living OpenAPI with different content, and the merge overwrites it wholesale */\n  | \"openapi.component-modified\"\n  /** a $ref reachable from the merged operations or a merged component resolves in neither the feature's OpenAPI nor the living one — merging would write a dangling reference */\n  | \"openapi.ref-unresolved\"\n  /** the delta redefines a PATH-level key (parameters, servers, summary) the living OpenAPI already has — the overwrite applies to every operation on that path */\n  | \"openapi.path-item-modified\"\n  /** the delta redefines a `components.messages` slot the living AsyncAPI already has — the merge overwrites the living message wholesale */\n  | \"asyncapi.message-modified\"\n  /** the delta redefines a `channels` slot the living AsyncAPI already has — the merge overwrites it wholesale, inline channel messages included */\n  | \"asyncapi.channel-modified\"\n  /** the delta redefines an `operations` slot the living AsyncAPI already has — the merge overwrites it wholesale */\n  | \"asyncapi.operation-modified\"\n  /** the delta declares a component SURFACE outside `components.messages` — a schema, a security scheme — that the living AsyncAPI already has with different content, and the merge copies the feature's version over it wholesale */\n  | \"asyncapi.component-modified\"\n  /** an `x-loam-remove: true` marker with no operationId — loam cannot tell which operation it retires, and the marker itself would reach the living contract */\n  | \"openapi.remove-marker-anonymous\"\n  /** an `x-loam-remove: true` written at PATH level, beside the methods — it addresses no operation, so it retires nothing and is not a contract key either */\n  | \"openapi.remove-marker-path-level\"\n  /** an `x-loam-remove: true` nested on an INLINE channel message — inline messages are channel interior, never slots, so it retires nothing; when the channel is otherwise unchanged the marker surfaces nowhere else at all */\n  | \"asyncapi.remove-marker-inline\"\n  /** the living OpenAPI defines one operationId in two (path, method) slots — every join on the id picks one arbitrarily */\n  | \"openapi.duplicate-operationid\"\n  /** the FEATURE's own openapi.yaml exists but does not parse — the same name validate gives a living contract in that state: every contract-axis check for the service is suspended, and the archive plan refuses the merge mechanically */\n  | \"openapi.invalid\"\n  /** an `x-loam-based-on` that is not a digest or sits on an operation the living contract does not have; a malformed `x-loam-baselines` record, an entry of it pinning a surface the delta does not restate, or one whose living counterpart is gone */\n  | \"openapi.baseline-invalid\"\n  /** a feature operation, restated path-level key or component with no baseline pin — the merge cannot tell whether the delta EDITS it or merely quotes it */\n  | \"openapi.baseline-missing\"\n  /** the living operation, path-level key or component changed since this delta pinned it — merging would discard whoever landed in between */\n  | \"openapi.baseline-stale\"\n  /** the feature retires an operation the LIVING fleet still consumes — a landscape edge's `metadata { op }`, or another service's living requirement */\n  | \"openapi.remove-op-consumed\"\n  /** two requirements in the LIVING document share one heading — MODIFIED rewrites the first, REMOVED deletes both, so no delta applies predictably */\n  | \"delta.living-duplicate-requirement\"\n  /** another feature in flight MODIFIES/REMOVES the same living requirement — whichever archives second replaces the other's text wholesale */\n  | \"delta.modified-conflict\"\n  /** a `Based-On:` line whose value is not a digest, or declared twice — the pin cannot be compared, so it protects nothing */\n  | \"delta.baseline-invalid\"\n  /** a MODIFIED/REMOVED requirement with no `Based-On:` — nothing can tell whether the living text moved under it */\n  | \"delta.baseline-missing\"\n  /** the living requirement changed since this delta was written — merging it would silently discard whoever landed in between */\n  | \"delta.baseline-stale\"\n  /** the archive creates `services/<id>/` but nothing writes its `model.likec4` — the fleet gate will report the service incomplete */\n  | \"service.no-model\"\n  /* --- capability axis: the Capability: join against architecture/capabilities.yaml --- */\n  /** a delta requirement's `Capability:` entry that the fleet vocabulary does not declare — the merge would land a join that resolves to nothing, so it blocks archive like other errors, and `--approve` overrides it */\n  | \"capability.unknown\"\n  /** a delta requirement's `Realizes:` entry that names no capability requirement — same argument as `capability.unknown` one join over: the merge would land a pointer at a promise that does not exist, looking exactly like a working one */\n  | \"capability.realizes-unknown\"\n  /** a capability requirement this feature ADDS that no `Realizes:` line in the same feature's service deltas names — the merge would land a business promise nothing in this change keeps. A warning that GATES, `--approve` overrides: the document is legal (writing ahead of the fleet is the intended use, which is why `capability.requirement-unrealized` warns and never gates), the MERGE is what is unsafe. Joined by `Realizes:`, NOT by `Covers:` — the name is the roadmap's, the join is the other one */\n  | \"capability.uncovered\"\n  /** the same join in the removal direction — this feature RETIRES a capability requirement that something the merge leaves behind still realizes, so the archive would leave `capability.realizes-unknown` standing against a document nobody in the feature touched. An error, exactly as `openapi.remove-op-consumed` is for the identical shape one axis over */\n  | \"capability.remove-requirement-realized\"\n  | CapabilityDocCode\n  /* --- the domain glossary: a term a feature introduces --- */\n  /** a `features/<FEAT>/glossary/<term>.md` whose term the living glossary already defines — the merge is a whole-file copy, so it would replace an authored definition wholesale. An error with no legal reading, which is why `--approve` changes nothing about it: a feature-local glossary document INTRODUCES a term, and rewriting one belongs in a pull request where git produces the conflict */\n  | \"glossary.term-exists\"\n  /* --- the use-case axis: a flow a feature introduces --- */\n  /** a `features/<FEAT>/usecases/*.likec4` that could not be read against the map this feature's own merge would leave behind — a parse error, an unresolved element, or a landscape merge that itself refuses. The flows were not graded, and archiving would copy them into `architecture/` for the next reader's `loam validate --all` to fail on. Mechanical rather than a judgement, which is why `--approve` does not move it */\n  | \"usecase.flow-invalid\"\n  /** a `features/<FEAT>/usecases/<name>.likec4` whose flow the living `architecture/` already holds — the merge is a whole-file copy, so it would replace an authored hop sequence wholesale. An error with no legal reading, which is why `--approve` changes nothing about it: a feature-local flow INTRODUCES a use case, and rewriting one belongs in a pull request where git produces the conflict */\n  | \"usecase.flow-exists\"\n  /* --- the deployment axis: the topology a feature introduces --- */\n  /** a `features/<FEAT>/deployment/<name>.likec4` whose file the living `architecture/` already holds — the merge is a whole-file copy, so it would replace an authored topology wholesale. An error with no legal reading, which is why `--approve` changes nothing about it: a feature-local deployment document INTRODUCES topology, and rewriting one belongs in a pull request where git produces the conflict. The same act, and the same severity, as `usecase.flow-exists` one axis over */\n  | \"deployment.doc-exists\"\n  /** a `features/<FEAT>/deployment/*.likec4` that could not be read against the map this feature's own merge would leave behind — a parse error, an unresolved element, or a landscape merge that itself refuses. The topology was not graded, and archiving would copy it into `architecture/` for the next reader's `loam validate --all` to fail on. Mechanical rather than a judgement, which is why `--approve` does not move it; the twin of `usecase.flow-invalid` one axis over */\n  | \"deployment.doc-invalid\"\n  /** a `features/<FEAT>/deployment/<name>.likec4` whose name is one loam owns inside `architecture/` — `subsystems.likec4` (generated, overwritten wholesale by `loam subsystem sync`, and parsed by nothing, so anything landing there is invisible from the moment it archives), `landscape.likec4` (spliced into, never replaced), or a path under `usecases/` (the flow tree). Refused whether or not the target exists, which is the point: two of the three fail silently when it does not. An error with no legal reading, so `--approve` changes nothing about it */\n  | \"deployment.doc-reserved\"\n  /* --- authoring: did a person actually write this? --- */\n  /** a document `loam new` scaffolded still carries its exact placeholder text — the merge would publish a requirement, scenario or description nobody authored */\n  | \"scaffold.placeholder\"\n  /** intent.md is missing, or says nothing outside the scaffold's own comments — nothing states why the feature exists */\n  | \"intent.empty\"\n  /* --- docs-repo contract: --all only, never a merge question --- */\n  /** AGENTS.md carries no version stamp, or one older than the running binary — the agent contract may have drifted */\n  | \"agents.stale\";\n"]}

package/dist/core/vocabulary/maturity.js

@@ -0,0 +1,145 @@
+/** The ladder, in order. Each rung stands on every rung below it. */
+export const MATURITY_LADDER = ["empty", "partial", "documented", "sourced", "vouched"];
+/**
+ * How far a service's documentation has got. Derived from artifact PRESENCE and
+ * provenance state only — the data an enumeration already holds — never from
+ * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the
+ * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of
+ * thirty climbs this ladder exactly as fast as a thorough one, which is why no
+ * rung is called "adopted".
+ *
+ *   empty       services/<id>/ exists, no artifact is in it
+ *   partial     some artifacts, but not the required set
+ *   documented  the artifacts the adopt brief marks required are present
+ *   sourced     the living spec declares `sources` — something ties it to code
+ *   vouched     status: verified with a sources_digest behind it — a person
+ *               stamped it. `verified` with no digest is a claim with nothing
+ *               behind it and stays below this rung.
+ *
+ * `openapi.yaml` is required ONLY where an API is expected. The rung used to
+ * demand it of everything, which permanently pinned every worker, cron and
+ * consumer in the fleet at `partial` — services that are fully documented and
+ * vouched for, reported as unfinished forever, leaving the rollup permanently
+ * below its true documentation state. The evidence is the same one
+ * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be
+ * green in one command and unfinished in the other.
+ */
+export function serviceMaturity(v) {
+    const s = v.entry;
+    if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0)
+        return "empty";
+    if (!(s.has.model && s.has.spec && (!v.apiExpected || s.has.openapi)))
+        return "partial";
+    if (!s.sources.declared)
+        return "documented";
+    if (!(s.status === "verified" && s.sources.stamped))
+        return "sourced";
+    return "vouched";
+}
+/**
+ * What stands between this service and `vouched`, named as the thing to go and
+ * do. One rung's worth at a time: telling somebody at `empty` that they also
+ * need a vouch is noise, and the vouch is not even possible yet.
+ */
+export function maturityGaps(v) {
+    const s = v.entry;
+    const files = [
+        ...(s.has.model ? [] : ["model.likec4"]),
+        ...(s.has.spec ? [] : ["spec.md"]),
+        ...(v.apiExpected && !s.has.openapi ? ["openapi.yaml"] : []),
+    ];
+    if (files.length > 0)
+        return files;
+    if (!s.sources.declared)
+        return ["sources: in the spec.md frontmatter"];
+    if (!(s.status === "verified" && s.sources.stamped))
+        return [`\`loam vouch --service ${s.id}\``];
+    return [];
+}
+/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */
+export function maturityRollup(graded) {
+    const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0]));
+    for (const v of graded)
+        out[v.maturity] += 1;
+    return out;
+}
+/* ------------------------------------------------------------------ */
+/* What the fleet map proves about one service                         */
+/* ------------------------------------------------------------------ */
+/**
+ * C4 kinds that model people, and the tag marking an element as somebody
+ * else's system. A person is never a service directory, and `#external` is
+ * undocumented on purpose — every census and exemption over the fleet map
+ * asks both questions.
+ *
+ * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,
+ * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.
+ * Their real home is `core/c4/likec4.ts` beside the model they describe, but
+ * that file sits against the 300-line limit and its package holds five files
+ * — so the trio lives here, beside `landscapeEvidence`, which reads the same
+ * map for the same per-service questions.
+ *
+ * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,
+ * where it was declared beside its one reader. It moved for the rule above the
+ * others came for: `fleet/kind-tags.ts` needs to know which tag names loam
+ * grades on, and reaching into fleet-shape.ts for a five-character constant
+ * would import a module that reads permissions, capabilities and every
+ * service's requirements to get it. The two tags loam gives meaning to belong
+ * in one place anyway — that list IS what the kind-tag check is about.
+ */
+export const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+export const EXTERNAL_TAG = "external";
+/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */
+export const PLATFORM_TAG = "platform";
+/**
+ * The tags loam GRADES on, as opposed to the ones it merely carries.
+ *
+ * A tag in this list changes what loam concludes about a fleet: `#external`
+ * exempts an element from the landscape↔services reconciliation entirely, and
+ * `#platform` silences the hub warning. Every other tag on an element is the
+ * author's own vocabulary and loam does not read it.
+ *
+ * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND
+ * — `specification { element softwareSystem { #external } }` — and LikeC4
+ * applies it to every element of that kind. A kind-wide declaration of a tag on
+ * this list switches loam's grading off for the whole fleet at once, which is
+ * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare
+ * kind-wide, so the check must ask exactly this question and no broader one.
+ */
+export const GRADED_TAGS = [EXTERNAL_TAG, PLATFORM_TAG];
+/**
+ * The fleet map's evidence about one service: the edges into and out of it,
+ * whether the map draws it at all, and whether an API is expected of it.
+ *
+ * One spelling, because it had grown three. `explore`'s describe and the
+ * context pack's living slice partitioned the same relationships with the
+ * same positive-evidence rule line for line — an inbound edge carrying an
+ * operation proves somebody calls the service; a landscape that is absent or
+ * does not parse proves NOTHING about who calls it, so the contract is still
+ * owed — and a rule spelled twice is how the same service grades `partial` in
+ * one command and `documented` in another. `list`'s serviceViews
+ * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —
+ * a single `called` set for every service, not a partition per service —
+ * so that spelling deliberately stays there, cross-referenced from both
+ * sides: calling this per service inside a fleet loop would re-walk the
+ * whole relationship list once per service.
+ */
+export function landscapeEvidence(req) {
+    const { id, parses, relationships, svcOf } = req;
+    const inbound = [];
+    const outbound = [];
+    for (const r of relationships) {
+        const edge = { op: r.op ?? null, title: r.title ?? null };
+        if (svcOf(r.target) === id)
+            inbound.push({ service: svcOf(r.source), ...edge });
+        else if (svcOf(r.source) === id)
+            outbound.push({ service: svcOf(r.target), ...edge });
+    }
+    return {
+        inbound,
+        outbound,
+        modelled: req.elementIds.some((e) => svcOf(e) === id),
+        apiExpected: !parses || inbound.some((e) => e.op !== null),
+    };
+}
+//# sourceMappingURL=maturity.js.map

package/dist/core/vocabulary/maturity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maturity.js","sourceRoot":"","sources":["../../../src/core/vocabulary/maturity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption-maturity ladder: one monotone word for how far a service's\n * documentation has got, and what stands between it and the next rung.\n *\n * This lived inside `commands/list.ts` while `list` was the only caller. It\n * moved here when `explore` needed the same answer, because the alternative is\n * the failure `core/kernel/ids/service.ts` already records for the service-id grammar: a\n * second, subtly different copy, so two commands grade the same directory\n * differently and nobody can tell which one is lying. The rung is a fleet dial\n * — `list` prints it per service and in a rollup, `explore` prints it for a\n * service somebody is about to build against — and a dial with two readings is\n * not a dial.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\n\n/** The ladder, in order. Each rung stands on every rung below it. */\nexport const MATURITY_LADDER = [\"empty\", \"partial\", \"documented\", \"sourced\", \"vouched\"] as const;\nexport type Maturity = (typeof MATURITY_LADDER)[number];\n\n/**\n * A service entry plus the two facts the directory enumeration cannot know on\n * its own. Both change what a rung MEANS, and both are fleet-level: they need\n * the landscape, not `services/<id>/`.\n */\nexport interface MaturityInput {\n  entry: ServiceEntry;\n  /** `arch.spec.md` — the architecture-obligations axis, absent from ServiceEntry.has. */\n  archSpec: boolean;\n  /**\n   * Does anything in the fleet call an operation on this service? True unless\n   * the landscape PROVES otherwise, exactly as `validate`'s no-openapi grace\n   * reads it: a missing or unparseable landscape proves nothing.\n   */\n  apiExpected: boolean;\n}\n\n/**\n * How far a service's documentation has got. Derived from artifact PRESENCE and\n * provenance state only — the data an enumeration already holds — never from\n * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the\n * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of\n * thirty climbs this ladder exactly as fast as a thorough one, which is why no\n * rung is called \"adopted\".\n *\n *   empty       services/<id>/ exists, no artifact is in it\n *   partial     some artifacts, but not the required set\n *   documented  the artifacts the adopt brief marks required are present\n *   sourced     the living spec declares `sources` — something ties it to code\n *   vouched     status: verified with a sources_digest behind it — a person\n *               stamped it. `verified` with no digest is a claim with nothing\n *               behind it and stays below this rung.\n *\n * `openapi.yaml` is required ONLY where an API is expected. The rung used to\n * demand it of everything, which permanently pinned every worker, cron and\n * consumer in the fleet at `partial` — services that are fully documented and\n * vouched for, reported as unfinished forever, leaving the rollup permanently\n * below its true documentation state. The evidence is the same one\n * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be\n * green in one command and unfinished in the other.\n */\nexport function serviceMaturity(v: MaturityInput): Maturity {\n  const s = v.entry;\n  if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0) return \"empty\";\n  if (!(s.has.model && s.has.spec && (!v.apiExpected || s.has.openapi))) return \"partial\";\n  if (!s.sources.declared) return \"documented\";\n  if (!(s.status === \"verified\" && s.sources.stamped)) return \"sourced\";\n  return \"vouched\";\n}\n\n/**\n * What stands between this service and `vouched`, named as the thing to go and\n * do. One rung's worth at a time: telling somebody at `empty` that they also\n * need a vouch is noise, and the vouch is not even possible yet.\n */\nexport function maturityGaps(v: MaturityInput): string[] {\n  const s = v.entry;\n  const files = [\n    ...(s.has.model ? [] : [\"model.likec4\"]),\n    ...(s.has.spec ? [] : [\"spec.md\"]),\n    ...(v.apiExpected && !s.has.openapi ? [\"openapi.yaml\"] : []),\n  ];\n  if (files.length > 0) return files;\n  if (!s.sources.declared) return [\"sources: in the spec.md frontmatter\"];\n  if (!(s.status === \"verified\" && s.sources.stamped)) return [`\\`loam vouch --service ${s.id}\\``];\n  return [];\n}\n\n/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */\nexport function maturityRollup(graded: readonly { maturity: Maturity }[]): Record<Maturity, number> {\n  const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0])) as Record<Maturity, number>;\n  for (const v of graded) out[v.maturity] += 1;\n  return out;\n}\n\n/* ------------------------------------------------------------------ */\n/* What the fleet map proves about one service                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * C4 kinds that model people, and the tag marking an element as somebody\n * else's system. A person is never a service directory, and `#external` is\n * undocumented on purpose — every census and exemption over the fleet map\n * asks both questions.\n *\n * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,\n * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.\n * Their real home is `core/c4/likec4.ts` beside the model they describe, but\n * that file sits against the 300-line limit and its package holds five files\n * — so the trio lives here, beside `landscapeEvidence`, which reads the same\n * map for the same per-service questions.\n *\n * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,\n * where it was declared beside its one reader. It moved for the rule above the\n * others came for: `fleet/kind-tags.ts` needs to know which tag names loam\n * grades on, and reaching into fleet-shape.ts for a five-character constant\n * would import a module that reads permissions, capabilities and every\n * service's requirements to get it. The two tags loam gives meaning to belong\n * in one place anyway — that list IS what the kind-tag check is about.\n */\nexport const ACTOR_KINDS = new Set([\"person\", \"actor\", \"user\"]);\nexport const EXTERNAL_TAG = \"external\";\n/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */\nexport const PLATFORM_TAG = \"platform\";\n\n/**\n * The tags loam GRADES on, as opposed to the ones it merely carries.\n *\n * A tag in this list changes what loam concludes about a fleet: `#external`\n * exempts an element from the landscape↔services reconciliation entirely, and\n * `#platform` silences the hub warning. Every other tag on an element is the\n * author's own vocabulary and loam does not read it.\n *\n * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND\n * — `specification { element softwareSystem { #external } }` — and LikeC4\n * applies it to every element of that kind. A kind-wide declaration of a tag on\n * this list switches loam's grading off for the whole fleet at once, which is\n * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare\n * kind-wide, so the check must ask exactly this question and no broader one.\n */\nexport const GRADED_TAGS: readonly string[] = [EXTERNAL_TAG, PLATFORM_TAG];\n\n/** One end of a call the fleet map draws, as every per-service view spells it. */\nexport interface LandscapeEdge {\n  service: string;\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * The slice of a parsed relationship the partition reads. Structural on\n * purpose — the smallest parameter type the derivation needs — so this module\n * stays a leaf: `core/c4/likec4.ts`'s `Rel` satisfies it without an import\n * edge from the vocabulary package into the parser.\n */\nexport interface EdgeSource {\n  source: string;\n  target: string;\n  op?: string;\n  title?: string;\n}\n\nexport interface LandscapeEvidenceRequest {\n  /** The service being asked about. */\n  id: string;\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  /** The parsed relationships; empty when the landscape is absent or unparseable. */\n  relationships: readonly EdgeSource[];\n  /** Every element id in the map, for the `modelled` probe. */\n  elementIds: readonly string[];\n  /** The shared resolver (`core/c4/resolve/service.ts` `serviceResolver`), widened to plain strings. */\n  svcOf: (id: string) => string;\n}\n\nexport interface LandscapeEvidence {\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Whether anything in the fleet map resolves to this service. */\n  modelled: boolean;\n  /** The `apiExpected` input the ladder above consumes. */\n  apiExpected: boolean;\n}\n\n/**\n * The fleet map's evidence about one service: the edges into and out of it,\n * whether the map draws it at all, and whether an API is expected of it.\n *\n * One spelling, because it had grown three. `explore`'s describe and the\n * context pack's living slice partitioned the same relationships with the\n * same positive-evidence rule line for line — an inbound edge carrying an\n * operation proves somebody calls the service; a landscape that is absent or\n * does not parse proves NOTHING about who calls it, so the contract is still\n * owed — and a rule spelled twice is how the same service grades `partial` in\n * one command and `documented` in another. `list`'s serviceViews\n * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —\n * a single `called` set for every service, not a partition per service —\n * so that spelling deliberately stays there, cross-referenced from both\n * sides: calling this per service inside a fleet loop would re-walk the\n * whole relationship list once per service.\n */\nexport function landscapeEvidence(req: LandscapeEvidenceRequest): LandscapeEvidence {\n  const { id, parses, relationships, svcOf } = req;\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of relationships) {\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === id) inbound.push({ service: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === id) outbound.push({ service: svcOf(r.target), ...edge });\n  }\n  return {\n    inbound,\n    outbound,\n    modelled: req.elementIds.some((e) => svcOf(e) === id),\n    apiExpected: !parses || inbound.some((e) => e.op !== null),\n  };\n}\n"]}

package/dist/core/{report.js → vocabulary/report.js}

@@ -26,7 +26,20 @@ export function reportValid(targets) {
 export function countSeverity(targets, severity) {
     return targets.reduce((n, t) => n + t.findings.filter((f) => f.severity === severity).length, 0);
 }
-export function findingJson(f) {
+/**
+ * DISTINCT subjects carrying a finding with `code`, across the whole report.
+ *
+ * By SUBJECT, not by finding, and that is the rule every rollup derived from
+ * findings must share: one service can raise the same code from two documents
+ * — each document has its own list and its own answer — but it is one service,
+ * and a count of findings sends the reader looking for services that do not
+ * exist. A finding that names no subject is about its target, so the target id
+ * is the fallback key.
+ */
+export function subjectsWith(targets, code) {
+    return new Set(targets.flatMap((t) => t.findings.filter((f) => f.code === code).map((f) => f.subject ?? t.id))).size;
+}
+export function findingJson(f, fallback) {
     return {
         severity: f.severity,
         code: f.code,
@@ -34,14 +47,29 @@ export function findingJson(f) {
         ...(f.gates === undefined ? {} : { gates: f.gates }),
         message: f.message,
         details: f.details ?? [],
+        locations: f.locations ?? (fallback === undefined ? [] : [fallback]),
+    };
+}
+function targetScope(t) {
+    const path = t.path ??
+        (t.kind === "service"
+            ? `services/${t.id}`
+            : t.kind === "feature"
+                ? "features"
+                : "architecture/landscape.likec4");
+    return {
+        path,
+        role: t.kind === "landscape" ? "primary" : "scope",
+        ...(t.kind === "feature" && t.path === undefined ? { pointer: t.id } : {}),
     };
 }
 export function targetJson(t) {
     return {
         kind: t.kind,
         id: t.id,
+        ...(t.path === undefined ? {} : { path: t.path }),
         valid: targetValid(t),
-        findings: t.findings.map(findingJson),
+        findings: t.findings.map((finding) => findingJson(finding, targetScope(t))),
     };
 }
 //# sourceMappingURL=report.js.map

package/dist/core/vocabulary/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/vocabulary/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The validation report — what `loam validate` produces before anything is\n * printed.\n *\n * Checks build findings; renderers turn them into a human view or into the JSON\n * contract. Keeping the two apart is what makes `--all` and `--json` possible\n * without a second implementation of every check, and it is why a finding\n * carries a stable `code`: prose is for people, codes are for callers.\n */\n\nexport type Severity = \"ok\" | \"warn\" | \"error\";\n\n/**\n * The glyph each severity is printed with. Five sites had written it out\n * themselves — four as a two-armed ternary that spelled `error` and let\n * everything else fall to ⚠ — and a reader who learns the marks from one\n * command's output has to be able to read them in the next. It lives beside\n * `Severity` because it is a fact about the union, not about any one renderer;\n * `TextHint.marker` above already describes it as \"the ✓/⚠/✗ marker\".\n */\nexport const SEVERITY_MARK: Record<Severity, string> = { ok: \"✓\", warn: \"⚠\", error: \"✗\" };\n\n/** How the text renderer should lay a finding out. The JSON contract ignores this. */\nexport interface TextHint {\n  /** Leading spaces. Default 0. */\n  indent?: number;\n  /** Print the ✓/⚠/✗ marker. Default true. */\n  marker?: boolean;\n  /** Block header printed once, before the first finding that carries it. */\n  header?: string;\n  /** Prefix for each detail line (e.g. \"- \" for a list of names). */\n  detailPrefix?: string;\n}\n\nexport interface FindingLocation {\n  /** Portable path relative to the docs repo whenever the finding is about one. */\n  path: string;\n  /** `primary` is exact; `scope` is the smallest directory the check can prove. */\n  role: \"primary\" | \"related\" | \"scope\";\n  line?: number;\n  column?: number;\n  /** A stable structural address when a line is not available. */\n  pointer?: string;\n}\n\nexport interface Finding {\n  severity: Severity;\n  /** Stable machine identifier — prose may change, this may not. */\n  code: string;\n  message: string;\n  /**\n   * What the finding is about, when that is narrower than the target: the\n   * service a feature's per-service check ran on, say. Without it a caller\n   * would have to read the service name back out of the message.\n   */\n  subject?: string;\n  details?: string[];\n  locations?: FindingLocation[];\n  /**\n   * Coherence findings only: whether `loam archive` refuses on this issue\n   * without `--approve` (issue.ts explains why severity alone cannot say).\n   * Absent on findings that never face the archive gate.\n   */\n  gates?: boolean;\n  text?: TextHint;\n}\n\nexport interface TargetReport {\n  /**\n   * What was validated. `landscape` is the fleet itself — the checks that need\n   * every service and every element in view at once, so they belong to no single\n   * service and only run under `--all`.\n   */\n  kind: \"service\" | \"feature\" | \"landscape\";\n  id: string;\n  /** The exact repo-relative scope this target was read from. */\n  path?: string;\n  findings: Finding[];\n}\n\n/** A target is valid when nothing in it is an error. Warnings never gate. */\nexport function targetValid(target: TargetReport): boolean {\n  return !target.findings.some((f) => f.severity === \"error\");\n}\n\nexport function reportValid(targets: TargetReport[]): boolean {\n  return targets.every(targetValid);\n}\n\nexport function countSeverity(targets: TargetReport[], severity: Severity): number {\n  return targets.reduce((n, t) => n + t.findings.filter((f) => f.severity === severity).length, 0);\n}\n\n/**\n * DISTINCT subjects carrying a finding with `code`, across the whole report.\n *\n * By SUBJECT, not by finding, and that is the rule every rollup derived from\n * findings must share: one service can raise the same code from two documents\n * — each document has its own list and its own answer — but it is one service,\n * and a count of findings sends the reader looking for services that do not\n * exist. A finding that names no subject is about its target, so the target id\n * is the fallback key.\n */\nexport function subjectsWith(targets: TargetReport[], code: string): number {\n  return new Set(\n    targets.flatMap((t) =>\n      t.findings.filter((f) => f.code === code).map((f) => f.subject ?? t.id),\n    ),\n  ).size;\n}\n\nexport function findingJson(f: Finding, fallback?: FindingLocation): Record<string, unknown> {\n  return {\n    severity: f.severity,\n    code: f.code,\n    ...(f.subject === undefined ? {} : { subject: f.subject }),\n    ...(f.gates === undefined ? {} : { gates: f.gates }),\n    message: f.message,\n    details: f.details ?? [],\n    locations: f.locations ?? (fallback === undefined ? [] : [fallback]),\n  };\n}\n\nfunction targetScope(t: TargetReport): FindingLocation {\n  const path =\n    t.path ??\n    (t.kind === \"service\"\n      ? `services/${t.id}`\n      : t.kind === \"feature\"\n        ? \"features\"\n        : \"architecture/landscape.likec4\");\n  return {\n    path,\n    role: t.kind === \"landscape\" ? \"primary\" : \"scope\",\n    ...(t.kind === \"feature\" && t.path === undefined ? { pointer: t.id } : {}),\n  };\n}\n\nexport function targetJson(t: TargetReport): Record<string, unknown> {\n  return {\n    kind: t.kind,\n    id: t.id,\n    ...(t.path === undefined ? {} : { path: t.path }),\n    valid: targetValid(t),\n    findings: t.findings.map((finding) => findingJson(finding, targetScope(t))),\n  };\n}\n"]}