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

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

@@ -1 +1 @@
-{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../../src/core/verify/store/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The verification record's commit: staged beside the target, compared against\n * the byte pre-image the merge consumed, swapped in by one rename(2).\n *\n * The record used to go down as a plain `writeFile`, which cost three ways at\n * once: two `--record` runs read the same pre-image and the last writer\n * silently discarded the other service's attestation; a process killed\n * mid-write left the ONLY copy truncated, unreadable, and blocking every later\n * record; and an edit that landed between the read and the write was buried\n * under bytes computed from a document that no longer existed. The docs lock\n * (taken by `loam verify` before its authoritative read) closes the first;\n * this module closes the other two, and backstops the lock itself for a writer\n * that never took it.\n *\n * A sub-package of core/verify rather than a sixth file in it, and a consumer\n * of core/staging's primitives rather than a re-implementation: `stageWrites`\n * and `swapStaged` already do temp-beside-target, whole-content compare-and-set\n * and same-directory rename — vouch commits through exactly this shape.\n */\nimport { message, rollbackMessage, rollbackStaged, stageWrites, StagingRaceError, swapStaged } from \"../../staging/commit.js\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { type PlannedWrite, type StagedWrite } from \"../../staging/writes.js\";\nimport { renderVerification } from \"./render.js\";\nimport { verificationPath, type Verification } from \"../record.js\";\n\n/**\n * `record-raced` re-runs cleanly: the merge is recomputed over whatever the\n * other writer left. The other two are staging's own vocabulary, with staging's\n * meanings — `merge-failed` trusts the repo, `rollback-incomplete` does not.\n */\nexport type VerificationCommit =\n  | { ok: true; path: string }\n  | { ok: false; code: \"record-raced\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * `preImage` is the exact bytes the caller's merge was computed from, or null\n * when the record was absent at the authoritative read — in which case the\n * commit may only CREATE (link(2) refuses a file that appeared since), never\n * replace one it has not read.\n */\nexport async function commitVerification(\n  featureDir: string,\n  v: Verification,\n  preImage: Buffer | null,\n  docsDir: string,\n): Promise<VerificationCommit> {\n  const path = verificationPath(featureDir);\n  const display = repoPath(docsDir, path);\n  const write: PlannedWrite =\n    preImage === null ? { path, content: renderVerification(v), exclusive: true } : { path, content: renderVerification(v) };\n  // Staging touches the filesystem — a read-only feature directory, a full\n  // disk, a pre-image that will not read. None of that is a bug in loam, and\n  // letting it escape as `internal` sends the reader looking for one (archive\n  // draws the same line around its own `stageWrites`). Nothing was written.\n  let staged: StagedWrite[];\n  try {\n    staged = await stageWrites([write]);\n  } catch (err) {\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  // Joined by path, not by index — vouch's rule, for vouch's reason: one entry\n  // per planned write in order is true today and promised nowhere, and a\n  // compare-and-set over the wrong pair would vouch for bytes the merge never\n  // saw. A missing entry fails closed as a merge that never happened.\n  const s = staged.find((x) => x.write.path === path);\n  if (s === undefined) {\n    await rollbackStaged(staged);\n    return { ok: false, code: \"merge-failed\", message: `staging returned no entry for ${display} — nothing was recorded` };\n  }\n  // The compare the read promised: the file as staging found it must be the\n  // file the merge consumed. `swapStaged` re-checks against ITS read just\n  // before the rename, so together the two compares cover the whole window\n  // from the authoritative read to the swap.\n  const edited = preImage === null ? s.before !== null : s.before === null || !s.before.equals(preImage);\n  if (edited) {\n    await rollbackStaged(staged);\n    return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n  }\n  try {\n    await swapStaged(staged);\n  } catch (err) {\n    const failures = await rollbackStaged(staged);\n    if (failures.length > 0) {\n      return {\n        ok: false,\n        code: \"rollback-incomplete\",\n        message: rollbackMessage(err, failures, \"written\"),\n      };\n    }\n    // EEXIST is the exclusive create losing its race — same fact as the CAS\n    // refusal, discovered by link(2) instead of by the compare.\n    if (err instanceof StagingRaceError || (err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n    }\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  return { ok: true, path };\n}\n\nfunction racedMessage(display: string): string {\n  return (\n    `${display} changed while this record was being written — another writer or an editor landed between the read and the write. ` +\n    \"Nothing was written and their bytes are untouched. Re-run: the merge is recomputed over the record as it now stands.\"\n  );\n}\n"]}
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../../src/core/verify/store/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The verification record's commit: staged beside the target, compared against\n * the byte pre-image the merge consumed, swapped in by one rename(2) per file.\n * A write is one file, or two: a service's own `verification/<svc>.yaml`, and\n * — once nothing in it counts any more — the removal of the one-file record it\n * supersedes. Never another service's file: those are not this run's to touch.\n *\n * The record used to go down as a plain `writeFile`, which cost three ways at\n * once: two `--record` runs read the same pre-image and the last writer\n * silently discarded the other service's attestation; a process killed\n * mid-write left the ONLY copy truncated, unreadable, and blocking every later\n * record; and an edit that landed between the read and the write was buried\n * under bytes computed from a document that no longer existed. The docs lock\n * (taken by `loam verify` before its authoritative read) closes the first;\n * this module closes the other two, and backstops the lock itself for a writer\n * that never took it.\n *\n * A sub-package of core/verify rather than a sixth file in it, and a consumer\n * of core/staging's primitives rather than a re-implementation: `stageWrites`\n * and `swapStaged` already do temp-beside-target, whole-content compare-and-set\n * and same-directory rename — vouch commits through exactly this shape.\n */\nimport { message, rollbackMessage, rollbackStaged, stageWrites, StagingRaceError, swapStaged } from \"../../staging/commit.js\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { type PlannedWrite, type StagedWrite } from \"../../staging/writes.js\";\nimport { renderVerification } from \"./render.js\";\nimport { type Verification } from \"../record.js\";\n\n/**\n * `record-raced` re-runs cleanly: the merge is recomputed over whatever the\n * other writer left. The other two are staging's own vocabulary, with staging's\n * meanings — `merge-failed` trusts the repo, `rollback-incomplete` does not.\n */\nexport type VerificationCommit =\n  | { ok: true }\n  | { ok: false; code: \"record-raced\" | \"merge-failed\" | \"rollback-incomplete\"; message: string };\n\n/**\n * One file of the record this commit writes or removes.\n *\n * `preImage` is the exact bytes the caller's merge was computed from, or null\n * when the file was absent at the authoritative read — in which case the\n * commit may only CREATE it (link(2) refuses a file that appeared since), never\n * replace one it has not read. `record: null` removes the file, and only over\n * the bytes that read saw: a delete is a replace with nothing, and it is held\n * to the same compare.\n */\nexport interface RecordWrite {\n  path: string;\n  record: Verification | null;\n  preImage: Buffer | null;\n}\n\n/**\n * Writes land in the order given, so a caller puts what must survive a kill\n * FIRST: a service's own file before the one-file record it supersedes, so a\n * process killed between the two renames leaves a record that still reads\n * whole — the new file counted, the old one superseded by it — rather than one\n * with the old file gone and nothing in its place.\n */\nexport async function commitVerification(writes: RecordWrite[], docsDir: string): Promise<VerificationCommit> {\n  const planned = writes.map(\n    (w): PlannedWrite =>\n      w.record === null\n        ? { path: w.path, content: null }\n        : w.preImage === null\n          ? { path: w.path, content: renderVerification(w.record), exclusive: true }\n          : { path: w.path, content: renderVerification(w.record) },\n  );\n  // Staging touches the filesystem — a read-only feature directory, a full\n  // disk, a pre-image that will not read. None of that is a bug in loam, and\n  // letting it escape as `internal` sends the reader looking for one (archive\n  // draws the same line around its own `stageWrites`). Nothing was written.\n  let staged: StagedWrite[];\n  try {\n    staged = await stageWrites(planned);\n  } catch (err) {\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  for (const w of writes) {\n    const display = repoPath(docsDir, w.path);\n    // Joined by path, not by index — vouch's rule, for vouch's reason: one\n    // entry per planned write in order is true today and promised nowhere, and\n    // a compare-and-set over the wrong pair would vouch for bytes the merge\n    // never saw. A missing entry fails closed as a merge that never happened.\n    const s = staged.find((x) => x.write.path === w.path);\n    if (s === undefined) {\n      await rollbackStaged(staged);\n      return { ok: false, code: \"merge-failed\", message: `staging returned no entry for ${display} — nothing was recorded` };\n    }\n    // The compare the read promised: the file as staging found it must be the\n    // file the merge consumed. `swapStaged` re-checks against ITS read just\n    // before the rename, so together the two compares cover the whole window\n    // from the authoritative read to the swap.\n    const edited = w.preImage === null ? s.before !== null : s.before === null || !s.before.equals(w.preImage);\n    if (edited) {\n      await rollbackStaged(staged);\n      return { ok: false, code: \"record-raced\", message: racedMessage(display) };\n    }\n  }\n  try {\n    await swapStaged(staged);\n  } catch (err) {\n    const failures = await rollbackStaged(staged);\n    if (failures.length > 0) {\n      return {\n        ok: false,\n        code: \"rollback-incomplete\",\n        message: rollbackMessage(err, failures, \"written\"),\n      };\n    }\n    // EEXIST is the exclusive create losing its race — same fact as the CAS\n    // refusal, discovered by link(2) instead of by the compare.\n    if (err instanceof StagingRaceError || (err as NodeJS.ErrnoException).code === \"EEXIST\") {\n      const path = err instanceof StagingRaceError ? err.path : (writes.find((w) => w.preImage === null)?.path ?? writes[0]!.path);\n      return { ok: false, code: \"record-raced\", message: racedMessage(repoPath(docsDir, path)) };\n    }\n    return { ok: false, code: \"merge-failed\", message: `${message(err)} — nothing was recorded; the record is as the last writer left it` };\n  }\n  return { ok: true };\n}\n\nfunction racedMessage(display: string): string {\n  return (\n    `${display} changed while this record was being written — another writer or an editor landed between the read and the write. ` +\n    \"Nothing was written and their bytes are untouched. Re-run: the merge is recomputed over the record as it now stands.\"\n  );\n}\n"]}

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

@@ -6,8 +6,10 @@
  * 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.
+ * whose atomic swap that one performs. The reading went on to a package of its
+ * own, `../read/` (`file.ts` finds and grades the files, `shape.ts` says what a
+ * file must hold, `union.ts` adds the files up), and `../read/file.ts`'s header
+ * says where the render went.
  */
 import { stringify } from "yaml";
 import {} from "../record.js";
@@ -42,8 +44,10 @@ export function renderVerification(v) {
             ? [
                 "#",
                 "# 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.",
+                "# and file:line evidence to that repository's git commit. Each attesting service has a",
+                "# file of its own, verification/<svc>.yaml, and the record is the directory: claims",
+                "# another service owns are honestly unanswered in this file and answered in that",
+                "# service's own, and loam adds the files up when it reads them.",
                 "# `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.",

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

@@ -1 +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"]}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../../src/core/verify/store/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;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,wFAAwF;gBACxF,qFAAqF;gBACrF,kFAAkF;gBAClF,iEAAiE;gBACjE,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. The reading went on to a package of its\n * own, `../read/` (`file.ts` finds and grades the files, `shape.ts` says what a\n * file must hold, `union.ts` adds the files up), and `../read/file.ts`'s header\n * 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. Each attesting service has a\",\n          \"# file of its own, verification/<svc>.yaml, and the record is the directory: claims\",\n          \"# another service owns are honestly unanswered in this file and answered in that\",\n          \"# service's own, and loam adds the files up when it reads them.\",\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/issue.js

@@ -14,6 +14,7 @@ export function issueFinding(i) {
         gates: gatesArchive(i),
         ...(i.subject === undefined ? {} : { subject: i.subject }),
         ...(i.locations === undefined ? {} : { locations: i.locations }),
+        ...(i.details === undefined ? {} : { details: i.details }),
         message: i.message,
     };
 }
@@ -47,6 +48,9 @@ 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) {

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

@@ -1 +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,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  \"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  /* --- 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"]}
+{"version":3,"file":"issue.js","sourceRoot":"","sources":["../../../src/core/vocabulary/issue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+BH,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,GAAG,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1D,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  /**\n   * The evidence lines behind the message, when it has a list to show — the\n   * `details` every `Finding` already carries. `loam archive`'s overwrite\n   * warnings put the current consumers of the overwritten operation or\n   * message here, one per line, so the message stays one sentence however\n   * many there are.\n   */\n  details?: 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    ...(i.details === undefined ? {} : { details: i.details }),\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 — retires with a marker, or replaces at its method and path so the merge leaves it defined nowhere */\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 its service's living contract still defines, and the feature has no matching removal marker — owed only while there is one to retire: not for another service's id, not for one this delta already replaces at its address */\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 `channels`/`operations` slot, or a message by name, that this feature declares, the living contract no longer has, and an ARCHIVED feature's removal retired — or a message declared at a `components.messages` key an archived feature moved it away from — the merge cannot tell a quote of a retired or moved slot from an addition, so archiving would put it back. A warning that GATES; `--approve` re-adds it on purpose */\n  | \"asyncapi.slot-revived\"\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 and the merged contract would too, 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, or stops sending it, while the fleet would still name it after the merge — the consumer index's consumes-edges, other services' `Consumes:` lines and use-case hops while nothing would still send it after the merge (no service, no `#external` element publishing it), plus the provider's own `Publishes:` lines and `publishes` edges whoever else sends it (core/consumers/) */\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. Also: a tagged `consumes` edge whose message only an in-flight feature's delta sends */\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. Also: a delta `Consumes:` line whose message only an in-flight feature's delta sends — archive that one first */\n  | \"spec-event.message-pending\"\n  /** a delta's `Consumes:` line or tagged `consumes` edge names a message nothing would send after the merge — no service's contract as the merge leaves it, no #external element on the living map or in the delta; validate's living-side code, graded in feature scope so the archive cannot land the consumer it would report */\n  | \"spine.message-unproduced\"\n  /** a tagged edge's `publishes`/`consumes` key sits on an end that is infrastructure (a topic, queue or store, which neither publishes nor consumes) while a service sits at the other end — `publishes` binds the SOURCE and `consumes` the TARGET, so the key binds nothing and nothing grades it; an `#external` system at that end is an outside party and never raises it; validate's living-side code, graded in feature scope too. Warn: the drawing is legal, the link is lost */\n  | \"spine.message-unbound\"\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  /** the delta's OpenAPI spells an `info` key differently from the living contract — the merge carries paths and components and never `info`, so the living contract keeps its own and the delta's version or description is lost unless the author edits the living file in the same change */\n  | \"openapi.info-not-merged\"\n  /** the delta's AsyncAPI spells an `info` key differently from the living contract — the merge carries channels, operations and components and never `info`; the event-axis twin of `openapi.info-not-merged` */\n  | \"asyncapi.info-not-merged\"\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  /** an operation this feature spells, the living contract no longer has, and an ARCHIVED feature's removal marker retired — or spells at an address an archived feature moved it away from — the merge cannot tell a quote of a retired or moved operation from an addition, so archiving would put it back (beside its new address, for a move). A warning that GATES; `--approve` re-adds it on purpose */\n  | \"openapi.op-revived\"\n  /** the feature takes out of the contract an operation the fleet would still consume after the merge — the consumer index's edges of the `architecture/` project, other services' `Operations:` lines (not one naming its own service's operation of the same id), use-case hops, plus the provider's own requirements and self-edges (core/consumers/). Two shapes: a removal marker retires it, or the delta defines another operation at its method and path and the contract the merge would write defines it nowhere */\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. An ERROR, the severity `validate` gives the same directory, that does NOT gate: the merge is correct, the fleet it leaves is not yet whole */\n  | \"service.no-model\"\n  /** a health.yaml alert or SLI a living arch.spec.md requirement covers today that this feature's arch.spec.md delta would leave covered by nothing — validate's service-scope warning, predicted before the merge */\n  | \"health.uncovered\"\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 hop of a feature's own flow that no relationship on the map its merge would leave backs — validate's fleet-scope code, graded in feature scope against the merge preview, so the archive cannot land a flow `validate --all` then convicts */\n  | \"usecase.step-unbacked\"\n  /** a hop of a feature's own flow whose candidate relationships on the post-merge map disagree about the operation — validate's fleet-scope warning, graded in feature scope */\n  | \"usecase.step-contested\"\n  /** a cross-service hop of a feature's own flow backed by a relationship carrying no operation — validate's fleet-scope warning, graded in feature scope */\n  | \"usecase.step-unlinked\"\n  /** a `#cap-` tag on a feature's own flow that resolves to no capability the merge would leave declared — validate's fleet-scope code, graded in feature scope */\n  | \"usecase.capability-unresolved\"\n  /** a `#req-` tag on a feature's own flow that resolves to no requirement of the capability its `#cap-` tag names, as the merge would leave that document — or a flow with no resolving `#cap-` at all; validate's fleet-scope code, graded in feature scope. Also a LIVING flow — in `architecture/` or a service's own — whose resolving `#req-` tag this feature's merge breaks — by REMOVING the requirement it claims, or, beside a MODIFIED of it, by adding an id that flattens to the same tag: the fleet's error one archive early */\n  | \"usecase.requirement-unresolved\"\n  /** a LIVING flow — in `architecture/` or a service's own — whose `#req-` tag claims a requirement — a capability's, or that service's own — this feature MODIFIES: the tag still resolves after the archive (unless an id the feature adds flattens to it too — then it is `usecase.requirement-unresolved` instead) and nothing grades the drawing against the new wording, so the author reads the flow against the replacement. A warning that never gates */\n  | \"usecase.requirement-modified\"\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` and `services.likec4` (both generated, overwritten wholesale by `loam subsystem sync`, and parsed by nothing, so anything landing in either 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: three of the four 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

@@ -16,6 +16,14 @@ export const MATURITY_LADDER = ["empty", "partial", "documented", "sourced", "vo
  *               stamped it. `verified` with no digest is a claim with nothing
  *               behind it and stays below this rung.
  *
+ * A spec.md marked `adoption: partial` does not count toward `documented`.
+ * That marker is not a completeness grade — completeness stays unchecked, as
+ * above — but a PROVENANCE fact: `loam archive` wrote the file from one
+ * feature's slice into a service that existed and was never adopted, so the
+ * document says what that feature added and nothing about what the service
+ * already did. Counting it made one archive move a service from `partial` to
+ * `documented` with no adoption having happened.
+ *
  * `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
@@ -28,7 +36,7 @@ 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)))
+    if (!(s.has.model && s.has.spec && s.adoption === null && (!v.apiExpected || s.has.openapi)))
         return "partial";
     if (!s.sources.declared)
         return "documented";
@@ -40,12 +48,22 @@ export function serviceMaturity(v) {
  * 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.
+ *
+ * At the top rung, the one thing a vouch can still owe: a re-vouch, when a
+ * stamped document's words moved after the person read them
+ * (`ServiceEntry.contentStale`). The RUNG does not move — the stamp is real —
+ * but "nothing missing" over words nobody has read since is the false green
+ * this list exists to prevent, and `list --needs-work`, `explore` and the
+ * context pack all read their worklist from here.
  */
 export function maturityGaps(v) {
     const s = v.entry;
     const files = [
         ...(s.has.model ? [] : ["model.likec4"]),
         ...(s.has.spec ? [] : ["spec.md"]),
+        // Named as the step that discharges it, because the file it is about is
+        // already there: what is missing is the adoption, not the document.
+        ...(s.has.spec && s.adoption !== null ? [`\`loam adopt --service ${s.id}\` (spec.md is adoption: partial — one feature's slice)`] : []),
         ...(v.apiExpected && !s.has.openapi ? ["openapi.yaml"] : []),
     ];
     if (files.length > 0)
@@ -54,6 +72,8 @@ export function maturityGaps(v) {
         return ["sources: in the spec.md frontmatter"];
     if (!(s.status === "verified" && s.sources.stamped))
         return [`\`loam vouch --service ${s.id}\``];
+    if (s.contentStale.length > 0)
+        return [`re-vouch (${s.contentStale.join(", ")} changed since the vouch)`];
     return [];
 }
 /** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */
@@ -70,10 +90,12 @@ export function maturityRollup(graded) {
  * 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.
+ * asks both questions, and `INFRA_KINDS` below is the third they now ask
+ * beside them.
  *
- * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,
- * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.
+ * Extracted on the third strike: `commands/validate/checks/vocabulary.ts` (a
+ * module since deleted), `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
@@ -88,6 +110,45 @@ export function maturityRollup(graded) {
  * in one place anyway — that list IS what the kind-tag check is about.
  */
 export const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+/**
+ * C4 kinds that model INFRASTRUCTURE the fleet runs rather than a system a team
+ * adopts. A person is never a `services/<id>/`, and neither is a datastore: a
+ * Postgres, a Kafka topic or an S3 bucket has no spec.md to write, no OpenAPI to
+ * publish, no maturity rung to climb and nobody to adopt it.
+ *
+ * The third census category, beside `ACTOR_KINDS` and `EXTERNAL_TAG`, and it
+ * exists because the fleet had only two. A store the fleet OWNS and draws at
+ * fleet level was neither a person nor somebody else's system, so it earned
+ * `landscape.service-undocumented` ("bind it with `metadata { service }`, or tag
+ * it `#external`") — two remedies, neither of them true of it — and
+ * `gate.partner-undocumented` on every service that reads it. `examples/docs`
+ * and this repo's own suite both tagged an owned Redis `#external` purely to buy
+ * that silence, which is a map that lies about ownership to satisfy a check.
+ *
+ * The LIMITATION is `ACTOR_KINDS`' exactly, and is stated here so the next
+ * reader does not have to measure it: the hook is a kind NAME, compared
+ * case-insensitively, so a fleet whose specification spells its kind `postgres`,
+ * `store` or `datastore` is not covered. That is deliberate rather than
+ * unfinished — a tag (`#infrastructure`) can be added later as a SECOND spelling
+ * without moving anything, exactly as `#external` sits beside `ACTOR_KINDS`
+ * today. An element of one of these kinds that stands for a real
+ * `services/<id>/` — a bound `database`, a title naming a directory — is a
+ * service and every reader here must say so first; the kind is the fallback,
+ * never the override.
+ */
+export const INFRA_KINDS = new Set(["database", "queue", "topic", "cache", "bucket"]);
+/**
+ * The one element kind read as a datastore, compared case-insensitively — the
+ * subject of `landscape.datastore-shared`.
+ *
+ * It was a bare string declared twice, in `commands/validate/fleet/map/consumers.ts`
+ * and `commands/validate/fleet/map/attest.ts`, each with a comment pointing at
+ * the other. Two literals free to drift about what a store IS are exactly the
+ * failure the trio above was extracted to stop: the peer census and the nested
+ * census would have graded different fleets the day one of them learned a second
+ * spelling.
+ */
+export const DATASTORE_KIND = "database";
 export const EXTERNAL_TAG = "external";
 /** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */
 export const PLATFORM_TAG = "platform";
@@ -129,6 +190,16 @@ export function landscapeEvidence(req) {
     const inbound = [];
     const outbound = [];
     for (const r of relationships) {
+        // An edge whose BOTH endpoints resolve to this service is its own internal
+        // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own
+        // caller — `← <id> "reads"` in `loam context` (verification 2026-09-04) —
+        // and, through `apiExpected` below, told a service nobody calls that it owed
+        // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same
+        // reason. It still TOUCHES the service, which is why the brief's `touched`
+        // and `landscape.service-isolated` read the relationships rather than these
+        // two lists.
+        if (svcOf(r.source) === id && svcOf(r.target) === id)
+            continue;
         const edge = { op: r.op ?? null, title: r.title ?? null };
         if (svcOf(r.target) === id)
             inbound.push({ service: svcOf(r.source), ...edge });

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

@@ -1 +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"]}
+{"version":3,"file":"maturity.js","sourceRoot":"","sources":["../../../src/core/vocabulary/maturity.ts"],"names":[],"mappings":"AAeA,qEAAqE;AACrE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAoBjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe,CAAC,CAAgB;IAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACvF,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/G,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAC;IAC7C,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACtE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,CAAgB;IAC3C,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IAClB,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;QACxC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClC,wEAAwE;QACxE,oEAAoE;QACpE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,EAAE,yDAAyD,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvI,GAAG,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7D,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ;QAAE,OAAO,CAAC,qCAAqC,CAAC,CAAC;IACxE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACjG,IAAI,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC1G,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,MAAyC;IACtE,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAA6B,CAAC;IAC/F,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AACzC,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AACvC,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;AA4C3E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA6B;IAC7D,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC;IACjD,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,2EAA2E;QAC3E,6EAA6E;QAC7E,0EAA0E;QAC1E,6EAA6E;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,4EAA4E;QAC5E,aAAa;QACb,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QAC1D,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;aAC3E,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO;QACL,OAAO;QACP,QAAQ;QACR,QAAQ,EAAE,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACrD,WAAW,EAAE,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC;KAC3D,CAAC;AACJ,CAAC","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 * A spec.md marked `adoption: partial` does not count toward `documented`.\n * That marker is not a completeness grade — completeness stays unchecked, as\n * above — but a PROVENANCE fact: `loam archive` wrote the file from one\n * feature's slice into a service that existed and was never adopted, so the\n * document says what that feature added and nothing about what the service\n * already did. Counting it made one archive move a service from `partial` to\n * `documented` with no adoption having happened.\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 && s.adoption === null && (!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 *\n * At the top rung, the one thing a vouch can still owe: a re-vouch, when a\n * stamped document's words moved after the person read them\n * (`ServiceEntry.contentStale`). The RUNG does not move — the stamp is real —\n * but \"nothing missing\" over words nobody has read since is the false green\n * this list exists to prevent, and `list --needs-work`, `explore` and the\n * context pack all read their worklist from here.\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    // Named as the step that discharges it, because the file it is about is\n    // already there: what is missing is the adoption, not the document.\n    ...(s.has.spec && s.adoption !== null ? [`\\`loam adopt --service ${s.id}\\` (spec.md is adoption: partial — one feature's slice)`] : []),\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  if (s.contentStale.length > 0) return [`re-vouch (${s.contentStale.join(\", \")} changed since the vouch)`];\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, and `INFRA_KINDS` below is the third they now ask\n * beside them.\n *\n * Extracted on the third strike: `commands/validate/checks/vocabulary.ts` (a\n * module since deleted), `core/gate/partners.ts` and `core/verify/checklist.ts`\n * 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\"]);\n\n/**\n * C4 kinds that model INFRASTRUCTURE the fleet runs rather than a system a team\n * adopts. A person is never a `services/<id>/`, and neither is a datastore: a\n * Postgres, a Kafka topic or an S3 bucket has no spec.md to write, no OpenAPI to\n * publish, no maturity rung to climb and nobody to adopt it.\n *\n * The third census category, beside `ACTOR_KINDS` and `EXTERNAL_TAG`, and it\n * exists because the fleet had only two. A store the fleet OWNS and draws at\n * fleet level was neither a person nor somebody else's system, so it earned\n * `landscape.service-undocumented` (\"bind it with `metadata { service }`, or tag\n * it `#external`\") — two remedies, neither of them true of it — and\n * `gate.partner-undocumented` on every service that reads it. `examples/docs`\n * and this repo's own suite both tagged an owned Redis `#external` purely to buy\n * that silence, which is a map that lies about ownership to satisfy a check.\n *\n * The LIMITATION is `ACTOR_KINDS`' exactly, and is stated here so the next\n * reader does not have to measure it: the hook is a kind NAME, compared\n * case-insensitively, so a fleet whose specification spells its kind `postgres`,\n * `store` or `datastore` is not covered. That is deliberate rather than\n * unfinished — a tag (`#infrastructure`) can be added later as a SECOND spelling\n * without moving anything, exactly as `#external` sits beside `ACTOR_KINDS`\n * today. An element of one of these kinds that stands for a real\n * `services/<id>/` — a bound `database`, a title naming a directory — is a\n * service and every reader here must say so first; the kind is the fallback,\n * never the override.\n */\nexport const INFRA_KINDS = new Set([\"database\", \"queue\", \"topic\", \"cache\", \"bucket\"]);\n\n/**\n * The one element kind read as a datastore, compared case-insensitively — the\n * subject of `landscape.datastore-shared`.\n *\n * It was a bare string declared twice, in `commands/validate/fleet/map/consumers.ts`\n * and `commands/validate/fleet/map/attest.ts`, each with a comment pointing at\n * the other. Two literals free to drift about what a store IS are exactly the\n * failure the trio above was extracted to stop: the peer census and the nested\n * census would have graded different fleets the day one of them learned a second\n * spelling.\n */\nexport const DATASTORE_KIND = \"database\";\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    // An edge whose BOTH endpoints resolve to this service is its own internal\n    // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own\n    // caller — `← <id> \"reads\"` in `loam context` (verification 2026-09-04) —\n    // and, through `apiExpected` below, told a service nobody calls that it owed\n    // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same\n    // reason. It still TOUCHES the service, which is why the brief's `touched`\n    // and `landscape.service-isolated` read the relationships rather than these\n    // two lists.\n    if (svcOf(r.source) === id && svcOf(r.target) === id) continue;\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/vocabulary/report.js

@@ -13,9 +13,24 @@
  * everything else fall to ⚠ — and a reader who learns the marks from one
  * command's output has to be able to read them in the next. It lives beside
  * `Severity` because it is a fact about the union, not about any one renderer;
- * `TextHint.marker` above already describes it as "the ✓/⚠/✗ marker".
+ * `TextHint.marker` below is the switch that prints it, or a different mark.
  */
 export const SEVERITY_MARK = { ok: "✓", warn: "⚠", error: "✗" };
+/**
+ * The glyph for an `ok` finding whose check did NOT run here — printed in
+ * place of ✓, never in place of ⚠ or ✗.
+ *
+ * Not a fourth severity, on purpose: `sources.unverifiable-from-here` is `ok`
+ * because nothing is wrong with the docs, and a severity of its own would move
+ * the footer's counts, `--strict` and the frozen `--json` vocabulary for what
+ * is only a question of how the line reads. But ✓ is the one mark that says
+ * "checked, fine", and a person reading a docs-repo run saw a column of them
+ * beside the sentence "nothing here can resolve them" — a pass for a check
+ * that was skipped. Defined here beside SEVERITY_MARK for the same reason that
+ * table is: a reader who learns it from one command must be able to read it in
+ * the next.
+ */
+export const NOT_CHECKED_MARK = "○";
 /** A target is valid when nothing in it is an error. Warnings never gate. */
 export function targetValid(target) {
     return !target.findings.some((f) => f.severity === "error");

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

@@ -1 +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"]}
+{"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` below is the switch that prints it, or a different mark.\n */\nexport const SEVERITY_MARK: Record<Severity, string> = { ok: \"✓\", warn: \"⚠\", error: \"✗\" };\n\n/**\n * The glyph for an `ok` finding whose check did NOT run here — printed in\n * place of ✓, never in place of ⚠ or ✗.\n *\n * Not a fourth severity, on purpose: `sources.unverifiable-from-here` is `ok`\n * because nothing is wrong with the docs, and a severity of its own would move\n * the footer's counts, `--strict` and the frozen `--json` vocabulary for what\n * is only a question of how the line reads. But ✓ is the one mark that says\n * \"checked, fine\", and a person reading a docs-repo run saw a column of them\n * beside the sentence \"nothing here can resolve them\" — a pass for a check\n * that was skipped. Defined here beside SEVERITY_MARK for the same reason that\n * table is: a reader who learns it from one command must be able to read it in\n * the next.\n */\nexport const NOT_CHECKED_MARK = \"○\";\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  /**\n   * Which marker leads the line. Absent prints the severity's ✓/⚠/✗.\n   *\n   * `false` prints none, and only a line that is genuinely a sub-header may\n   * ask for it — `coherence.ok`, whose message carries its own ✓ under the\n   * feature it belongs to. An error or a warning that stands alone with no\n   * marker reads as prose between findings: `service.no-model` printed that\n   * way, and a run that exited 1 showed no ✗ anywhere.\n   *\n   * `\"not-checked\"` prints NOT_CHECKED_MARK in place of ✓ — see there.\n   */\n  marker?: false | \"not-checked\";\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   * Print this finding before every target's block on a fleet run, rather\n   * than inside its own target's. For a finding that says nothing below it\n   * can be trusted (`docs.commit-interrupted`): it has to be attached to SOME\n   * target, and the fleet report orders targets by kind, so without the hint\n   * it would print wherever its host target happened to land.\n   */\n  lead?: true;\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"]}