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

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

@@ -1 +1 @@
-{"version":3,"file":"glossary.js","sourceRoot":"","sources":["../../../../src/commands/validate/links/glossary.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `glossary.unlinked` — a defined term that no document outside the glossary\n * cites.\n *\n * The mirror of `permissions.unenforced` and `capability.unrealized`, and it\n * earns its place for their reason: a vocabulary is worth what cites it. A term\n * nobody links to is either a word the fleet never adopted or a definition left\n * behind by a rename — both are drift, and neither is visible from inside the\n * file. WARN, because the honest answer is often \"not written up yet\", and\n * because a glossary must be safe to start: a fleet that defines twenty terms\n * on a Monday and cites four of them is adopting the axis, not failing it.\n *\n * A TERM CITED ONLY BY OTHER TERMS IS STILL UNLINKED, and this is the judgement\n * that keeps the warning worth anything. A glossary is a network of definitions,\n * so `order-line` linking to `order` is normal and correct — and it proves\n * nothing about whether the FLEET uses either word. The same reasoning\n * `capability.requirement-inert-join` applies one axis over: a join written\n * inside the tree is not evidence about the world outside it. The intra-glossary\n * citations are listed in `details` rather than hidden, because they are the\n * first thing a reader will otherwise go looking for.\n *\n * ONE FINDING FOR THE WHOLE GLOSSARY when nothing cites anything, and one per\n * term otherwise. A fleet that has just created `glossary/` and written its\n * first eight definitions would otherwise get eight identical warnings saying\n * the same thing about the same afternoon's work.\n */\nimport { backlinkIndex } from \"../../../core/links/backlinks.js\";\nimport { readGlossary } from \"../../../core/glossary/tree.js\";\nimport { glossaryDir } from \"../../../core/repo/authored/paths.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport async function glossaryFindings(docsDir: DocsDir, fleet?: FleetContext): Promise<Finding[]> {\n  const root = glossaryDir(docsDir);\n  const glossary = await readGlossary(root);\n  // The directory's existence is the axis's opt-in, exactly as\n  // `architecture/capabilities.yaml` and `capabilities/` are the business\n  // axis's. A fleet without one pays a single `existsSync` and hears nothing —\n  // and the whole fleet-wide link walk below is never built.\n  if (!glossary.present || glossary.terms.length === 0) return [];\n\n  const index = await backlinkIndex(docsDir, fleet);\n  const inGlossary = (source: string): boolean => source.startsWith(`${repoPath(docsDir, root)}/`);\n  const unlinked = glossary.terms\n    .map((term) => ({ term, cited: index.linkersOf(term.path) }))\n    .map(({ term, cited }) => ({ term, outside: cited.filter((s) => !inGlossary(s)), within: cited.filter(inGlossary) }))\n    .filter(({ outside }) => outside.length === 0);\n  if (unlinked.length === 0) return [];\n\n  // The whole vocabulary uncited is one fact about one afternoon, not N facts.\n  if (unlinked.length === glossary.terms.length && glossary.terms.length > 1) {\n    return [\n      {\n        severity: \"warn\",\n        code: \"glossary.unlinked\",\n        message:\n          `glossary: none of the ${glossary.terms.length} defined term(s) is linked from any document outside glossary/. ` +\n          \"A term becomes checkable when a requirement, capability or intent cites it — \" +\n          \"`[Order](../../glossary/order.md)` — and until then the definitions are a document nothing joins to.\",\n        details: unlinked.map(({ term }) => term.id),\n      },\n    ];\n  }\n  return unlinked.map(({ term, within }) => ({\n    severity: \"warn\" as const,\n    code: \"glossary.unlinked\",\n    subject: term.id,\n    message:\n      `glossary/${term.id}.md is linked from no document outside glossary/` +\n      (within.length === 0\n        ? \" — either a word the fleet has not adopted, or a definition left behind by a rename.\"\n        : \", only from other terms — which says the glossary is consistent, not that the fleet uses the word.\") +\n      ` Cite it as \\`[${term.id}](<relative>/glossary/${term.id}.md)\\` from the requirement or capability that uses it, or delete the definition.`,\n    ...(within.length === 0 ? {} : { details: within }),\n  }));\n}\n"]}
+{"version":3,"file":"glossary.js","sourceRoot":"","sources":["../../../../src/commands/validate/links/glossary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAGlE,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAmB;IAC1E,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1C,6DAA6D;IAC7D,wEAAwE;IACxE,6EAA6E;IAC7E,2DAA2D;IAC3D,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEhE,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,CAAC,MAAc,EAAW,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACjG,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK;SAC5B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SAC5D,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;SACpH,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,6EAA6E;IAC7E,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,KAAK,CAAC,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,OAAO;YACL;gBACE,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,mBAAmB;gBACzB,OAAO,EACL,yBAAyB,QAAQ,CAAC,KAAK,CAAC,MAAM,kEAAkE;oBAChH,+EAA+E;oBAC/E,sGAAsG;gBACxG,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;aAC7C;SACF,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QACzC,QAAQ,EAAE,MAAe;QACzB,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EACL,YAAY,IAAI,CAAC,EAAE,kDAAkD;YACrE,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;gBAClB,CAAC,CAAC,sFAAsF;gBACxF,CAAC,CAAC,oGAAoG,CAAC;YACzG,kBAAkB,IAAI,CAAC,EAAE,yBAAyB,IAAI,CAAC,EAAE,mFAAmF;QAC9I,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;KACpD,CAAC,CAAC,CAAC;AACN,CAAC","sourcesContent":["/**\n * `glossary.unlinked` — a defined term that no document outside the glossary\n * cites.\n *\n * The mirror of `permissions.unenforced` and `capability.unrealized`, and it\n * earns its place for their reason: a vocabulary is worth what cites it. A term\n * nobody links to is either a word the fleet never adopted or a definition left\n * behind by a rename — both are drift, and neither is visible from inside the\n * file. WARN, because the honest answer is often \"not written up yet\", and\n * because a glossary must be safe to start: a fleet that defines twenty terms\n * on a Monday and cites four of them is adopting the axis, not failing it.\n *\n * A TERM CITED ONLY BY OTHER TERMS IS STILL UNLINKED, and this is the judgement\n * that keeps the warning worth anything. A glossary is a network of definitions,\n * so `order-line` linking to `order` is normal and correct — and it proves\n * nothing about whether the FLEET uses either word. The same reasoning\n * `capability.requirement-inert-join` applies one axis over: a join written\n * inside the tree is not evidence about the world outside it. The intra-glossary\n * citations are listed in `details` rather than hidden, because they are the\n * first thing a reader will otherwise go looking for.\n *\n * ONE FINDING FOR THE WHOLE GLOSSARY when nothing cites anything, and one per\n * term otherwise. A fleet that has just created `glossary/` and written its\n * first eight definitions would otherwise get eight identical warnings saying\n * the same thing about the same afternoon's work.\n */\nimport { backlinkIndex } from \"../../../core/links/backlinks.js\";\nimport { readGlossary } from \"../../../core/glossary/tree.js\";\nimport { glossaryDir } from \"../../../core/repo/authored/paths.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport async function glossaryFindings(docsDir: DocsDir, fleet: FleetContext): Promise<Finding[]> {\n  const root = glossaryDir(docsDir);\n  const glossary = await readGlossary(root);\n  // The directory's existence is the axis's opt-in, exactly as\n  // `architecture/capabilities.yaml` and `capabilities/` are the business\n  // axis's. A fleet without one pays a single `existsSync` and hears nothing —\n  // and the whole fleet-wide link walk below is never built.\n  if (!glossary.present || glossary.terms.length === 0) return [];\n\n  const index = await backlinkIndex(docsDir, fleet);\n  const inGlossary = (source: string): boolean => source.startsWith(`${repoPath(docsDir, root)}/`);\n  const unlinked = glossary.terms\n    .map((term) => ({ term, cited: index.linkersOf(term.path) }))\n    .map(({ term, cited }) => ({ term, outside: cited.filter((s) => !inGlossary(s)), within: cited.filter(inGlossary) }))\n    .filter(({ outside }) => outside.length === 0);\n  if (unlinked.length === 0) return [];\n\n  // The whole vocabulary uncited is one fact about one afternoon, not N facts.\n  if (unlinked.length === glossary.terms.length && glossary.terms.length > 1) {\n    return [\n      {\n        severity: \"warn\",\n        code: \"glossary.unlinked\",\n        message:\n          `glossary: none of the ${glossary.terms.length} defined term(s) is linked from any document outside glossary/. ` +\n          \"A term becomes checkable when a requirement, capability or intent cites it — \" +\n          \"`[Order](../../glossary/order.md)` — and until then the definitions are a document nothing joins to.\",\n        details: unlinked.map(({ term }) => term.id),\n      },\n    ];\n  }\n  return unlinked.map(({ term, within }) => ({\n    severity: \"warn\" as const,\n    code: \"glossary.unlinked\",\n    subject: term.id,\n    message:\n      `glossary/${term.id}.md is linked from no document outside glossary/` +\n      (within.length === 0\n        ? \" — either a word the fleet has not adopted, or a definition left behind by a rename.\"\n        : \", only from other terms — which says the glossary is consistent, not that the fleet uses the word.\") +\n      ` Cite it as \\`[${term.id}](<relative>/glossary/${term.id}.md)\\` from the requirement or capability that uses it, or delete the definition.`,\n    ...(within.length === 0 ? {} : { details: within }),\n  }));\n}\n"]}

package/dist/commands/validate/report.js

@@ -32,10 +32,11 @@ export function summary(targets) {
  * arch.spec.md both name `sources` raises two findings and is one service) is
  * `subjectsWith`'s, spelled once for every findings-derived rollup — the
  * fleet scorecard counts through the same function on the same code, so its
- * number and this one are structurally the same number. The code is a LITERAL
- * rather than checks/vocabulary.ts's UNVERIFIABLE constant because the
- * stable-code collector reads counting sites too, and it refuses a slot it
- * cannot read — the collector is also what convicts a typo here.
+ * number and this one are structurally the same number. The code is a LITERAL,
+ * as it is at the emission site (checks/sources.ts), rather than a shared
+ * constant, because the stable-code collector reads counting sites too, and it
+ * refuses a slot it cannot read — the collector is also what convicts a typo
+ * here.
  */
 export function unverifiableSubjects(targets) {
     return subjectsWith(targets, "sources.unverifiable-from-here");

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

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/validate/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Everything that happens to a `TargetReport` around the checks themselves:\n * how one is built when a target could not be read at all, how a finding's\n * evidence is capped, how the set is summed, and how it prints.\n *\n * A module rather than the tail of validate.ts because the rollup and the\n * renderer have to agree. The `--all` footer and the `--json` summary are the\n * same `summary()`, and the cap reaches both payloads from one place; a second\n * copy of either is how a footer starts printing a number its own findings\n * contradict.\n */\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listCodes } from \"../../core/explain/lookup.js\";\nimport {\n  countSeverity,\n  subjectsWith,\n  SEVERITY_MARK,\n  type Finding,\n  type TargetReport,\n} from \"../../core/vocabulary/report.js\";\nimport { EXPLAIN_FOOTER, plural } from \"../policy/format.js\";\nimport {\n  ADOPTION_AXES,\n  groupedWarnCodes,\n  type Adoption,\n  type AdoptionAxis,\n} from \"./fleet/scorecard/adoption.js\";\n\n/**\n * The rollup `--json` carries and the `--all` footer prints.\n *\n * Four named fields rather than a `Record<string, number>`: the keys ARE the\n * contract, and under an index signature every read of them was an assertion\n * (`s.errors!`) that tsc could not check — rename one and the compiler stayed\n * quiet while the footer printed `undefined errors`.\n */\nexport interface ValidateSummary {\n  services: number;\n  features: number;\n  errors: number;\n  warnings: number;\n}\n\nexport function summary(targets: TargetReport[]): ValidateSummary {\n  return {\n    services: targets.filter((t) => t.kind === \"service\").length,\n    features: targets.filter((t) => t.kind === \"feature\").length,\n    errors: countSeverity(targets, \"error\"),\n    warnings: countSeverity(targets, \"warn\"),\n  };\n}\n\n/**\n * How many services this run could not check, for the rollup line and the\n * `--json` payload.\n *\n * Counted off the findings rather than alongside them, so the rollup line\n * and the per-service findings can never disagree about how many services\n * this run could not check. The by-SUBJECT rule (a service whose spec.md and\n * arch.spec.md both name `sources` raises two findings and is one service) is\n * `subjectsWith`'s, spelled once for every findings-derived rollup — the\n * fleet scorecard counts through the same function on the same code, so its\n * number and this one are structurally the same number. The code is a LITERAL\n * rather than checks/vocabulary.ts's UNVERIFIABLE constant because the\n * stable-code collector reads counting sites too, and it refuses a slot it\n * cannot read — the collector is also what convicts a typo here.\n */\nexport function unverifiableSubjects(targets: TargetReport[]): number {\n  return subjectsWith(targets, \"sources.unverifiable-from-here\");\n}\n\n/**\n * How many `details` lines any one finding may print before the rest are\n * summarised away.\n *\n * A finding's details are evidence, not a log: LikeC4 reports one syntax error\n * as dozens of cascading diagnostics, and a fleet-sized repo multiplies that by\n * every target that mentions the file. The report is read by a person scrolling\n * a CI log and by an agent with a context window, and neither of them is helped\n * by the four-hundredth copy. The cap is applied to the JSON payload too, on\n * purpose: `--json` is the interface an agent pipes, and an unbounded array is\n * the same denial-of-attention there, just machine-readable.\n */\nconst DETAIL_LIMIT = 10;\n\n/** Truncate every finding's details, marking what was dropped so nothing looks complete when it is not. */\nexport function capDetails(t: TargetReport): TargetReport {\n  return {\n    ...t,\n    findings: t.findings.map((f) => {\n      const details = f.details ?? [];\n      if (details.length <= DETAIL_LIMIT) return f;\n      return {\n        ...f,\n        details: [...details.slice(0, DETAIL_LIMIT), `… (+${details.length - DETAIL_LIMIT} more)`],\n      };\n    }),\n  };\n}\n\n/**\n * One target's checks, with an IO exception turned into a finding ON that\n * target instead of aborting the run.\n *\n * A fleet gate that dies on the first unreadable file reports nothing about the\n * other ninety-nine services — one bad permission bit, one file that is a\n * dangling symlink, and CI's answer to \"how is the fleet\" becomes a stack\n * trace. The failure is real and it is an error, so the run still exits 1; what\n * changes is that everything else is still graded, and the finding names the\n * service and the path instead of arriving as the `internal` catch-all.\n */\nexport async function guarded(\n  target: { kind: \"service\" | \"feature\"; id: string },\n  run: () => Promise<TargetReport>,\n): Promise<TargetReport> {\n  try {\n    return await run();\n  } catch (err) {\n    // A docs repo that vanished mid-run is not one target's problem — it is the\n    // whole run's, and the action's own catch reports it.\n    if (err instanceof DocsRepoUnavailableError) throw err;\n    const path = (err as NodeJS.ErrnoException).path;\n    const reason = err instanceof Error ? err.message : String(err);\n    return {\n      kind: target.kind,\n      id: target.id,\n      findings: [\n        {\n          severity: \"error\",\n          code: target.kind === \"service\" ? \"service.unreadable\" : \"feature.unreadable\",\n          subject: target.id,\n          message:\n            `${target.id}: ${path === undefined ? \"an artifact\" : path} could not be read — ` +\n            `nothing about this ${target.kind} was checked. ${reason}`,\n        },\n      ],\n    };\n  }\n}\n\n/**\n * `target.ambiguous` — the positional named a service AND a feature. The tie is\n * still broken the way it always was (the feature wins), because changing which\n * one is picked would silently re-target every script that relies on it; what\n * is new is that the run says which reading it took and how to force the other.\n */\nexport function ambiguousTarget(arg: string, chosen: \"service\" | \"feature\"): Finding {\n  const other = chosen === \"feature\" ? \"service\" : \"feature\";\n  return {\n    severity: \"warn\",\n    code: \"target.ambiguous\",\n    subject: arg,\n    message:\n      `'${arg}' names both a service and a feature — validated as the ${chosen}. ` +\n      `Pass --${other} ${arg} for the other reading.`,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Text renderer                                                       */\n/* ------------------------------------------------------------------ */\n\n/** What `renderText` needs of the run beyond the graded targets themselves. */\nexport interface RenderOptions {\n  all: boolean;\n  errorsOnly: boolean;\n  /** The fleet's unverifiable-sources subject count, for the one-line rollup. */\n  unverifiable: number;\n  /**\n   * The run's scorecard facts the renderer reads — ONE field, not a nullable\n   * adoption beside a defaulted denominator, so \"adoption without its real\n   * denominator\" is not constructible. Null on every single-target run and on\n   * an `--all` run whose card failed closed, and null renders exactly as\n   * before grouping existed: fail-open to today's behaviour, every warning\n   * printed individually.\n   */\n  scorecard: { readonly adoption: Adoption; readonly services: number } | null;\n}\n\n/**\n * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code\n * lever: neither changes the report, and the `--json` payload is unaffected by\n * both. On a fleet of a hundred services the clean run prints several hundred\n * `ok` confirmations, and the two warnings that matter are somewhere inside it;\n * anyone reading a CI log wants the exceptions, and anyone auditing wants all\n * of it. Both are available, from the same run, and neither is the default.\n *\n * Axis grouping is the same kind of lever, one notch further: warnings whose\n * SOLE cause is a fleet-wide not-started axis (the mechanical, fail-closed\n * rule in fleet/scorecard/adoption.ts — warn severity, listed code, axis at\n * zero) are dropped from the per-target listing and re-stated as one banner\n * per axis after the footer. The report, the footer's counts, `--json` and\n * `--strict` are all computed from the UNFILTERED findings, so nothing a\n * machine or an exit code reads moves by a single bit.\n */\nexport function renderText(targets: TargetReport[], opts: RenderOptions): void {\n  const { all, errorsOnly, unverifiable } = opts;\n  // When the fleet-wide \"not started\" claim is measurable at all — each guard\n  // fails closed to ungrouped rendering. `!all` is structural, not just the\n  // call site's promise: the banners print after the footer that only `--all`\n  // reaches, so grouping outside `--all` would DROP warnings instead of\n  // moving them — the one thing this lever must never do. `services === 0`\n  // is the vacuous fleet: with no services every axis is 0 \"fleet-wide\", and\n  // a banner over \"0 of 0 services\" would hide the fleet-level warnings of a\n  // repo that merely has no fleet yet. And an unreadable service proves\n  // nothing about what it started: its all-false participation (contracts.ts)\n  // could MANUFACTURE the very N=0 that licenses suppression — beside an\n  // error saying that service could not be checked — so one\n  // `service.unreadable` subject disables grouping for the whole run.\n  const card =\n    !all ||\n    opts.scorecard === null ||\n    opts.scorecard.services === 0 ||\n    subjectsWith(targets, \"service.unreadable\") > 0\n      ? null\n      : opts.scorecard;\n  const grouped = card === null ? new Map<string, AdoptionAxis>() : groupedWarnCodes(card.adoption);\n  const isGrouped = (f: Finding): boolean => f.severity === \"warn\" && grouped.has(f.code);\n\n  // The explain pointer follows any report that printed work — a non-ok\n  // finding, listed or folded under an axis banner. Gated on the UNFILTERED\n  // findings like every other rollup, so `--errors-only` and grouping cannot\n  // print codes the pointer then fails to follow. It is computed HERE rather\n  // than beside the two places it prints because the code column below asks\n  // the same question and must not walk the findings a second time to answer\n  // it differently.\n  const pointer = targets.some((t) => t.findings.some((f) => f.severity !== \"ok\"));\n  // The lookup key on the line itself.\n  //\n  // Until now a text report printed messages and no codes, so the footer under\n  // it could only say codes were somewhere else — in `--json`, which a reader\n  // would have to re-run the whole command to see. The code is what `loam\n  // explain` takes, what a CI branch tests and what a bug report quotes, and\n  // withholding it from the one surface a person actually reads made the\n  // footer's own offer unreachable.\n  //\n  // Only where a code is genuinely answerable, and that guard is not\n  // decoration: a handful of emitted finding codes still have no fix-table row\n  // (test/explain.test.ts names them), and printing one beside a footer\n  // promising an explanation would send the reader to a refusal. The set is\n  // built ONCE per render, and only when something non-ok will be printed:\n  // `explainSubject` walks the shipped workflow bodies per code (the cost\n  // `fixesFor` measured from the other side, where a handful of lookups is the\n  // cheaper shape), while `listCodes()` walks them once for the whole\n  // vocabulary — and a fleet report has far more finding lines than the fleet\n  // has distinct codes. Measured: 2.7 ms for all 273 codes, once per report.\n  const explainable = pointer ? new Set(listCodes().map((listing) => listing.code)) : new Set<string>();\n  for (const t of targets) {\n    const shown = t.findings.filter(\n      (f) => !isGrouped(f) && (!errorsOnly || f.severity !== \"ok\"),\n    );\n    if (shown.length === 0) continue;\n    // A feature announces itself; a service's findings already carry its name.\n    if (t.kind === \"feature\") console.log(t.id);\n    let header: string | undefined;\n    for (const f of shown) {\n      const hint = f.text ?? {};\n      if (hint.header && hint.header !== header) {\n        header = hint.header;\n        console.log(`  ${header}`);\n      }\n      // The whole report goes to stdout, in document order. Splitting errors\n      // onto stderr meant a piped stdout silently lost them from the middle of\n      // the report and 2>&1 could reorder it; the exit code carries failure,\n      // and stderr stays reserved for refusals (the fail() path).\n      const marker = hint.marker === false ? \"\" : `${SEVERITY_MARK[f.severity]} `;\n      // `ok` confirmations stay clean, deliberately. A clean fleet run is\n      // several hundred ✓ lines and two warnings, and a code appended to every\n      // one of them would cost exactly the signal the exceptions carry — there\n      // is nothing to look up about a check that passed.\n      const code = f.severity !== \"ok\" && explainable.has(f.code) ? `  (${f.code})` : \"\";\n      console.log(`${\" \".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`);\n      for (const d of f.details ?? []) console.log(`    ${hint.detailPrefix ?? \"\"}${d}`);\n    }\n  }\n\n  if (!all) {\n    // Without the --all footer there would be nothing at all to print for a\n    // clean single target under --errors-only — and silence is the one output\n    // that must never mean \"checked, fine\".\n    if (errorsOnly && targets.every((t) => t.findings.every((f) => f.severity === \"ok\"))) {\n      console.log(`${targets.map((t) => t.id).join(\", \")}: no errors or warnings`);\n    }\n    if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n    return;\n  }\n  const s = summary(targets);\n  console.log(\n    `\\n${plural(s.services, \"service\")}, ${plural(s.features, \"feature\")} — ` +\n      `${plural(s.errors, \"error\")}, ${plural(s.warnings, \"warning\")}`,\n  );\n  // One line for the whole fleet, never one per service: honest about the blind\n  // spot without drowning the report in a hundred copies of it.\n  if (unverifiable > 0) {\n    const whose = unverifiable === 1 ? \"1 service's\" : `${unverifiable} services'`;\n    console.log(\n      `⚠ sources.unverifiable-from-here: ${whose} sources can only be checked from their own repos`,\n    );\n  }\n  // The axis banners — one per not-started axis that actually grouped a\n  // warning, in the axes' fixed order, each naming its dropped codes with\n  // counts. Tallied off the UNFILTERED findings (the same walk the footer\n  // counts), and printed under --errors-only too: like the footer and the\n  // unverifiable line this is a rollup, not a finding.\n  if (card !== null && grouped.size > 0) {\n    const tally = new Map<string, number>();\n    for (const t of targets) {\n      for (const f of t.findings) {\n        if (isGrouped(f)) tally.set(f.code, (tally.get(f.code) ?? 0) + 1);\n      }\n    }\n    for (const axis of ADOPTION_AXES) {\n      // Insertion order of `grouped` is the table's order, so the pairs render\n      // deterministically across runs and machines.\n      const pairs = [...grouped]\n        .filter(([code, a]) => a === axis && (tally.get(code) ?? 0) > 0)\n        .map(([code]) => [code, tally.get(code) ?? 0] as const);\n      if (pairs.length === 0) continue;\n      const total = pairs.reduce((n, [, k]) => n + k, 0);\n      console.log(\n        `⚠ ${axis} axis not started fleet-wide (0 of ${plural(card.services, \"service\")}), ` +\n          `expected during staged adoption — ${total} warning(s) grouped: ` +\n          `${pairs.map(([code, k]) => `${code}×${k}`).join(\", \")}; every finding is unchanged in --json`,\n      );\n    }\n  }\n  if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n}\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/commands/validate/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Everything that happens to a `TargetReport` around the checks themselves:\n * how one is built when a target could not be read at all, how a finding's\n * evidence is capped, how the set is summed, and how it prints.\n *\n * A module rather than the tail of validate.ts because the rollup and the\n * renderer have to agree. The `--all` footer and the `--json` summary are the\n * same `summary()`, and the cap reaches both payloads from one place; a second\n * copy of either is how a footer starts printing a number its own findings\n * contradict.\n */\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listCodes } from \"../../core/explain/lookup.js\";\nimport {\n  countSeverity,\n  subjectsWith,\n  SEVERITY_MARK,\n  type Finding,\n  type TargetReport,\n} from \"../../core/vocabulary/report.js\";\nimport { EXPLAIN_FOOTER, plural } from \"../policy/format.js\";\nimport {\n  ADOPTION_AXES,\n  groupedWarnCodes,\n  type Adoption,\n  type AdoptionAxis,\n} from \"./fleet/scorecard/adoption.js\";\n\n/**\n * The rollup `--json` carries and the `--all` footer prints.\n *\n * Four named fields rather than a `Record<string, number>`: the keys ARE the\n * contract, and under an index signature every read of them was an assertion\n * (`s.errors!`) that tsc could not check — rename one and the compiler stayed\n * quiet while the footer printed `undefined errors`.\n */\nexport interface ValidateSummary {\n  services: number;\n  features: number;\n  errors: number;\n  warnings: number;\n}\n\nexport function summary(targets: TargetReport[]): ValidateSummary {\n  return {\n    services: targets.filter((t) => t.kind === \"service\").length,\n    features: targets.filter((t) => t.kind === \"feature\").length,\n    errors: countSeverity(targets, \"error\"),\n    warnings: countSeverity(targets, \"warn\"),\n  };\n}\n\n/**\n * How many services this run could not check, for the rollup line and the\n * `--json` payload.\n *\n * Counted off the findings rather than alongside them, so the rollup line\n * and the per-service findings can never disagree about how many services\n * this run could not check. The by-SUBJECT rule (a service whose spec.md and\n * arch.spec.md both name `sources` raises two findings and is one service) is\n * `subjectsWith`'s, spelled once for every findings-derived rollup — the\n * fleet scorecard counts through the same function on the same code, so its\n * number and this one are structurally the same number. The code is a LITERAL,\n * as it is at the emission site (checks/sources.ts), rather than a shared\n * constant, because the stable-code collector reads counting sites too, and it\n * refuses a slot it cannot read — the collector is also what convicts a typo\n * here.\n */\nexport function unverifiableSubjects(targets: TargetReport[]): number {\n  return subjectsWith(targets, \"sources.unverifiable-from-here\");\n}\n\n/**\n * How many `details` lines any one finding may print before the rest are\n * summarised away.\n *\n * A finding's details are evidence, not a log: LikeC4 reports one syntax error\n * as dozens of cascading diagnostics, and a fleet-sized repo multiplies that by\n * every target that mentions the file. The report is read by a person scrolling\n * a CI log and by an agent with a context window, and neither of them is helped\n * by the four-hundredth copy. The cap is applied to the JSON payload too, on\n * purpose: `--json` is the interface an agent pipes, and an unbounded array is\n * the same denial-of-attention there, just machine-readable.\n */\nconst DETAIL_LIMIT = 10;\n\n/** Truncate every finding's details, marking what was dropped so nothing looks complete when it is not. */\nexport function capDetails(t: TargetReport): TargetReport {\n  return {\n    ...t,\n    findings: t.findings.map((f) => {\n      const details = f.details ?? [];\n      if (details.length <= DETAIL_LIMIT) return f;\n      return {\n        ...f,\n        details: [...details.slice(0, DETAIL_LIMIT), `… (+${details.length - DETAIL_LIMIT} more)`],\n      };\n    }),\n  };\n}\n\n/**\n * One target's checks, with an IO exception turned into a finding ON that\n * target instead of aborting the run.\n *\n * A fleet gate that dies on the first unreadable file reports nothing about the\n * other ninety-nine services — one bad permission bit, one file that is a\n * dangling symlink, and CI's answer to \"how is the fleet\" becomes a stack\n * trace. The failure is real and it is an error, so the run still exits 1; what\n * changes is that everything else is still graded, and the finding names the\n * service and the path instead of arriving as the `internal` catch-all.\n */\nexport async function guarded(\n  target: { kind: \"service\" | \"feature\"; id: string },\n  run: () => Promise<TargetReport>,\n): Promise<TargetReport> {\n  try {\n    return await run();\n  } catch (err) {\n    // A docs repo that vanished mid-run is not one target's problem — it is the\n    // whole run's, and the action's own catch reports it.\n    if (err instanceof DocsRepoUnavailableError) throw err;\n    const path = (err as NodeJS.ErrnoException).path;\n    const reason = err instanceof Error ? err.message : String(err);\n    return {\n      kind: target.kind,\n      id: target.id,\n      findings: [\n        {\n          severity: \"error\",\n          code: target.kind === \"service\" ? \"service.unreadable\" : \"feature.unreadable\",\n          subject: target.id,\n          message:\n            `${target.id}: ${path === undefined ? \"an artifact\" : path} could not be read — ` +\n            `nothing about this ${target.kind} was checked. ${reason}`,\n        },\n      ],\n    };\n  }\n}\n\n/**\n * `target.ambiguous` — the positional named a service AND a feature. The tie is\n * still broken the way it always was (the feature wins), because changing which\n * one is picked would silently re-target every script that relies on it; what\n * is new is that the run says which reading it took and how to force the other.\n */\nexport function ambiguousTarget(arg: string, chosen: \"service\" | \"feature\"): Finding {\n  const other = chosen === \"feature\" ? \"service\" : \"feature\";\n  return {\n    severity: \"warn\",\n    code: \"target.ambiguous\",\n    subject: arg,\n    message:\n      `'${arg}' names both a service and a feature — validated as the ${chosen}. ` +\n      `Pass --${other} ${arg} for the other reading.`,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Text renderer                                                       */\n/* ------------------------------------------------------------------ */\n\n/** What `renderText` needs of the run beyond the graded targets themselves. */\nexport interface RenderOptions {\n  all: boolean;\n  errorsOnly: boolean;\n  /** The fleet's unverifiable-sources subject count, for the one-line rollup. */\n  unverifiable: number;\n  /**\n   * The run's scorecard facts the renderer reads — ONE field, not a nullable\n   * adoption beside a defaulted denominator, so \"adoption without its real\n   * denominator\" is not constructible. Null on every single-target run and on\n   * an `--all` run whose card failed closed, and null renders exactly as\n   * before grouping existed: fail-open to today's behaviour, every warning\n   * printed individually.\n   */\n  scorecard: { readonly adoption: Adoption; readonly services: number } | null;\n}\n\n/**\n * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code\n * lever: neither changes the report, and the `--json` payload is unaffected by\n * both. On a fleet of a hundred services the clean run prints several hundred\n * `ok` confirmations, and the two warnings that matter are somewhere inside it;\n * anyone reading a CI log wants the exceptions, and anyone auditing wants all\n * of it. Both are available, from the same run, and neither is the default.\n *\n * Axis grouping is the same kind of lever, one notch further: warnings whose\n * SOLE cause is a fleet-wide not-started axis (the mechanical, fail-closed\n * rule in fleet/scorecard/adoption.ts — warn severity, listed code, axis at\n * zero) are dropped from the per-target listing and re-stated as one banner\n * per axis after the footer. The report, the footer's counts, `--json` and\n * `--strict` are all computed from the UNFILTERED findings, so nothing a\n * machine or an exit code reads moves by a single bit.\n */\nexport function renderText(targets: TargetReport[], opts: RenderOptions): void {\n  const { all, errorsOnly, unverifiable } = opts;\n  // When the fleet-wide \"not started\" claim is measurable at all — each guard\n  // fails closed to ungrouped rendering. `!all` is structural, not just the\n  // call site's promise: the banners print after the footer that only `--all`\n  // reaches, so grouping outside `--all` would DROP warnings instead of\n  // moving them — the one thing this lever must never do. `services === 0`\n  // is the vacuous fleet: with no services every axis is 0 \"fleet-wide\", and\n  // a banner over \"0 of 0 services\" would hide the fleet-level warnings of a\n  // repo that merely has no fleet yet. And an unreadable service proves\n  // nothing about what it started: its all-false participation (contracts.ts)\n  // could MANUFACTURE the very N=0 that licenses suppression — beside an\n  // error saying that service could not be checked — so one\n  // `service.unreadable` subject disables grouping for the whole run.\n  const card =\n    !all ||\n    opts.scorecard === null ||\n    opts.scorecard.services === 0 ||\n    subjectsWith(targets, \"service.unreadable\") > 0\n      ? null\n      : opts.scorecard;\n  const grouped = card === null ? new Map<string, AdoptionAxis>() : groupedWarnCodes(card.adoption);\n  const isGrouped = (f: Finding): boolean => f.severity === \"warn\" && grouped.has(f.code);\n\n  // The explain pointer follows any report that printed work — a non-ok\n  // finding, listed or folded under an axis banner. Gated on the UNFILTERED\n  // findings like every other rollup, so `--errors-only` and grouping cannot\n  // print codes the pointer then fails to follow. It is computed HERE rather\n  // than beside the two places it prints because the code column below asks\n  // the same question and must not walk the findings a second time to answer\n  // it differently.\n  const pointer = targets.some((t) => t.findings.some((f) => f.severity !== \"ok\"));\n  // The lookup key on the line itself.\n  //\n  // Until now a text report printed messages and no codes, so the footer under\n  // it could only say codes were somewhere else — in `--json`, which a reader\n  // would have to re-run the whole command to see. The code is what `loam\n  // explain` takes, what a CI branch tests and what a bug report quotes, and\n  // withholding it from the one surface a person actually reads made the\n  // footer's own offer unreachable.\n  //\n  // Only where a code is genuinely answerable, and that guard is not\n  // decoration: a handful of emitted finding codes still have no fix-table row\n  // (test/explain.test.ts names them), and printing one beside a footer\n  // promising an explanation would send the reader to a refusal. The set is\n  // built ONCE per render, and only when something non-ok will be printed:\n  // `explainSubject` walks the shipped workflow bodies per code (the cost\n  // `fixesFor` measured from the other side, where a handful of lookups is the\n  // cheaper shape), while `listCodes()` walks them once for the whole\n  // vocabulary — and a fleet report has far more finding lines than the fleet\n  // has distinct codes. Measured: 2.7 ms for all 273 codes, once per report.\n  const explainable = pointer ? new Set(listCodes().map((listing) => listing.code)) : new Set<string>();\n  for (const t of targets) {\n    const shown = t.findings.filter(\n      (f) => !isGrouped(f) && (!errorsOnly || f.severity !== \"ok\"),\n    );\n    if (shown.length === 0) continue;\n    // A feature announces itself; a service's findings already carry its name.\n    if (t.kind === \"feature\") console.log(t.id);\n    let header: string | undefined;\n    for (const f of shown) {\n      const hint = f.text ?? {};\n      if (hint.header && hint.header !== header) {\n        header = hint.header;\n        console.log(`  ${header}`);\n      }\n      // The whole report goes to stdout, in document order. Splitting errors\n      // onto stderr meant a piped stdout silently lost them from the middle of\n      // the report and 2>&1 could reorder it; the exit code carries failure,\n      // and stderr stays reserved for refusals (the fail() path).\n      const marker = hint.marker === false ? \"\" : `${SEVERITY_MARK[f.severity]} `;\n      // `ok` confirmations stay clean, deliberately. A clean fleet run is\n      // several hundred ✓ lines and two warnings, and a code appended to every\n      // one of them would cost exactly the signal the exceptions carry — there\n      // is nothing to look up about a check that passed.\n      const code = f.severity !== \"ok\" && explainable.has(f.code) ? `  (${f.code})` : \"\";\n      console.log(`${\" \".repeat(hint.indent ?? 0)}${marker}${f.message}${code}`);\n      for (const d of f.details ?? []) console.log(`    ${hint.detailPrefix ?? \"\"}${d}`);\n    }\n  }\n\n  if (!all) {\n    // Without the --all footer there would be nothing at all to print for a\n    // clean single target under --errors-only — and silence is the one output\n    // that must never mean \"checked, fine\".\n    if (errorsOnly && targets.every((t) => t.findings.every((f) => f.severity === \"ok\"))) {\n      console.log(`${targets.map((t) => t.id).join(\", \")}: no errors or warnings`);\n    }\n    if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n    return;\n  }\n  const s = summary(targets);\n  console.log(\n    `\\n${plural(s.services, \"service\")}, ${plural(s.features, \"feature\")} — ` +\n      `${plural(s.errors, \"error\")}, ${plural(s.warnings, \"warning\")}`,\n  );\n  // One line for the whole fleet, never one per service: honest about the blind\n  // spot without drowning the report in a hundred copies of it.\n  if (unverifiable > 0) {\n    const whose = unverifiable === 1 ? \"1 service's\" : `${unverifiable} services'`;\n    console.log(\n      `⚠ sources.unverifiable-from-here: ${whose} sources can only be checked from their own repos`,\n    );\n  }\n  // The axis banners — one per not-started axis that actually grouped a\n  // warning, in the axes' fixed order, each naming its dropped codes with\n  // counts. Tallied off the UNFILTERED findings (the same walk the footer\n  // counts), and printed under --errors-only too: like the footer and the\n  // unverifiable line this is a rollup, not a finding.\n  if (card !== null && grouped.size > 0) {\n    const tally = new Map<string, number>();\n    for (const t of targets) {\n      for (const f of t.findings) {\n        if (isGrouped(f)) tally.set(f.code, (tally.get(f.code) ?? 0) + 1);\n      }\n    }\n    for (const axis of ADOPTION_AXES) {\n      // Insertion order of `grouped` is the table's order, so the pairs render\n      // deterministically across runs and machines.\n      const pairs = [...grouped]\n        .filter(([code, a]) => a === axis && (tally.get(code) ?? 0) > 0)\n        .map(([code]) => [code, tally.get(code) ?? 0] as const);\n      if (pairs.length === 0) continue;\n      const total = pairs.reduce((n, [, k]) => n + k, 0);\n      console.log(\n        `⚠ ${axis} axis not started fleet-wide (0 of ${plural(card.services, \"service\")}), ` +\n          `expected during staged adoption — ${total} warning(s) grouped: ` +\n          `${pairs.map(([code, k]) => `${code}×${k}`).join(\", \")}; every finding is unchanged in --json`,\n      );\n    }\n  }\n  if (pointer) console.log(`\\n${EXPLAIN_FOOTER}`);\n}\n"]}

package/dist/commands/validate/scope.js

@@ -0,0 +1,113 @@
+/**
+ * What a `--base` run does to the landscape target, which is the one target
+ * whose subject is not a directory.
+ *
+ * Every other target is graded whole or not at all: a service or a feature the
+ * branch touched is graded by exactly the checks `--all` runs on it. The
+ * landscape cannot be, for two reasons that pull in opposite directions, and
+ * both are defects a docs-repo PR gate actually shipped with.
+ *
+ * IT GRADED TOO MUCH. The landscape target carries the fleet-wide
+ * vocabularies' warnings — a permission nobody requires, a capability nobody
+ * realizes, an obligation nobody applies, a glossary term nobody cites — and
+ * the AGENTS.md stamp. Every one of those grades a file other than the map, so
+ * any `architecture/` branch re-graded all of them, and under `--strict` a
+ * one-line map edit on the adopted example fleet went red on four warnings that
+ * were all there at the base. Those findings now ride a scoped run only when the
+ * file that carries them changed.
+ *
+ * IT GRADED TOO LITTLE. `spine.op-undefined` is graded on the PROVIDER's
+ * service target, so an edge the branch drew or re-spelled on the map was
+ * graded by no scoped run unless the provider happened to change too —
+ * README's own `authorisePayment` example merged green through both PR gates.
+ * Those edges are now graded here, against their providers' contracts, and
+ * ONLY those edges: pulling the provider into scope instead would grade every
+ * document it already has, which on a spine-first fleet means
+ * `service.no-model` reddening exactly the labour that path asks for.
+ */
+import { existsSync } from "node:fs";
+import { serviceResolver } from "../../core/c4/resolve/service.js";
+import { edgeKey } from "../../core/diff/scope/edges.js";
+import { touched } from "../../core/diff/scope/changed-paths.js";
+import { repoPath } from "../../core/envelope/json.js";
+import { inOrder } from "../../core/kernel/concurrency.js";
+import { serviceTreePath } from "../../core/kernel/ids/dirs.js";
+import { readOpenapi } from "../../core/openapi/doc.js";
+import { capabilityDocsDir, glossaryDir } from "../../core/repo/authored/paths.js";
+import { agentsPath, capabilitiesPath, obligationsPath, permissionsPath, servicePathsAt } from "../../core/repo/paths.js";
+import { contractOf } from "./service/api.js";
+import { spineFindings } from "./service/spine.js";
+/**
+ * The landscape target's findings that grade a file other than the map, with
+ * the file — or directory — that carries each.
+ *
+ * Only the families that are a VERDICT ON THAT FILE are listed: the vocabulary
+ * that does not read, and the declaration nothing cites. The obligation codes
+ * the MAP causes stay off this table — `obligation.unknown` (a tag naming no
+ * rule) and `obligation.uncovered` (an applied rule no requirement covers) are
+ * written by an edit to `architecture/`, and a scoped run over that edit owes
+ * them. A code on no row rides the landscape target exactly as before.
+ *
+ * What this costs, said once: the "nothing cites it" grades also move when a
+ * CITATION goes away — a branch deleting the last `Requires:` line naming a
+ * permission. A branch that touches only a service never graded the landscape
+ * at all, so that is not a new blind spot; the unscoped `validate --all` keeps
+ * reporting every one of these.
+ */
+const CARRIED = [
+    { carries: (code) => code.startsWith("permissions."), by: (d) => [permissionsPath(d)] },
+    { carries: (code) => code.startsWith("capability."), by: (d) => [capabilitiesPath(d), capabilityDocsDir(d)] },
+    { carries: (code) => code === "obligation.invalid" || code === "obligation.unapplied", by: (d) => [obligationsPath(d)] },
+    { carries: (code) => code.startsWith("glossary."), by: (d) => [glossaryDir(d)] },
+    // The stamp is a fact about which binary wrote the file, and a branch that
+    // did not edit the file did not move it — `loam doctor` is where a binary
+    // upgrade is noticed, not every map PR that happens to follow one.
+    { carries: (code) => code === "agents.stale" || code === "docs.binary-behind", by: (d) => [agentsPath(d)] },
+];
+/** The landscape target's `findings` as a `--base` run reports them. */
+export async function scopedLandscapeFindings(findings, scoped) {
+    const { docsDir, scope } = scoped;
+    const kept = findings.filter((f) => {
+        const carried = CARRIED.find((row) => row.carries(f.code));
+        return carried === undefined || carried.by(docsDir).some((abs) => touched(scope, repoPath(docsDir, abs)));
+    });
+    return [...kept, ...(await changedEdgeFindings(scoped))];
+}
+/**
+ * The spine of the edges this branch wrote, graded per provider by the
+ * service target's own `spineFindings` over just those edges — so a changed
+ * edge reads exactly as it would on the provider's target, and an unreadable
+ * or absent contract proves nothing here for the reason it proves nothing
+ * there.
+ *
+ * A provider the run already grades is skipped: its own target walks every
+ * inbound edge, these included, and grading them twice would report one broken
+ * join as two.
+ */
+async function changedEdgeFindings(scoped) {
+    const { docsDir, scope, land, services, fleet } = scoped;
+    // A map that does not parse has no edges to read, and `landscape.invalid`
+    // on this same target already says so.
+    if (land === null || land.errors.length > 0 || scope.edges.size === 0)
+        return [];
+    const svcOf = serviceResolver(land.elements, new Set(services.map((s) => s.id)));
+    const providerOf = (target) => svcOf(target);
+    const edges = land.relationships.filter((r) => scope.edges.has(edgeKey(r)));
+    const graded = new Set(scope.services.map((s) => s.id));
+    const providers = services.filter((s) => !graded.has(s.id) && edges.some((r) => providerOf(r.target) === s.id));
+    const perProvider = await inOrder(providers, async (svc) => {
+        const paths = servicePathsAt(svc.dir);
+        return spineFindings({
+            service: svc.id,
+            docsDir,
+            treePath: serviceTreePath(svc),
+            me: svc.id,
+            land: { ...land, relationships: edges.filter((r) => providerOf(r.target) === svc.id) },
+            landSvcOf: svcOf,
+            contract: contractOf(await readOpenapi(paths.openapi, fleet), !existsSync(paths.openapi)),
+            landscapeReported: true,
+        });
+    });
+    return perProvider.flat();
+}
+//# sourceMappingURL=scope.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../src/commands/validate/scope.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a `--base` run does to the landscape target, which is the one target\n * whose subject is not a directory.\n *\n * Every other target is graded whole or not at all: a service or a feature the\n * branch touched is graded by exactly the checks `--all` runs on it. The\n * landscape cannot be, for two reasons that pull in opposite directions, and\n * both are defects a docs-repo PR gate actually shipped with.\n *\n * IT GRADED TOO MUCH. The landscape target carries the fleet-wide\n * vocabularies' warnings — a permission nobody requires, a capability nobody\n * realizes, an obligation nobody applies, a glossary term nobody cites — and\n * the AGENTS.md stamp. Every one of those grades a file other than the map, so\n * any `architecture/` branch re-graded all of them, and under `--strict` a\n * one-line map edit on the adopted example fleet went red on four warnings that\n * were all there at the base. Those findings now ride a scoped run only when the\n * file that carries them changed.\n *\n * IT GRADED TOO LITTLE. `spine.op-undefined` is graded on the PROVIDER's\n * service target, so an edge the branch drew or re-spelled on the map was\n * graded by no scoped run unless the provider happened to change too —\n * README's own `authorisePayment` example merged green through both PR gates.\n * Those edges are now graded here, against their providers' contracts, and\n * ONLY those edges: pulling the provider into scope instead would grade every\n * document it already has, which on a spine-first fleet means\n * `service.no-model` reddening exactly the labour that path asks for.\n */\nimport { existsSync } from \"node:fs\";\nimport { serviceResolver } from \"../../core/c4/resolve/service.js\";\nimport type { LoadedDoc } from \"../../core/c4/likec4.js\";\nimport { edgeKey } from \"../../core/diff/scope/edges.js\";\nimport { touched, type ValidateScope } from \"../../core/diff/scope/changed-paths.js\";\nimport { repoPath } from \"../../core/envelope/json.js\";\nimport type { FleetContext } from \"../../core/fleet-context.js\";\nimport { inOrder } from \"../../core/kernel/concurrency.js\";\nimport { serviceTreePath, type DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { readOpenapi } from \"../../core/openapi/doc.js\";\nimport { capabilityDocsDir, glossaryDir } from \"../../core/repo/authored/paths.js\";\nimport type { ServiceEntry } from \"../../core/repo/entries.js\";\nimport { agentsPath, capabilitiesPath, obligationsPath, permissionsPath, servicePathsAt } from \"../../core/repo/paths.js\";\nimport type { Finding } from \"../../core/vocabulary/report.js\";\nimport { contractOf } from \"./service/api.js\";\nimport { spineFindings } from \"./service/spine.js\";\n\n/**\n * The landscape target's findings that grade a file other than the map, with\n * the file — or directory — that carries each.\n *\n * Only the families that are a VERDICT ON THAT FILE are listed: the vocabulary\n * that does not read, and the declaration nothing cites. The obligation codes\n * the MAP causes stay off this table — `obligation.unknown` (a tag naming no\n * rule) and `obligation.uncovered` (an applied rule no requirement covers) are\n * written by an edit to `architecture/`, and a scoped run over that edit owes\n * them. A code on no row rides the landscape target exactly as before.\n *\n * What this costs, said once: the \"nothing cites it\" grades also move when a\n * CITATION goes away — a branch deleting the last `Requires:` line naming a\n * permission. A branch that touches only a service never graded the landscape\n * at all, so that is not a new blind spot; the unscoped `validate --all` keeps\n * reporting every one of these.\n */\nconst CARRIED: readonly { carries: (code: string) => boolean; by: (docsDir: DocsDir) => string[] }[] = [\n  { carries: (code) => code.startsWith(\"permissions.\"), by: (d) => [permissionsPath(d)] },\n  { carries: (code) => code.startsWith(\"capability.\"), by: (d) => [capabilitiesPath(d), capabilityDocsDir(d)] },\n  { carries: (code) => code === \"obligation.invalid\" || code === \"obligation.unapplied\", by: (d) => [obligationsPath(d)] },\n  { carries: (code) => code.startsWith(\"glossary.\"), by: (d) => [glossaryDir(d)] },\n  // The stamp is a fact about which binary wrote the file, and a branch that\n  // did not edit the file did not move it — `loam doctor` is where a binary\n  // upgrade is noticed, not every map PR that happens to follow one.\n  { carries: (code) => code === \"agents.stale\" || code === \"docs.binary-behind\", by: (d) => [agentsPath(d)] },\n];\n\n/** What the scoped landscape grade needs from the run. */\nexport interface ScopedLandscape {\n  docsDir: DocsDir;\n  scope: ValidateScope;\n  /** The parsed `architecture/` project, or null when the repo draws no fleet. */\n  land: LoadedDoc | null;\n  /** The run's FULL service enumeration: a changed edge's provider is found here whether or not it is in scope. */\n  services: readonly ServiceEntry[];\n  fleet: FleetContext;\n}\n\n/** The landscape target's `findings` as a `--base` run reports them. */\nexport async function scopedLandscapeFindings(findings: Finding[], scoped: ScopedLandscape): Promise<Finding[]> {\n  const { docsDir, scope } = scoped;\n  const kept = findings.filter((f) => {\n    const carried = CARRIED.find((row) => row.carries(f.code));\n    return carried === undefined || carried.by(docsDir).some((abs) => touched(scope, repoPath(docsDir, abs)));\n  });\n  return [...kept, ...(await changedEdgeFindings(scoped))];\n}\n\n/**\n * The spine of the edges this branch wrote, graded per provider by the\n * service target's own `spineFindings` over just those edges — so a changed\n * edge reads exactly as it would on the provider's target, and an unreadable\n * or absent contract proves nothing here for the reason it proves nothing\n * there.\n *\n * A provider the run already grades is skipped: its own target walks every\n * inbound edge, these included, and grading them twice would report one broken\n * join as two.\n */\nasync function changedEdgeFindings(scoped: ScopedLandscape): Promise<Finding[]> {\n  const { docsDir, scope, land, services, fleet } = scoped;\n  // A map that does not parse has no edges to read, and `landscape.invalid`\n  // on this same target already says so.\n  if (land === null || land.errors.length > 0 || scope.edges.size === 0) return [];\n  const svcOf = serviceResolver(land.elements, new Set(services.map((s) => s.id)));\n  const providerOf = (target: string): string => svcOf(target);\n  const edges = land.relationships.filter((r) => scope.edges.has(edgeKey(r)));\n  const graded = new Set(scope.services.map((s) => s.id));\n  const providers = services.filter((s) => !graded.has(s.id) && edges.some((r) => providerOf(r.target) === s.id));\n  const perProvider = await inOrder(providers, async (svc) => {\n    const paths = servicePathsAt(svc.dir);\n    return spineFindings({\n      service: svc.id,\n      docsDir,\n      treePath: serviceTreePath(svc),\n      me: svc.id,\n      land: { ...land, relationships: edges.filter((r) => providerOf(r.target) === svc.id) },\n      landSvcOf: svcOf,\n      contract: contractOf(await readOpenapi(paths.openapi, fleet), !existsSync(paths.openapi)),\n      landscapeReported: true,\n    });\n  });\n  return perProvider.flat();\n}\n"]}

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

@@ -10,11 +10,6 @@
  * is what reads it.
  */
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { parse as parseYaml } from "yaml";
-import { resolveInside } from "../../../core/kernel/path-safety.js";
-import { canonicalJson } from "../../../core/openapi/digest.js";
 import { closeIds } from "../../../core/c4/arch.js";
 import {} from "../../../core/c4/likec4.js";
 import {} from "../../../core/kernel/ids/service.js";
@@ -31,8 +26,10 @@ export async function apiAxisFindings(axis) {
     const api = await readOpenapi(paths.openapi, fleet);
     const removeMarkers = api.ops.filter((o) => o.remove);
     const liveOps = api.ops.filter((o) => !o.remove);
-    const ops = liveOps.map((o) => o.id);
-    const deprecatedOps = new Set(liveOps.filter((o) => o.deprecated).map((o) => o.id));
+    /** No contract to read: deleted, renamed, or never written. */
+    const contractMissing = !existsSync(paths.openapi);
+    const contract = contractOf(api, contractMissing);
+    const { ops, deprecated: deprecatedOps } = contract;
     // Inbound calls the landscape can PROVE: op-linked edges whose target
     // resolves to this service. Null when the landscape proves nothing at all
     // (absent, or it did not parse) — which is not the same fact as "nobody
@@ -43,8 +40,6 @@ export async function apiAxisFindings(axis) {
     // The other half of the evidence a contract is owed: the living spec's own
     // `Operations:` lines. A requirement on its way out governs nothing.
     const governedOps = livingReqs.flatMap((r) => r.operations);
-    /** No contract to read: deleted, renamed, or never written. */
-    const contractMissing = !existsSync(paths.openapi);
     if (contractMissing) {
         // A contract that is gone is not a reason to stop grading the API axis —
         // it IS the axis's answer, and every check below used to live inside the
@@ -236,103 +231,20 @@ export async function apiAxisFindings(axis) {
             }
         }
     }
-    return {
-        findings,
-        contract: { ops, deprecated: deprecatedOps, unreadable: api.unreadable || contractMissing },
-    };
+    return { findings, contract };
 }
 /**
- * The build's own contract document, compared with the copy the docs repo
- * committed — `openapi.generated-stale`, `contracts.source-missing`,
- * `contracts.source-invalid`.
- *
- * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no
- * meaning: it parses a standard document the team's own build emitted, at a
- * path a human wrote into `loam.json`, and compares a digest. That is the same
- * category as `verify --results` ingesting a cucumber report, and it is the
- * only thing in the product that can notice the assumption SCHEMA quietly makes
- * — that the committed `services/<id>/openapi.yaml` is the contract the service
- * actually serves. Most fleets generate that document; a fleet that copies it
- * by hand in month one is a fleet whose spine checks grade last quarter's
- * endpoints by month six, and until now nothing could say so.
- *
- * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,
- * because that is what makes the docs-repo document a contract somebody agreed
- * to rather than a cache of whatever the build last produced. loam reports the
- * divergence and stops.
- *
- * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions
- * that order keys differently, or a YAML dumper that re-wraps a description,
- * produce identical documents and must not produce a permanent warning nobody
- * can clear — the lesson `requirementDigest` already records one package over.
- *
- * Runs only in the SERVICE repo. From the docs repo there is no build output to
- * read and the whole family stays silent, exactly as `sources` provenance does.
+ * What the spine may conclude from one contract read — spelled once, because a
+ * `--base` run now grades a changed edge against a provider it does not grade
+ * as a target (`../scope.ts`), and two spellings of "which operations are
+ * live" would be two chances for a removal marker to count as defined.
  */
-export async function generatedContractFindings(service, repoDir, spelled, committedPath) {
-    if (spelled === undefined)
-        return [];
-    let generatedPath;
-    try {
-        // Containment is checked HERE rather than at config load, with the service
-        // in hand so the refusal can name it — and a path that escapes the repo is
-        // a finding, never a thrown config error that would take down every other
-        // command in the repo.
-        generatedPath = resolveInside(repoDir, spelled, `"contracts.openapi"`);
-    }
-    catch (err) {
-        return [{
-                severity: "error",
-                code: "contracts.source-invalid",
-                subject: service,
-                message: `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +
-                    `${err instanceof Error ? err.message : String(err)}`,
-            }];
-    }
-    if (!existsSync(generatedPath)) {
-        return [{
-                severity: "error",
-                code: "contracts.source-missing",
-                subject: service,
-                message: `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +
-                    "Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds " +
-                    "sees exactly this. Run the build first, or correct the path",
-            }];
-    }
-    const digests = [];
-    for (const [label, path] of [["generated", generatedPath], ["committed", committedPath]]) {
-        if (label === "committed" && !existsSync(path))
-            return [];
-        let parsed;
-        try {
-            parsed = parseYaml(await readFile(path, "utf8"));
-        }
-        catch (err) {
-            // An unreadable GENERATED document is this check's business; an
-            // unreadable committed one is already `openapi.invalid` and must not be
-            // reported twice under two codes.
-            if (label === "committed")
-                return [];
-            return [{
-                    severity: "error",
-                    code: "contracts.source-invalid",
-                    subject: service,
-                    message: `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +
-                        `${err instanceof Error ? err.message : String(err)}`,
-                }];
-        }
-        digests.push(createHash("sha256").update(canonicalJson(parsed), "utf8").digest("hex"));
-    }
-    if (digests[0] === digests[1])
-        return [];
-    return [{
-            severity: "warn",
-            code: "openapi.generated-stale",
-            subject: service,
-            message: `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ` +
-                "The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a " +
-                "contract this service no longer serves. Review the difference and copy the generated document across — " +
-                "loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build",
-        }];
+export function contractOf(api, missing) {
+    const live = api.ops.filter((o) => !o.remove);
+    return {
+        ops: live.map((o) => o.id),
+        deprecated: new Set(live.filter((o) => o.deprecated).map((o) => o.id)),
+        unreadable: api.unreadable || missing,
+    };
 }
 //# sourceMappingURL=api.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The HTTP contract axis: openapi.yaml graded against the living spec.\n *\n * What it decides for everything downstream is whether there is a contract to\n * read at all. A missing or unparseable openapi.yaml is ONE finding about ONE\n * file, and that fact has to travel: grading the fleet map's inbound edges\n * against the empty operation set it leaves behind turns one broken YAML into\n * one `spine.op-undefined` per consumer, each of them accusing the landscape of\n * a fault that is not there. `ServiceContract` is how it travels; `./spine.js`\n * is what reads it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { createHash } from \"node:crypto\";\nimport { parse as parseYaml } from \"yaml\";\nimport { resolveInside } from \"../../../core/kernel/path-safety.js\";\nimport { canonicalJson } from \"../../../core/openapi/digest.js\";\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type DeclaredService, type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { responseGovernanceFindings } from \"../checks/requirements.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { readOpenapi } from \"../../../core/openapi/doc.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\n\n/** What the service target hands the HTTP axis. */\nexport interface ApiAxis {\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  paths: ServicePaths;\n  /** Every requirement the living spec declares, REMOVED ones included. */\n  reqs: Requirement[];\n  /** The ones that still govern something. */\n  livingReqs: Requirement[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver, built once per run; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  fleet?: FleetContext;\n}\n\n/**\n * What the spine may conclude from this service's contract.\n *\n * `unreadable` covers both shapes of \"there is nothing to read\" — absent and\n * unparseable — because they have the same consequence for an inbound edge:\n * the contract proves neither that the operation exists nor that it does not.\n */\nexport interface ServiceContract {\n  /** operationIds the living contract defines, empty when there is nothing to read. */\n  ops: string[];\n  /** Those of them the contract marks `deprecated: true`. */\n  deprecated: ReadonlySet<string>;\n  unreadable: boolean;\n}\n\nexport async function apiAxisFindings(\n  axis: ApiAxis,\n): Promise<{ findings: Finding[]; contract: ServiceContract }> {\n  const { service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;\n  const findings: Finding[] = [];\n\n  // API coverage: every operation in openapi.yaml is governed by a requirement.\n  const api = await readOpenapi(paths.openapi, fleet);\n  const removeMarkers = api.ops.filter((o) => o.remove);\n  const liveOps = api.ops.filter((o) => !o.remove);\n  const ops = liveOps.map((o) => o.id);\n  const deprecatedOps = new Set(liveOps.filter((o) => o.deprecated).map((o) => o.id));\n  // Inbound calls the landscape can PROVE: op-linked edges whose target\n  // resolves to this service. Null when the landscape proves nothing at all\n  // (absent, or it did not parse) — which is not the same fact as \"nobody\n  // calls me\", and the two must not be graded alike.\n  const inboundOps =\n    land === null || land.errors.length > 0\n      ? null\n      : land.relationships.filter((r) => r.op !== undefined && landSvcOf!(r.target) === me);\n  // The other half of the evidence a contract is owed: the living spec's own\n  // `Operations:` lines. A requirement on its way out governs nothing.\n  const governedOps = livingReqs.flatMap((r) => r.operations);\n  /** No contract to read: deleted, renamed, or never written. */\n  const contractMissing = !existsSync(paths.openapi);\n  if (contractMissing) {\n    // A contract that is gone is not a reason to stop grading the API axis —\n    // it IS the axis's answer, and every check below used to live inside the\n    // file-exists branch, so deleting or misspelling the file turned the whole\n    // axis (including the documented `spec-api.op-undefined`) green.\n    //\n    // What decides the severity is whether anything already written down is\n    // holding a join into it: a living `Operations:` line, or an op-linked\n    // landscape edge. With one of those, the absence breaks a link somebody\n    // authored — an error. With neither, this is a service that legitimately\n    // has no HTTP surface (a worker nobody calls), and a fleet mid-rollout\n    // must not go red for it — a warning, or, when the landscape PROVES nobody\n    // calls it, the documented silence.\n    //\n    // One finding, not one per dangling link: the fix is a single file, and\n    // the links it strands ride along as details.\n    const dangling = [...new Set([...governedOps, ...(inboundOps ?? []).map((r) => r.op!)])].sort();\n    if (dangling.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"service.no-openapi\",\n        subject: service,\n        message:\n          `No OpenAPI contract at ${paths.openapi}, and ${dangling.length} operation link(s) already point into it — ` +\n          `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,\n        details: dangling,\n      });\n    } else if (inboundOps === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"service.no-openapi\",\n        message: `No OpenAPI contract at ${paths.openapi} — API coverage and the landscape spine are unchecked`,\n      });\n    }\n  } else if (api.unreadable) {\n    // A contract that EXISTS but does not read is a broken source of truth, not\n    // an empty one: swallowing it into zero operations used to grade every\n    // inbound landscape edge `spine.op-undefined` — a false diagnosis pointing\n    // at the landscape when the truth was this file. So the file is the error,\n    // and every check that reads the contract (api.*, the spine's op\n    // resolution) is suspended below, the landscape.invalid discipline.\n    findings.push({\n      severity: \"error\",\n      code: \"openapi.invalid\",\n      message: `${service}: openapi.yaml does not parse — API coverage and the landscape spine are unchecked`,\n      ...(api.error === undefined ? {} : { details: [api.error] }),\n    });\n  } else {\n    if (removeMarkers.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-living\",\n        message: `${service}: living openapi.yaml contains ${removeMarkers.length} x-loam-remove marker(s) (${removeMarkers.map((op) => op.id).join(\", \")}) — removal markers are valid only in feature deltas`,\n      });\n    }\n    // The same marker written at PATH level, beside the methods. `readOpenapi`\n    // is keyed by (path, method), which is precisely why the check above cannot\n    // see this one and precisely how one reached a living contract in the first\n    // place: it addresses no operation, so it retired nothing, and it stayed\n    // invisible afterwards. Error, like its method-level sibling — a\n    // feature-only key published to every consumer of the fleet, and one that\n    // keeps the empty-path cleanup from ever firing. Same code as the archive\n    // plan's: one breach, one name, wherever it is found.\n    for (const removed of api.pathLevelRemovals) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: service,\n        message:\n          `${service}: living openapi.yaml carries x-loam-remove at PATH level on '${removed}' — ` +\n          `a removal marker names ONE operation, so beside the methods it retires nothing and is not a contract key either, ` +\n          `and no id-keyed check can see it. Delete it from the living contract; retire an operation through a feature delta whose marker sits inside the operation.`,\n      });\n    }\n    // Two slots claiming one operationId in a LIVING contract. `readOpenapi`\n    // has computed this since the merge needed it, and only the feature path\n    // (coherence) ever read it — so the ambiguity was reachable only when some\n    // unrelated feature happened to carry a delta for this service, and the\n    // fleet gate that actually runs in CI was blind to it. Same code and same\n    // sentence as the feature-scope check: one breach, one name.\n    for (const id of api.duplicateIds) {\n      const slots = api.ops.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.duplicate-operationid\",\n        subject: service,\n        message: `${service}: the living OpenAPI defines operationId '${id}' at ${slots.join(\" and \")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,\n      });\n    }\n    // The contract-depth probes. Form validated and depth did not: an\n    // operation whose one response is `description: OK`, and a `$ref` to a\n    // schema nobody wrote, both read as cleanly as a complete contract while\n    // a reader still cannot rebuild its payloads. Presence\n    // probes over the document's own keys; nothing reads what a schema says.\n    const undescribed = liveOps.filter((op) => op.undescribed === true).map((op) => op.id);\n    if (undescribed.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.response-undescribed\",\n        subject: service,\n        message:\n          `${service}: ${undescribed.length} operation(s) declare no response schema (${undescribed.join(\", \")}) — ` +\n          `the contract names the operation and says nothing about what it returns, so a reader still ` +\n          `needs the code; declare content with a schema on at least one response (204/304 excepted)`,\n      });\n    }\n    if (api.danglingRefs.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.ref-unresolved\",\n        subject: service,\n        message:\n          `${service}: openapi.yaml contains ${api.danglingRefs.length} internal $ref(s) that resolve to ` +\n          `nothing in the document — the operation validates while its schema is silently absent ` +\n          `(the archive plan refuses the same breach in a feature delta, as an error)`,\n        details: api.danglingRefs,\n      });\n    }\n    const defined = new Set(ops);\n    // `Operations:` on a LIVING requirement, resolved against this service's own\n    // contract. Nothing did this before: the same spine is checked inside a\n    // feature delta (coherence's spec-api.op-undefined) and then never again, so\n    // a typo that shipped, or an operation later renamed out of openapi.yaml,\n    // left a living requirement governing an operation that does not exist —\n    // green forever, and every downstream join through that id silently empty.\n    // Same code and severity as the feature-scope check on purpose: one breach,\n    // one name, wherever it is found.\n    for (const r of livingReqs) {\n      for (const op of r.operations) {\n        if (defined.has(op)) continue;\n        const close = closeIds(op, ops);\n        findings.push({\n          severity: \"error\",\n          code: \"spec-api.op-undefined\",\n          subject: service,\n          message:\n            `${service}: requirement '${r.name}' governs '${op}', not defined in ${service}'s OpenAPI` +\n            (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n        });\n      }\n    }\n    if (ops.length > 0) {\n    const governed = new Set(livingReqs.flatMap((r) => r.operations));\n    const orphans = ops.filter((op) => !governed.has(op));\n    if (orphans.length === 0) {\n      findings.push({\n        severity: \"ok\",\n        code: \"api.covered\",\n        // Both counts on purpose: the ratio is the one signal that lets a\n        // reviewer smell a thin baseline from the summary — forty behaviours\n        // filed under one requirement passes every check, and \"covered\" alone\n        // read as done.\n        message: `${service}: API covered (${ops.length} operation(s) governed by requirements · ${livingReqs.length} living requirement(s))`,\n      });\n    } else {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ungoverned\",\n        message: `${service}: ${orphans.length} operation(s) not governed by any requirement — ${orphans.join(\", \")}`,\n      });\n    }\n    findings.push(...responseGovernanceFindings(service, liveOps, livingReqs));\n    // The migration-debt case: requirements exist, the API exists, and no\n    // `Operations:` line ties them — every cross-axis check above and in\n    // feature mode is vacuously green. Once per service, not per operation;\n    // with zero requirements the spec (or its absence) is the finding instead.\n    if (reqs.length > 0 && reqs.every((r) => r.operations.length === 0)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ops-unlinked\",\n        message: `${service}: openapi.yaml defines ${ops.length} operation(s) but no requirement links any — the API axis is unchecked for this service`,\n      });\n    }\n    // Lifecycle: a requirement whose `Operations:` list resolves ONLY to\n    // deprecated operations governs behaviour the contract is retiring.\n    // Deprecation is the documented first step of removing an op; the explicit\n    // feature marker is the final step. Until that delta archives, the op stays\n    // live, so the fix is migration or a coordinated retirement. Ops the contract does not define at all\n    // prove nothing here and are left to spec-api.op-undefined above.\n    for (const r of reqs) {\n      const resolved = r.operations.filter((op) => defined.has(op));\n      if (resolved.length === 0 || !resolved.every((op) => deprecatedOps.has(op))) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"api.requirement-deprecated\",\n        message: `${service}: requirement '${r.name}' governs only deprecated operation(s) (${resolved.join(\", \")}) — the behaviour it describes is on its way out; migrate it to the replacement operation, or retire it`,\n      });\n    }\n    }\n  }\n\n  return {\n    findings,\n    contract: { ops, deprecated: deprecatedOps, unreadable: api.unreadable || contractMissing },\n  };\n}\n\n/**\n * The build's own contract document, compared with the copy the docs repo\n * committed — `openapi.generated-stale`, `contracts.source-missing`,\n * `contracts.source-invalid`.\n *\n * WHY THIS IS NOT AN EXTRACTOR. It reads no line of service code and derives no\n * meaning: it parses a standard document the team's own build emitted, at a\n * path a human wrote into `loam.json`, and compares a digest. That is the same\n * category as `verify --results` ingesting a cucumber report, and it is the\n * only thing in the product that can notice the assumption SCHEMA quietly makes\n * — that the committed `services/<id>/openapi.yaml` is the contract the service\n * actually serves. Most fleets generate that document; a fleet that copies it\n * by hand in month one is a fleet whose spine checks grade last quarter's\n * endpoints by month six, and until now nothing could say so.\n *\n * IT NEVER WRITES. The copy stays a human `cp`, reviewed in a pull request,\n * because that is what makes the docs-repo document a contract somebody agreed\n * to rather than a cache of whatever the build last produced. loam reports the\n * divergence and stops.\n *\n * THE DIGEST IS OVER CANONICAL JSON, never raw bytes. Two generator versions\n * that order keys differently, or a YAML dumper that re-wraps a description,\n * produce identical documents and must not produce a permanent warning nobody\n * can clear — the lesson `requirementDigest` already records one package over.\n *\n * Runs only in the SERVICE repo. From the docs repo there is no build output to\n * read and the whole family stays silent, exactly as `sources` provenance does.\n */\nexport async function generatedContractFindings(\n  service: string,\n  repoDir: string,\n  spelled: string | undefined,\n  committedPath: string,\n): Promise<Finding[]> {\n  if (spelled === undefined) return [];\n  let generatedPath: string;\n  try {\n    // Containment is checked HERE rather than at config load, with the service\n    // in hand so the refusal can name it — and a path that escapes the repo is\n    // a finding, never a thrown config error that would take down every other\n    // command in the repo.\n    generatedPath = resolveInside(repoDir, spelled, `\"contracts.openapi\"`);\n  } catch (err) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-invalid\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', which does not resolve inside this repository — ` +\n        `${err instanceof Error ? err.message : String(err)}`,\n    }];\n  }\n  if (!existsSync(generatedPath)) {\n    return [{\n      severity: \"error\",\n      code: \"contracts.source-missing\",\n      subject: service,\n      message:\n        `${service}: loam.json names contracts.openapi '${spelled}', and nothing is there. ` +\n        \"Either the build has not run in this checkout, or the path is wrong — CI that validates before it builds \" +\n        \"sees exactly this. Run the build first, or correct the path\",\n    }];\n  }\n  const digests: string[] = [];\n  for (const [label, path] of [[\"generated\", generatedPath], [\"committed\", committedPath]] as const) {\n    if (label === \"committed\" && !existsSync(path)) return [];\n    let parsed: unknown;\n    try {\n      parsed = parseYaml(await readFile(path, \"utf8\"));\n    } catch (err) {\n      // An unreadable GENERATED document is this check's business; an\n      // unreadable committed one is already `openapi.invalid` and must not be\n      // reported twice under two codes.\n      if (label === \"committed\") return [];\n      return [{\n        severity: \"error\",\n        code: \"contracts.source-invalid\",\n        subject: service,\n        message:\n          `${service}: contracts.openapi '${spelled}' does not parse as YAML or JSON — ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      }];\n    }\n    digests.push(createHash(\"sha256\").update(canonicalJson(parsed), \"utf8\").digest(\"hex\"));\n  }\n  if (digests[0] === digests[1]) return [];\n  return [{\n    severity: \"warn\",\n    code: \"openapi.generated-stale\",\n    subject: service,\n    message:\n      `${service}: the committed openapi.yaml differs from what this repository's build produces (${spelled}). ` +\n      \"The docs-repo copy is what every operation join is graded against, so the fleet is being checked against a \" +\n      \"contract this service no longer serves. Review the difference and copy the generated document across — \" +\n      \"loam never does that for you, because the committed contract is one somebody agreed to, not a cache of the build\",\n  }];\n}\n"]}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The HTTP contract axis: openapi.yaml graded against the living spec.\n *\n * What it decides for everything downstream is whether there is a contract to\n * read at all. A missing or unparseable openapi.yaml is ONE finding about ONE\n * file, and that fact has to travel: grading the fleet map's inbound edges\n * against the empty operation set it leaves behind turns one broken YAML into\n * one `spine.op-undefined` per consumer, each of them accusing the landscape of\n * a fault that is not there. `ServiceContract` is how it travels; `./spine.js`\n * is what reads it.\n */\nimport { existsSync } from \"node:fs\";\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type DeclaredService, type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { responseGovernanceFindings } from \"../checks/requirements.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { readOpenapi, type OpenapiDoc } from \"../../../core/openapi/doc.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\n\n/** What the service target hands the HTTP axis. */\nexport interface ApiAxis {\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  paths: ServicePaths;\n  /** Every requirement the living spec declares, REMOVED ones included. */\n  reqs: Requirement[];\n  /** The ones that still govern something. */\n  livingReqs: Requirement[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver, built once per run; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  fleet: FleetContext;\n}\n\n/**\n * What the spine may conclude from this service's contract.\n *\n * `unreadable` covers both shapes of \"there is nothing to read\" — absent and\n * unparseable — because they have the same consequence for an inbound edge:\n * the contract proves neither that the operation exists nor that it does not.\n */\nexport interface ServiceContract {\n  /** operationIds the living contract defines, empty when there is nothing to read. */\n  ops: string[];\n  /** Those of them the contract marks `deprecated: true`. */\n  deprecated: ReadonlySet<string>;\n  unreadable: boolean;\n}\n\nexport async function apiAxisFindings(\n  axis: ApiAxis,\n): Promise<{ findings: Finding[]; contract: ServiceContract }> {\n  const { service, me, paths, reqs, livingReqs, land, landSvcOf, fleet } = axis;\n  const findings: Finding[] = [];\n\n  // API coverage: every operation in openapi.yaml is governed by a requirement.\n  const api = await readOpenapi(paths.openapi, fleet);\n  const removeMarkers = api.ops.filter((o) => o.remove);\n  const liveOps = api.ops.filter((o) => !o.remove);\n  /** No contract to read: deleted, renamed, or never written. */\n  const contractMissing = !existsSync(paths.openapi);\n  const contract = contractOf(api, contractMissing);\n  const { ops, deprecated: deprecatedOps } = contract;\n  // Inbound calls the landscape can PROVE: op-linked edges whose target\n  // resolves to this service. Null when the landscape proves nothing at all\n  // (absent, or it did not parse) — which is not the same fact as \"nobody\n  // calls me\", and the two must not be graded alike.\n  const inboundOps =\n    land === null || land.errors.length > 0\n      ? null\n      : land.relationships.filter((r) => r.op !== undefined && landSvcOf!(r.target) === me);\n  // The other half of the evidence a contract is owed: the living spec's own\n  // `Operations:` lines. A requirement on its way out governs nothing.\n  const governedOps = livingReqs.flatMap((r) => r.operations);\n  if (contractMissing) {\n    // A contract that is gone is not a reason to stop grading the API axis —\n    // it IS the axis's answer, and every check below used to live inside the\n    // file-exists branch, so deleting or misspelling the file turned the whole\n    // axis (including the documented `spec-api.op-undefined`) green.\n    //\n    // What decides the severity is whether anything already written down is\n    // holding a join into it: a living `Operations:` line, or an op-linked\n    // landscape edge. With one of those, the absence breaks a link somebody\n    // authored — an error. With neither, this is a service that legitimately\n    // has no HTTP surface (a worker nobody calls), and a fleet mid-rollout\n    // must not go red for it — a warning, or, when the landscape PROVES nobody\n    // calls it, the documented silence.\n    //\n    // One finding, not one per dangling link: the fix is a single file, and\n    // the links it strands ride along as details.\n    const dangling = [...new Set([...governedOps, ...(inboundOps ?? []).map((r) => r.op!)])].sort();\n    if (dangling.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"service.no-openapi\",\n        subject: service,\n        message:\n          `No OpenAPI contract at ${paths.openapi}, and ${dangling.length} operation link(s) already point into it — ` +\n          `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,\n        details: dangling,\n      });\n    } else if (inboundOps === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"service.no-openapi\",\n        message: `No OpenAPI contract at ${paths.openapi} — API coverage and the landscape spine are unchecked`,\n      });\n    }\n  } else if (api.unreadable) {\n    // A contract that EXISTS but does not read is a broken source of truth, not\n    // an empty one: swallowing it into zero operations used to grade every\n    // inbound landscape edge `spine.op-undefined` — a false diagnosis pointing\n    // at the landscape when the truth was this file. So the file is the error,\n    // and every check that reads the contract (api.*, the spine's op\n    // resolution) is suspended below, the landscape.invalid discipline.\n    findings.push({\n      severity: \"error\",\n      code: \"openapi.invalid\",\n      message: `${service}: openapi.yaml does not parse — API coverage and the landscape spine are unchecked`,\n      ...(api.error === undefined ? {} : { details: [api.error] }),\n    });\n  } else {\n    if (removeMarkers.length > 0) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-living\",\n        message: `${service}: living openapi.yaml contains ${removeMarkers.length} x-loam-remove marker(s) (${removeMarkers.map((op) => op.id).join(\", \")}) — removal markers are valid only in feature deltas`,\n      });\n    }\n    // The same marker written at PATH level, beside the methods. `readOpenapi`\n    // is keyed by (path, method), which is precisely why the check above cannot\n    // see this one and precisely how one reached a living contract in the first\n    // place: it addresses no operation, so it retired nothing, and it stayed\n    // invisible afterwards. Error, like its method-level sibling — a\n    // feature-only key published to every consumer of the fleet, and one that\n    // keeps the empty-path cleanup from ever firing. Same code as the archive\n    // plan's: one breach, one name, wherever it is found.\n    for (const removed of api.pathLevelRemovals) {\n      findings.push({\n        severity: \"error\",\n        code: \"openapi.remove-marker-path-level\",\n        subject: service,\n        message:\n          `${service}: living openapi.yaml carries x-loam-remove at PATH level on '${removed}' — ` +\n          `a removal marker names ONE operation, so beside the methods it retires nothing and is not a contract key either, ` +\n          `and no id-keyed check can see it. Delete it from the living contract; retire an operation through a feature delta whose marker sits inside the operation.`,\n      });\n    }\n    // Two slots claiming one operationId in a LIVING contract. `readOpenapi`\n    // has computed this since the merge needed it, and only the feature path\n    // (coherence) ever read it — so the ambiguity was reachable only when some\n    // unrelated feature happened to carry a delta for this service, and the\n    // fleet gate that actually runs in CI was blind to it. Same code and same\n    // sentence as the feature-scope check: one breach, one name.\n    for (const id of api.duplicateIds) {\n      const slots = api.ops.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.duplicate-operationid\",\n        subject: service,\n        message: `${service}: the living OpenAPI defines operationId '${id}' at ${slots.join(\" and \")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,\n      });\n    }\n    // The contract-depth probes. Form validated and depth did not: an\n    // operation whose one response is `description: OK`, and a `$ref` to a\n    // schema nobody wrote, both read as cleanly as a complete contract while\n    // a reader still cannot rebuild its payloads. Presence\n    // probes over the document's own keys; nothing reads what a schema says.\n    const undescribed = liveOps.filter((op) => op.undescribed === true).map((op) => op.id);\n    if (undescribed.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.response-undescribed\",\n        subject: service,\n        message:\n          `${service}: ${undescribed.length} operation(s) declare no response schema (${undescribed.join(\", \")}) — ` +\n          `the contract names the operation and says nothing about what it returns, so a reader still ` +\n          `needs the code; declare content with a schema on at least one response (204/304 excepted)`,\n      });\n    }\n    if (api.danglingRefs.length > 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"openapi.ref-unresolved\",\n        subject: service,\n        message:\n          `${service}: openapi.yaml contains ${api.danglingRefs.length} internal $ref(s) that resolve to ` +\n          `nothing in the document — the operation validates while its schema is silently absent ` +\n          `(the archive plan refuses the same breach in a feature delta, as an error)`,\n        details: api.danglingRefs,\n      });\n    }\n    const defined = new Set(ops);\n    // `Operations:` on a LIVING requirement, resolved against this service's own\n    // contract. Nothing did this before: the same spine is checked inside a\n    // feature delta (coherence's spec-api.op-undefined) and then never again, so\n    // a typo that shipped, or an operation later renamed out of openapi.yaml,\n    // left a living requirement governing an operation that does not exist —\n    // green forever, and every downstream join through that id silently empty.\n    // Same code and severity as the feature-scope check on purpose: one breach,\n    // one name, wherever it is found.\n    for (const r of livingReqs) {\n      for (const op of r.operations) {\n        if (defined.has(op)) continue;\n        const close = closeIds(op, ops);\n        findings.push({\n          severity: \"error\",\n          code: \"spec-api.op-undefined\",\n          subject: service,\n          message:\n            `${service}: requirement '${r.name}' governs '${op}', not defined in ${service}'s OpenAPI` +\n            (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n        });\n      }\n    }\n    if (ops.length > 0) {\n    const governed = new Set(livingReqs.flatMap((r) => r.operations));\n    const orphans = ops.filter((op) => !governed.has(op));\n    if (orphans.length === 0) {\n      findings.push({\n        severity: \"ok\",\n        code: \"api.covered\",\n        // Both counts on purpose: the ratio is the one signal that lets a\n        // reviewer smell a thin baseline from the summary — forty behaviours\n        // filed under one requirement passes every check, and \"covered\" alone\n        // read as done.\n        message: `${service}: API covered (${ops.length} operation(s) governed by requirements · ${livingReqs.length} living requirement(s))`,\n      });\n    } else {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ungoverned\",\n        message: `${service}: ${orphans.length} operation(s) not governed by any requirement — ${orphans.join(\", \")}`,\n      });\n    }\n    findings.push(...responseGovernanceFindings(service, liveOps, livingReqs));\n    // The migration-debt case: requirements exist, the API exists, and no\n    // `Operations:` line ties them — every cross-axis check above and in\n    // feature mode is vacuously green. Once per service, not per operation;\n    // with zero requirements the spec (or its absence) is the finding instead.\n    if (reqs.length > 0 && reqs.every((r) => r.operations.length === 0)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"api.ops-unlinked\",\n        message: `${service}: openapi.yaml defines ${ops.length} operation(s) but no requirement links any — the API axis is unchecked for this service`,\n      });\n    }\n    // Lifecycle: a requirement whose `Operations:` list resolves ONLY to\n    // deprecated operations governs behaviour the contract is retiring.\n    // Deprecation is the documented first step of removing an op; the explicit\n    // feature marker is the final step. Until that delta archives, the op stays\n    // live, so the fix is migration or a coordinated retirement. Ops the contract does not define at all\n    // prove nothing here and are left to spec-api.op-undefined above.\n    for (const r of reqs) {\n      const resolved = r.operations.filter((op) => defined.has(op));\n      if (resolved.length === 0 || !resolved.every((op) => deprecatedOps.has(op))) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"api.requirement-deprecated\",\n        message: `${service}: requirement '${r.name}' governs only deprecated operation(s) (${resolved.join(\", \")}) — the behaviour it describes is on its way out; migrate it to the replacement operation, or retire it`,\n      });\n    }\n    }\n  }\n\n  return { findings, contract };\n}\n\n/**\n * What the spine may conclude from one contract read — spelled once, because a\n * `--base` run now grades a changed edge against a provider it does not grade\n * as a target (`../scope.ts`), and two spellings of \"which operations are\n * live\" would be two chances for a removal marker to count as defined.\n */\nexport function contractOf(api: OpenapiDoc, missing: boolean): ServiceContract {\n  const live = api.ops.filter((o) => !o.remove);\n  return {\n    ops: live.map((o) => o.id),\n    deprecated: new Set(live.filter((o) => o.deprecated).map((o) => o.id)),\n    unreadable: api.unreadable || missing,\n  };\n}\n"]}