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

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,
     };
 }

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

@@ -40,6 +40,13 @@ 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;
@@ -54,6 +61,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. */
@@ -73,8 +82,9 @@ export function maturityRollup(graded) {
  * 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

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, 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`,\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\"]);\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"]}
+{"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 *\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    ...(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/examples/README.md

@@ -18,6 +18,7 @@ loam archive FEAT-112 --dry-run    # an operation being retired, writing nothing
 loam verify FEAT-088               # a shipped feature's done-check: attested
 loam verify FEAT-120               # …and its pair, the same check: verified
 loam dependencies                  # the active-feature graph
+loam list suites                   # which services each test suite needs up
 ```
 
 Working on loam itself and running from source, use `npx tsx ../../src/cli.ts <args>` in place of
@@ -58,6 +59,18 @@ GROUP and earns no finding. Each requirement in both files is a promise a custom
 names no service, and carries a `Requirement-ID:` — required here, unlike in a service spec, because
 these documents outlive every service that realizes them.
 
+**One journey in two suites.** The same use case also carries `#suite-smoke` and
+`#suite-notifications`, both declared in the landscape's `specification` block, so `loam list
+suites` has a real answer: each suite needs `checkout-web`, `order-service` and
+`notification-service` up — the union of the journey's participants, resolved through the same
+element→service join the step grades use (notification-service is found through its filing under
+`platform/`, because the answer is ids, never paths). Two participants resolve to no service and are
+NAMED rather than dropped: `customer`, who drives the flow, and `kafka.orderEvents`, which is
+`#external` through its `topic` kind and wants a double on the test stand. One journey in both
+suites is the point of the tag: a directory could file it in only one. The suite tags change
+nothing `validate` says here — the view was already graded through its `#cap-` tag — but on a view
+carrying ONLY `#suite-` tags they are the opt-in, and its hops are graded like any other use case's.
+
 **Two glossary terms**, `glossary/order.md` and the nested `glossary/payments/authorization.md`,
 each cited from the capability documents that use the word. This is the axis's whole mechanism in
 two files: the citation is an ordinary markdown link, so `loam validate` resolves it like any other
@@ -94,8 +107,10 @@ for.
 - **`features/archive/FEAT-088-refunds/`** — shipped, and **`attested`**. It was merged by the real
   `loam archive`, so its `.loam-before/` snapshot holds the exact bytes the merge overwrote and
   `loam unarchive FEAT-088` would put them back. Its `verification.yaml` is the done-check written
-  down: every claim is confirmed, but the scenario claims rest on an agent's word instead of a
-  digest-matched test run. loam does not pretend those are the same thing.
+  down — recorded all at once, so it is the one file (a feature recorded per service carries one
+  `verification/<svc>.yaml` per attesting service instead): every claim is confirmed, but the
+  scenario claims rest on an agent's word instead of a digest-matched test run. loam does not
+  pretend those are the same thing.
 - **`features/archive/FEAT-120-refund-notification/`** — shipped, and **`verified`**. The sequel
   FEAT-088 left open: the money went back and nobody told the customer. It publishes
   `payment.PaymentRefunded` from payment-service and has notification-service turn it into the
@@ -111,10 +126,10 @@ for.
   with its own requirements, architecture requirements and contract, a C4 delta that splices a
   nested element into the living landscape, a `MODIFIED` requirement that **renames its heading**
   while keeping its `Requirement-ID` — loam's rename mechanism — and an **event-contract delta**
-  (`specs/payment-service/asyncapi.yaml`): a complete AsyncAPI 3.0 document restating
-  payment-service's living contract under `loam rebase`-written `x-loam-based-on` pins and adding
-  one new producer side, so the archive merges the new slots and leaves every pinned quote to the
-  living contract's own copy.
+  (`specs/payment-service/asyncapi.yaml`) that restates payment-service's living contract under
+  `loam rebase`-written `x-loam-based-on` pins and adds one new producer side, so the archive merges
+  the new slots and leaves every pinned quote to the living contract's own copy. The restatement is
+  there to demonstrate the pin; a real delta holds only the slots it adds, changes or removes.
 - **`features/FEAT-112-retire-order-v1/`** — in flight, and the smallest legal shape: no
   `delta.likec4` at all, because retiring an operation moves no boxes. It carries the two halves
   loam requires together for a removal — a `REMOVED` requirement and an `x-loam-remove: true` marker

package/examples/docs/architecture/landscape.likec4

@@ -85,6 +85,14 @@ specification {
   // cannot carry flattened to `-`. Declared here for the same reason — one
   // specification block serves the whole `architecture/` project.
   tag req-NOTIFY-ONCE
+  // The SUITES a flow runs with — `#suite-<name>` on the view, many-to-many, so
+  // the one journey below sits in both. Declared here, like every tag, so a
+  // mistyped suite is a parse error rather than a second, empty suite.
+  // `loam list suites` answers which services each one needs up: the union of
+  // its journeys' participants, plus the ones no services/ directory stands for
+  // (the customer who drives it, the #external topic in the middle).
+  tag suite-smoke
+  tag suite-notifications
   // An ARCHITECTURAL OBLIGATION, declared in architecture/obligations.yaml and
   // applied HERE, on the objects it holds for. The decision itself is
   // architecture/adrs/0001-transactional-outbox.md; this tag is the architect

package/examples/docs/architecture/usecases/order-notification.likec4

@@ -1,8 +1,10 @@
 // A fleet use case: the ordered hops that fulfil one business capability.
 //
 // This file is the whole shape of the axis. A `dynamic view` tagged
-// `#cap-<slug>` opts in to grading; an untagged one is somebody's hand-drawn
-// diagram and loam never says a word about it. The slug is the capability id
+// `#cap-<slug>` opts in to grading — so does one tagged only `#req-` or only
+// `#suite-<name>`, the suite a journey runs with (`loam list suites`); an
+// untagged one is somebody's hand-drawn diagram and loam never says a word
+// about it. The slug is the capability id
 // from architecture/capabilities.yaml with every `/` flattened to `-`, because
 // a LikeC4 tag name cannot carry a slash — `identity/tokens` would be
 // `#cap-identity-tokens`.
@@ -49,6 +51,8 @@ views {
   dynamic view uc_order_notification {
     #cap-order-notifications
     #req-NOTIFY-ONCE
+    #suite-smoke
+    #suite-notifications
     title 'Order notification'
     description 'A placed order reaches the customer as exactly one confirmation'
 

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-service/asyncapi.yaml

@@ -1,14 +1,17 @@
 # The event-contract delta: what FEAT-101 changes about the messages
 # payment-service puts on the bus.
 #
-# Like the openapi delta, this is a COMPLETE AsyncAPI 3.0 document, not a
-# patch: the living contract is restated around the one change. Identity is
-# the slot — `channels.<key>`, `operations.<key>`, `components.messages.<key>`
-# — and `x-loam-based-on` (written by `loam rebase`, never by hand) is what
-# lets the merge tell a restated slot from an edited one: a pinned QUOTE is
-# never a merge input, so a change that lands on the living contract after
-# this delta was written survives the archive. The new slots below carry no
-# pin — there is no living version for them to be based on.
+# A delta needs only the slots it adds, changes or removes — the merge leaves
+# every slot it does not declare exactly as the living contract has it. This
+# one restates the living contract around the change ON PURPOSE, to show what
+# a pin does with a restatement: identity is the slot — `channels.<key>`,
+# `operations.<key>`, `components.messages.<key>` — and `x-loam-based-on`
+# (written by `loam rebase`, never by hand) is what lets the merge tell a
+# restated slot from an edited one: a pinned QUOTE is never a merge input, so
+# a change that lands on the living contract after this delta was written
+# survives the archive. Outside a demonstration, leave quotes out: each one
+# is a pin, and a parallel feature's removal turns it into an error. The new
+# slots below carry no pin — there is no living version for them to be based on.
 asyncapi: 3.0.0
 info:
   title: payment-service events

package/examples/docs/features/FEAT-101-payment-splitting/specs/payment-split-service/openapi.yaml

@@ -1,12 +1,12 @@
 # API delta for FEAT-101 — payment-split-service (new) gains the split API.
 # On `loam archive` this folds into services/payment-split-service/openapi.yaml (living).
 #
-# A feature contract is a COMPLETE document, not a patch: the author restates the living
-# contract around the slot being changed, and the merge upserts every operation the document
-# spells. Both operations here are new, so neither carries an `x-loam-based-on` pin — there is
-# no living operation for a pin to be the digest of. On a service that already exists, every
-# quoted operation carries one, written by `loam rebase`, and an unpinned restatement is exactly
-# the shape that silently reverts whoever landed in between.
+# A feature contract holds only what the feature adds, changes or removes, and the merge upserts
+# every operation it spells. Both operations here are new, like the service, so neither carries
+# an `x-loam-based-on` pin — there is no living operation for a pin to be the digest of. On a
+# service that already exists, an operation the delta edits carries one, written by `loam
+# rebase`; one it would only quote belongs out of the delta, because a restatement is exactly
+# the shape that silently reverts whoever landed in between unless something pins it.
 openapi: 3.1.0
 info:
   title: payment-split-service

package/examples/docs/features/archive/FEAT-088-refunds/specs/payment-service/openapi.yaml

@@ -1,11 +1,12 @@
 # API delta for FEAT-088 — payment-service gains the refund operation.
 #
-# A feature contract is a COMPLETE document, not a patch, and the merge upserts every operation
-# it spells. This one adds an operation that does not exist living, so it carries no
-# `x-loam-based-on` pin: a pin is the digest of the LIVING operation, and there is none.
-# Restated operations are the ones that need pins — on a service with thirty operations a delta
-# quotes twenty-nine of them, and every unpinned quote is a candidate rollback of whoever landed
-# in between. `loam rebase` writes them.
+# A feature contract holds only what the feature adds, changes or removes. The merge walks only
+# the paths and methods this document spells, so authorizePayment and capturePayment, which it
+# leaves out, stay exactly as the living contract has them. refundPayment is new, so it carries
+# no `x-loam-based-on` pin: a pin is the digest of the LIVING operation, and there is none. Only
+# an operation the living contract already holds needs one (`loam rebase` writes it), and every
+# such operation quoted without being changed is one more pin and a collision waiting for a
+# parallel feature to edit or remove it.
 openapi: 3.1.0
 info:
   title: payment-service
@@ -51,10 +52,12 @@ components:
         refundedAt:
           type: string
           format: date-time
-    # Quoted from the living contract unchanged. The merge leaves a component the living
-    # document already holds IDENTICALLY alone; one it holds DIFFERENTLY is overwritten
-    # wholesale and reported as `openapi.component-modified`, because components carry no
-    # baseline pin the way operations do.
+    # Quoted from the living contract unchanged, and it did not need to be: the `$ref` to it
+    # above resolves into the living document, which already holds Problem. The merge leaves a
+    # component the living document holds IDENTICALLY alone; one it holds DIFFERENTLY is
+    # overwritten wholesale and reported as `openapi.component-modified`. Components carried no
+    # baseline pin when this feature archived; a quote like this one now needs one in the root
+    # `x-loam-baselines` record `loam rebase` writes — one more reason to leave it out.
     Problem:
       type: object
       required: [type, title, status]

package/examples/docs/services/order-service/asyncapi.yaml

@@ -5,8 +5,9 @@
 # `action: send|receive`, which is the exact analog of an `operationId` and the thing
 # that makes direction legible; 2.x spells the same thing as publish/subscribe under
 # a channel, where the two words are ambiguous about whose perspective they take. A
-# 2.x document declares no `operations` at all, so loam would read it as a contract
-# with no messages rather than as a mis-parsed one.
+# 2.x document declares no `operations` at all, so loam refuses it as one
+# `asyncapi.invalid` naming the version rather than reading it as a contract with no
+# messages (`asyncapi convert --target-version=3.0.0` upgrades it).
 #
 # The join is the message NAME, spelled three times and required to be identical: the
 # landscape edge's `metadata { publishes }` / `metadata { consumes }`, a requirement's

package/examples/docs/services/platform/notification-service/asyncapi.yaml

@@ -6,7 +6,8 @@
 # `action: send|receive`, which is what makes a message's direction legible;
 # 2.x spells the same thing as publish/subscribe under a channel, where the two
 # words are ambiguous about whose perspective they take — and a 2.x document
-# reads here as a contract with no messages at all.
+# is refused as one `asyncapi.invalid` naming its version, with nothing graded
+# against it (`asyncapi convert --target-version=3.0.0` upgrades it).
 #
 # The name is the spine: the landscape edge's `metadata { consumes }`, the
 # requirement's `Consumes:` line and `name` below are one name spelled three

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ybotok/loam",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.0-alpha.9",
   "description": "Architecture-first semantic integrity and change governance for evolving software systems: connect C4, requirements, contracts, and verification evidence.",
   "author": "spentsov",
   "repository": {