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

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

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

package/dist/core/vocabulary/maturity.js

@@ -0,0 +1,216 @@
+/** The ladder, in order. Each rung stands on every rung below it. */
+export const MATURITY_LADDER = ["empty", "partial", "documented", "sourced", "vouched"];
+/**
+ * How far a service's documentation has got. Derived from artifact PRESENCE and
+ * provenance state only — the data an enumeration already holds — never from
+ * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the
+ * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of
+ * thirty climbs this ladder exactly as fast as a thorough one, which is why no
+ * rung is called "adopted".
+ *
+ *   empty       services/<id>/ exists, no artifact is in it
+ *   partial     some artifacts, but not the required set
+ *   documented  the artifacts the adopt brief marks required are present
+ *   sourced     the living spec declares `sources` — something ties it to code
+ *   vouched     status: verified with a sources_digest behind it — a person
+ *               stamped it. `verified` with no digest is a claim with nothing
+ *               behind it and stays below this rung.
+ *
+ * A spec.md marked `adoption: partial` does not count toward `documented`.
+ * That marker is not a completeness grade — completeness stays unchecked, as
+ * above — but a PROVENANCE fact: `loam archive` wrote the file from one
+ * feature's slice into a service that existed and was never adopted, so the
+ * document says what that feature added and nothing about what the service
+ * already did. Counting it made one archive move a service from `partial` to
+ * `documented` with no adoption having happened.
+ *
+ * `openapi.yaml` is required ONLY where an API is expected. The rung used to
+ * demand it of everything, which permanently pinned every worker, cron and
+ * consumer in the fleet at `partial` — services that are fully documented and
+ * vouched for, reported as unfinished forever, leaving the rollup permanently
+ * below its true documentation state. The evidence is the same one
+ * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be
+ * green in one command and unfinished in the other.
+ */
+export function serviceMaturity(v) {
+    const s = v.entry;
+    if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0)
+        return "empty";
+    if (!(s.has.model && s.has.spec && s.adoption === null && (!v.apiExpected || s.has.openapi)))
+        return "partial";
+    if (!s.sources.declared)
+        return "documented";
+    if (!(s.status === "verified" && s.sources.stamped))
+        return "sourced";
+    return "vouched";
+}
+/**
+ * What stands between this service and `vouched`, named as the thing to go and
+ * do. One rung's worth at a time: telling somebody at `empty` that they also
+ * need a vouch is noise, and the vouch is not even possible yet.
+ *
+ * At the top rung, the one thing a vouch can still owe: a re-vouch, when a
+ * stamped document's words moved after the person read them
+ * (`ServiceEntry.contentStale`). The RUNG does not move — the stamp is real —
+ * but "nothing missing" over words nobody has read since is the false green
+ * this list exists to prevent, and `list --needs-work`, `explore` and the
+ * context pack all read their worklist from here.
+ */
+export function maturityGaps(v) {
+    const s = v.entry;
+    const files = [
+        ...(s.has.model ? [] : ["model.likec4"]),
+        ...(s.has.spec ? [] : ["spec.md"]),
+        // Named as the step that discharges it, because the file it is about is
+        // already there: what is missing is the adoption, not the document.
+        ...(s.has.spec && s.adoption !== null ? [`\`loam adopt --service ${s.id}\` (spec.md is adoption: partial — one feature's slice)`] : []),
+        ...(v.apiExpected && !s.has.openapi ? ["openapi.yaml"] : []),
+    ];
+    if (files.length > 0)
+        return files;
+    if (!s.sources.declared)
+        return ["sources: in the spec.md frontmatter"];
+    if (!(s.status === "verified" && s.sources.stamped))
+        return [`\`loam vouch --service ${s.id}\``];
+    if (s.contentStale.length > 0)
+        return [`re-vouch (${s.contentStale.join(", ")} changed since the vouch)`];
+    return [];
+}
+/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */
+export function maturityRollup(graded) {
+    const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0]));
+    for (const v of graded)
+        out[v.maturity] += 1;
+    return out;
+}
+/* ------------------------------------------------------------------ */
+/* What the fleet map proves about one service                         */
+/* ------------------------------------------------------------------ */
+/**
+ * C4 kinds that model people, and the tag marking an element as somebody
+ * else's system. A person is never a service directory, and `#external` is
+ * undocumented on purpose — every census and exemption over the fleet map
+ * asks both questions, and `INFRA_KINDS` below is the third they now ask
+ * beside them.
+ *
+ * Extracted on the third strike: `commands/validate/checks/vocabulary.ts` (a
+ * module since deleted), `core/gate/partners.ts` and `core/verify/checklist.ts`
+ * each carried a copy.
+ * Their real home is `core/c4/likec4.ts` beside the model they describe, but
+ * that file sits against the 300-line limit and its package holds five files
+ * — so the trio lives here, beside `landscapeEvidence`, which reads the same
+ * map for the same per-service questions.
+ *
+ * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,
+ * where it was declared beside its one reader. It moved for the rule above the
+ * others came for: `fleet/kind-tags.ts` needs to know which tag names loam
+ * grades on, and reaching into fleet-shape.ts for a five-character constant
+ * would import a module that reads permissions, capabilities and every
+ * service's requirements to get it. The two tags loam gives meaning to belong
+ * in one place anyway — that list IS what the kind-tag check is about.
+ */
+export const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+/**
+ * C4 kinds that model INFRASTRUCTURE the fleet runs rather than a system a team
+ * adopts. A person is never a `services/<id>/`, and neither is a datastore: a
+ * Postgres, a Kafka topic or an S3 bucket has no spec.md to write, no OpenAPI to
+ * publish, no maturity rung to climb and nobody to adopt it.
+ *
+ * The third census category, beside `ACTOR_KINDS` and `EXTERNAL_TAG`, and it
+ * exists because the fleet had only two. A store the fleet OWNS and draws at
+ * fleet level was neither a person nor somebody else's system, so it earned
+ * `landscape.service-undocumented` ("bind it with `metadata { service }`, or tag
+ * it `#external`") — two remedies, neither of them true of it — and
+ * `gate.partner-undocumented` on every service that reads it. `examples/docs`
+ * and this repo's own suite both tagged an owned Redis `#external` purely to buy
+ * that silence, which is a map that lies about ownership to satisfy a check.
+ *
+ * The LIMITATION is `ACTOR_KINDS`' exactly, and is stated here so the next
+ * reader does not have to measure it: the hook is a kind NAME, compared
+ * case-insensitively, so a fleet whose specification spells its kind `postgres`,
+ * `store` or `datastore` is not covered. That is deliberate rather than
+ * unfinished — a tag (`#infrastructure`) can be added later as a SECOND spelling
+ * without moving anything, exactly as `#external` sits beside `ACTOR_KINDS`
+ * today. An element of one of these kinds that stands for a real
+ * `services/<id>/` — a bound `database`, a title naming a directory — is a
+ * service and every reader here must say so first; the kind is the fallback,
+ * never the override.
+ */
+export const INFRA_KINDS = new Set(["database", "queue", "topic", "cache", "bucket"]);
+/**
+ * The one element kind read as a datastore, compared case-insensitively — the
+ * subject of `landscape.datastore-shared`.
+ *
+ * It was a bare string declared twice, in `commands/validate/fleet/map/consumers.ts`
+ * and `commands/validate/fleet/map/attest.ts`, each with a comment pointing at
+ * the other. Two literals free to drift about what a store IS are exactly the
+ * failure the trio above was extracted to stop: the peer census and the nested
+ * census would have graded different fleets the day one of them learned a second
+ * spelling.
+ */
+export const DATASTORE_KIND = "database";
+export const EXTERNAL_TAG = "external";
+/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */
+export const PLATFORM_TAG = "platform";
+/**
+ * The tags loam GRADES on, as opposed to the ones it merely carries.
+ *
+ * A tag in this list changes what loam concludes about a fleet: `#external`
+ * exempts an element from the landscape↔services reconciliation entirely, and
+ * `#platform` silences the hub warning. Every other tag on an element is the
+ * author's own vocabulary and loam does not read it.
+ *
+ * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND
+ * — `specification { element softwareSystem { #external } }` — and LikeC4
+ * applies it to every element of that kind. A kind-wide declaration of a tag on
+ * this list switches loam's grading off for the whole fleet at once, which is
+ * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare
+ * kind-wide, so the check must ask exactly this question and no broader one.
+ */
+export const GRADED_TAGS = [EXTERNAL_TAG, PLATFORM_TAG];
+/**
+ * The fleet map's evidence about one service: the edges into and out of it,
+ * whether the map draws it at all, and whether an API is expected of it.
+ *
+ * One spelling, because it had grown three. `explore`'s describe and the
+ * context pack's living slice partitioned the same relationships with the
+ * same positive-evidence rule line for line — an inbound edge carrying an
+ * operation proves somebody calls the service; a landscape that is absent or
+ * does not parse proves NOTHING about who calls it, so the contract is still
+ * owed — and a rule spelled twice is how the same service grades `partial` in
+ * one command and `documented` in another. `list`'s serviceViews
+ * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —
+ * a single `called` set for every service, not a partition per service —
+ * so that spelling deliberately stays there, cross-referenced from both
+ * sides: calling this per service inside a fleet loop would re-walk the
+ * whole relationship list once per service.
+ */
+export function landscapeEvidence(req) {
+    const { id, parses, relationships, svcOf } = req;
+    const inbound = [];
+    const outbound = [];
+    for (const r of relationships) {
+        // An edge whose BOTH endpoints resolve to this service is its own internal
+        // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own
+        // caller — `← <id> "reads"` in `loam context` (verification 2026-09-04) —
+        // and, through `apiExpected` below, told a service nobody calls that it owed
+        // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same
+        // reason. It still TOUCHES the service, which is why the brief's `touched`
+        // and `landscape.service-isolated` read the relationships rather than these
+        // two lists.
+        if (svcOf(r.source) === id && svcOf(r.target) === id)
+            continue;
+        const edge = { op: r.op ?? null, title: r.title ?? null };
+        if (svcOf(r.target) === id)
+            inbound.push({ service: svcOf(r.source), ...edge });
+        else if (svcOf(r.source) === id)
+            outbound.push({ service: svcOf(r.target), ...edge });
+    }
+    return {
+        inbound,
+        outbound,
+        modelled: req.elementIds.some((e) => svcOf(e) === id),
+        apiExpected: !parses || inbound.some((e) => e.op !== null),
+    };
+}
+//# sourceMappingURL=maturity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"maturity.js","sourceRoot":"","sources":["../../../src/core/vocabulary/maturity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption-maturity ladder: one monotone word for how far a service's\n * documentation has got, and what stands between it and the next rung.\n *\n * This lived inside `commands/list.ts` while `list` was the only caller. It\n * moved here when `explore` needed the same answer, because the alternative is\n * the failure `core/kernel/ids/service.ts` already records for the service-id grammar: a\n * second, subtly different copy, so two commands grade the same directory\n * differently and nobody can tell which one is lying. The rung is a fleet dial\n * — `list` prints it per service and in a rollup, `explore` prints it for a\n * service somebody is about to build against — and a dial with two readings is\n * not a dial.\n */\nimport type { ServiceEntry } from \"../repo/entries.js\";\n\n/** The ladder, in order. Each rung stands on every rung below it. */\nexport const MATURITY_LADDER = [\"empty\", \"partial\", \"documented\", \"sourced\", \"vouched\"] as const;\nexport type Maturity = (typeof MATURITY_LADDER)[number];\n\n/**\n * A service entry plus the two facts the directory enumeration cannot know on\n * its own. Both change what a rung MEANS, and both are fleet-level: they need\n * the landscape, not `services/<id>/`.\n */\nexport interface MaturityInput {\n  entry: ServiceEntry;\n  /** `arch.spec.md` — the architecture-obligations axis, absent from ServiceEntry.has. */\n  archSpec: boolean;\n  /**\n   * Does anything in the fleet call an operation on this service? True unless\n   * the landscape PROVES otherwise, exactly as `validate`'s no-openapi grace\n   * reads it: a missing or unparseable landscape proves nothing.\n   */\n  apiExpected: boolean;\n}\n\n/**\n * How far a service's documentation has got. Derived from artifact PRESENCE and\n * provenance state only — the data an enumeration already holds — never from\n * what the artifacts say. COMPLETENESS of adopted docs is explicitly on the\n * unchecked list (brief/unchecked.ts): a service with one endpoint documented out of\n * thirty climbs this ladder exactly as fast as a thorough one, which is why no\n * rung is called \"adopted\".\n *\n *   empty       services/<id>/ exists, no artifact is in it\n *   partial     some artifacts, but not the required set\n *   documented  the artifacts the adopt brief marks required are present\n *   sourced     the living spec declares `sources` — something ties it to code\n *   vouched     status: verified with a sources_digest behind it — a person\n *               stamped it. `verified` with no digest is a claim with nothing\n *               behind it and stays below this rung.\n *\n * A spec.md marked `adoption: partial` does not count toward `documented`.\n * That marker is not a completeness grade — completeness stays unchecked, as\n * above — but a PROVENANCE fact: `loam archive` wrote the file from one\n * feature's slice into a service that existed and was never adopted, so the\n * document says what that feature added and nothing about what the service\n * already did. Counting it made one archive move a service from `partial` to\n * `documented` with no adoption having happened.\n *\n * `openapi.yaml` is required ONLY where an API is expected. The rung used to\n * demand it of everything, which permanently pinned every worker, cron and\n * consumer in the fleet at `partial` — services that are fully documented and\n * vouched for, reported as unfinished forever, leaving the rollup permanently\n * below its true documentation state. The evidence is the same one\n * `validate` uses to keep `service.no-openapi` quiet, so a service cannot be\n * green in one command and unfinished in the other.\n */\nexport function serviceMaturity(v: MaturityInput): Maturity {\n  const s = v.entry;\n  if (!Object.values(s.has).some(Boolean) && !v.archSpec && s.adrs === 0) return \"empty\";\n  if (!(s.has.model && s.has.spec && s.adoption === null && (!v.apiExpected || s.has.openapi))) return \"partial\";\n  if (!s.sources.declared) return \"documented\";\n  if (!(s.status === \"verified\" && s.sources.stamped)) return \"sourced\";\n  return \"vouched\";\n}\n\n/**\n * What stands between this service and `vouched`, named as the thing to go and\n * do. One rung's worth at a time: telling somebody at `empty` that they also\n * need a vouch is noise, and the vouch is not even possible yet.\n *\n * At the top rung, the one thing a vouch can still owe: a re-vouch, when a\n * stamped document's words moved after the person read them\n * (`ServiceEntry.contentStale`). The RUNG does not move — the stamp is real —\n * but \"nothing missing\" over words nobody has read since is the false green\n * this list exists to prevent, and `list --needs-work`, `explore` and the\n * context pack all read their worklist from here.\n */\nexport function maturityGaps(v: MaturityInput): string[] {\n  const s = v.entry;\n  const files = [\n    ...(s.has.model ? [] : [\"model.likec4\"]),\n    ...(s.has.spec ? [] : [\"spec.md\"]),\n    // Named as the step that discharges it, because the file it is about is\n    // already there: what is missing is the adoption, not the document.\n    ...(s.has.spec && s.adoption !== null ? [`\\`loam adopt --service ${s.id}\\` (spec.md is adoption: partial — one feature's slice)`] : []),\n    ...(v.apiExpected && !s.has.openapi ? [\"openapi.yaml\"] : []),\n  ];\n  if (files.length > 0) return files;\n  if (!s.sources.declared) return [\"sources: in the spec.md frontmatter\"];\n  if (!(s.status === \"verified\" && s.sources.stamped)) return [`\\`loam vouch --service ${s.id}\\``];\n  if (s.contentStale.length > 0) return [`re-vouch (${s.contentStale.join(\", \")} changed since the vouch)`];\n  return [];\n}\n\n/** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */\nexport function maturityRollup(graded: readonly { maturity: Maturity }[]): Record<Maturity, number> {\n  const out = Object.fromEntries(MATURITY_LADDER.map((m) => [m, 0])) as Record<Maturity, number>;\n  for (const v of graded) out[v.maturity] += 1;\n  return out;\n}\n\n/* ------------------------------------------------------------------ */\n/* What the fleet map proves about one service                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * C4 kinds that model people, and the tag marking an element as somebody\n * else's system. A person is never a service directory, and `#external` is\n * undocumented on purpose — every census and exemption over the fleet map\n * asks both questions, and `INFRA_KINDS` below is the third they now ask\n * beside them.\n *\n * Extracted on the third strike: `commands/validate/checks/vocabulary.ts` (a\n * module since deleted), `core/gate/partners.ts` and `core/verify/checklist.ts`\n * each carried a copy.\n * Their real home is `core/c4/likec4.ts` beside the model they describe, but\n * that file sits against the 300-line limit and its package holds five files\n * — so the trio lives here, beside `landscapeEvidence`, which reads the same\n * map for the same per-service questions.\n *\n * `PLATFORM_TAG` joined them from `commands/validate/checks/fleet-shape.ts`,\n * where it was declared beside its one reader. It moved for the rule above the\n * others came for: `fleet/kind-tags.ts` needs to know which tag names loam\n * grades on, and reaching into fleet-shape.ts for a five-character constant\n * would import a module that reads permissions, capabilities and every\n * service's requirements to get it. The two tags loam gives meaning to belong\n * in one place anyway — that list IS what the kind-tag check is about.\n */\nexport const ACTOR_KINDS = new Set([\"person\", \"actor\", \"user\"]);\n\n/**\n * C4 kinds that model INFRASTRUCTURE the fleet runs rather than a system a team\n * adopts. A person is never a `services/<id>/`, and neither is a datastore: a\n * Postgres, a Kafka topic or an S3 bucket has no spec.md to write, no OpenAPI to\n * publish, no maturity rung to climb and nobody to adopt it.\n *\n * The third census category, beside `ACTOR_KINDS` and `EXTERNAL_TAG`, and it\n * exists because the fleet had only two. A store the fleet OWNS and draws at\n * fleet level was neither a person nor somebody else's system, so it earned\n * `landscape.service-undocumented` (\"bind it with `metadata { service }`, or tag\n * it `#external`\") — two remedies, neither of them true of it — and\n * `gate.partner-undocumented` on every service that reads it. `examples/docs`\n * and this repo's own suite both tagged an owned Redis `#external` purely to buy\n * that silence, which is a map that lies about ownership to satisfy a check.\n *\n * The LIMITATION is `ACTOR_KINDS`' exactly, and is stated here so the next\n * reader does not have to measure it: the hook is a kind NAME, compared\n * case-insensitively, so a fleet whose specification spells its kind `postgres`,\n * `store` or `datastore` is not covered. That is deliberate rather than\n * unfinished — a tag (`#infrastructure`) can be added later as a SECOND spelling\n * without moving anything, exactly as `#external` sits beside `ACTOR_KINDS`\n * today. An element of one of these kinds that stands for a real\n * `services/<id>/` — a bound `database`, a title naming a directory — is a\n * service and every reader here must say so first; the kind is the fallback,\n * never the override.\n */\nexport const INFRA_KINDS = new Set([\"database\", \"queue\", \"topic\", \"cache\", \"bucket\"]);\n\n/**\n * The one element kind read as a datastore, compared case-insensitively — the\n * subject of `landscape.datastore-shared`.\n *\n * It was a bare string declared twice, in `commands/validate/fleet/map/consumers.ts`\n * and `commands/validate/fleet/map/attest.ts`, each with a comment pointing at\n * the other. Two literals free to drift about what a store IS are exactly the\n * failure the trio above was extracted to stop: the peer census and the nested\n * census would have graded different fleets the day one of them learned a second\n * spelling.\n */\nexport const DATASTORE_KIND = \"database\";\nexport const EXTERNAL_TAG = \"external\";\n/** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */\nexport const PLATFORM_TAG = \"platform\";\n\n/**\n * The tags loam GRADES on, as opposed to the ones it merely carries.\n *\n * A tag in this list changes what loam concludes about a fleet: `#external`\n * exempts an element from the landscape↔services reconciliation entirely, and\n * `#platform` silences the hub warning. Every other tag on an element is the\n * author's own vocabulary and loam does not read it.\n *\n * The list exists because since LikeC4 1.59.0 a tag can be declared on a KIND\n * — `specification { element softwareSystem { #external } }` — and LikeC4\n * applies it to every element of that kind. A kind-wide declaration of a tag on\n * this list switches loam's grading off for the whole fleet at once, which is\n * what `kindTagFindings` refuses. A tag NOT on this list is safe to declare\n * kind-wide, so the check must ask exactly this question and no broader one.\n */\nexport const GRADED_TAGS: readonly string[] = [EXTERNAL_TAG, PLATFORM_TAG];\n\n/** One end of a call the fleet map draws, as every per-service view spells it. */\nexport interface LandscapeEdge {\n  service: string;\n  op: string | null;\n  title: string | null;\n}\n\n/**\n * The slice of a parsed relationship the partition reads. Structural on\n * purpose — the smallest parameter type the derivation needs — so this module\n * stays a leaf: `core/c4/likec4.ts`'s `Rel` satisfies it without an import\n * edge from the vocabulary package into the parser.\n */\nexport interface EdgeSource {\n  source: string;\n  target: string;\n  op?: string;\n  title?: string;\n}\n\nexport interface LandscapeEvidenceRequest {\n  /** The service being asked about. */\n  id: string;\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  /** The parsed relationships; empty when the landscape is absent or unparseable. */\n  relationships: readonly EdgeSource[];\n  /** Every element id in the map, for the `modelled` probe. */\n  elementIds: readonly string[];\n  /** The shared resolver (`core/c4/resolve/service.ts` `serviceResolver`), widened to plain strings. */\n  svcOf: (id: string) => string;\n}\n\nexport interface LandscapeEvidence {\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Whether anything in the fleet map resolves to this service. */\n  modelled: boolean;\n  /** The `apiExpected` input the ladder above consumes. */\n  apiExpected: boolean;\n}\n\n/**\n * The fleet map's evidence about one service: the edges into and out of it,\n * whether the map draws it at all, and whether an API is expected of it.\n *\n * One spelling, because it had grown three. `explore`'s describe and the\n * context pack's living slice partitioned the same relationships with the\n * same positive-evidence rule line for line — an inbound edge carrying an\n * operation proves somebody calls the service; a landscape that is absent or\n * does not parse proves NOTHING about who calls it, so the contract is still\n * owed — and a rule spelled twice is how the same service grades `partial` in\n * one command and `documented` in another. `list`'s serviceViews\n * (`commands/list/views.ts`) derives the same rule fleet-wide in ONE pass —\n * a single `called` set for every service, not a partition per service —\n * so that spelling deliberately stays there, cross-referenced from both\n * sides: calling this per service inside a fleet loop would re-walk the\n * whole relationship list once per service.\n */\nexport function landscapeEvidence(req: LandscapeEvidenceRequest): LandscapeEvidence {\n  const { id, parses, relationships, svcOf } = req;\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of relationships) {\n    // An edge whose BOTH endpoints resolve to this service is its own internal\n    // wiring (`svc.web -> svc.db`): filed as inbound it made the service its own\n    // caller — `← <id> \"reads\"` in `loam context` (verification 2026-09-04) —\n    // and, through `apiExpected` below, told a service nobody calls that it owed\n    // an OpenAPI contract. `core/brief/landscape.ts` drops it for the same\n    // reason. It still TOUCHES the service, which is why the brief's `touched`\n    // and `landscape.service-isolated` read the relationships rather than these\n    // two lists.\n    if (svcOf(r.source) === id && svcOf(r.target) === id) continue;\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === id) inbound.push({ service: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === id) outbound.push({ service: svcOf(r.target), ...edge });\n  }\n  return {\n    inbound,\n    outbound,\n    modelled: req.elementIds.some((e) => svcOf(e) === id),\n    apiExpected: !parses || inbound.some((e) => e.op !== null),\n  };\n}\n"]}

package/dist/core/vocabulary/report.js

@@ -0,0 +1,90 @@
+/**
+ * The validation report — what `loam validate` produces before anything is
+ * printed.
+ *
+ * Checks build findings; renderers turn them into a human view or into the JSON
+ * contract. Keeping the two apart is what makes `--all` and `--json` possible
+ * without a second implementation of every check, and it is why a finding
+ * carries a stable `code`: prose is for people, codes are for callers.
+ */
+/**
+ * The glyph each severity is printed with. Five sites had written it out
+ * themselves — four as a two-armed ternary that spelled `error` and let
+ * everything else fall to ⚠ — and a reader who learns the marks from one
+ * command's output has to be able to read them in the next. It lives beside
+ * `Severity` because it is a fact about the union, not about any one renderer;
+ * `TextHint.marker` below is the switch that prints it, or a different mark.
+ */
+export const SEVERITY_MARK = { ok: "✓", warn: "⚠", error: "✗" };
+/**
+ * The glyph for an `ok` finding whose check did NOT run here — printed in
+ * place of ✓, never in place of ⚠ or ✗.
+ *
+ * Not a fourth severity, on purpose: `sources.unverifiable-from-here` is `ok`
+ * because nothing is wrong with the docs, and a severity of its own would move
+ * the footer's counts, `--strict` and the frozen `--json` vocabulary for what
+ * is only a question of how the line reads. But ✓ is the one mark that says
+ * "checked, fine", and a person reading a docs-repo run saw a column of them
+ * beside the sentence "nothing here can resolve them" — a pass for a check
+ * that was skipped. Defined here beside SEVERITY_MARK for the same reason that
+ * table is: a reader who learns it from one command must be able to read it in
+ * the next.
+ */
+export const NOT_CHECKED_MARK = "○";
+/** A target is valid when nothing in it is an error. Warnings never gate. */
+export function targetValid(target) {
+    return !target.findings.some((f) => f.severity === "error");
+}
+export function reportValid(targets) {
+    return targets.every(targetValid);
+}
+export function countSeverity(targets, severity) {
+    return targets.reduce((n, t) => n + t.findings.filter((f) => f.severity === severity).length, 0);
+}
+/**
+ * DISTINCT subjects carrying a finding with `code`, across the whole report.
+ *
+ * By SUBJECT, not by finding, and that is the rule every rollup derived from
+ * findings must share: one service can raise the same code from two documents
+ * — each document has its own list and its own answer — but it is one service,
+ * and a count of findings sends the reader looking for services that do not
+ * exist. A finding that names no subject is about its target, so the target id
+ * is the fallback key.
+ */
+export function subjectsWith(targets, code) {
+    return new Set(targets.flatMap((t) => t.findings.filter((f) => f.code === code).map((f) => f.subject ?? t.id))).size;
+}
+export function findingJson(f, fallback) {
+    return {
+        severity: f.severity,
+        code: f.code,
+        ...(f.subject === undefined ? {} : { subject: f.subject }),
+        ...(f.gates === undefined ? {} : { gates: f.gates }),
+        message: f.message,
+        details: f.details ?? [],
+        locations: f.locations ?? (fallback === undefined ? [] : [fallback]),
+    };
+}
+function targetScope(t) {
+    const path = t.path ??
+        (t.kind === "service"
+            ? `services/${t.id}`
+            : t.kind === "feature"
+                ? "features"
+                : "architecture/landscape.likec4");
+    return {
+        path,
+        role: t.kind === "landscape" ? "primary" : "scope",
+        ...(t.kind === "feature" && t.path === undefined ? { pointer: t.id } : {}),
+    };
+}
+export function targetJson(t) {
+    return {
+        kind: t.kind,
+        id: t.id,
+        ...(t.path === undefined ? {} : { path: t.path }),
+        valid: targetValid(t),
+        findings: t.findings.map((finding) => findingJson(finding, targetScope(t))),
+    };
+}
+//# sourceMappingURL=report.js.map

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

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