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

package/dist/core/vocabulary/maturity.js

@@ -40,6 +40,13 @@ export function serviceMaturity(v) {
  * What stands between this service and `vouched`, named as the thing to go and
  * do. One rung's worth at a time: telling somebody at `empty` that they also
  * need a vouch is noise, and the vouch is not even possible yet.
+ *
+ * At the top rung, the one thing a vouch can still owe: a re-vouch, when a
+ * stamped document's words moved after the person read them
+ * (`ServiceEntry.contentStale`). The RUNG does not move — the stamp is real —
+ * but "nothing missing" over words nobody has read since is the false green
+ * this list exists to prevent, and `list --needs-work`, `explore` and the
+ * context pack all read their worklist from here.
  */
 export function maturityGaps(v) {
     const s = v.entry;
@@ -54,6 +61,8 @@ export function maturityGaps(v) {
         return ["sources: in the spec.md frontmatter"];
     if (!(s.status === "verified" && s.sources.stamped))
         return [`\`loam vouch --service ${s.id}\``];
+    if (s.contentStale.length > 0)
+        return [`re-vouch (${s.contentStale.join(", ")} changed since the vouch)`];
     return [];
 }
 /** Counts per rung, every rung present — a stable shape a fleet dashboard can diff. */
@@ -70,10 +79,12 @@ export function maturityRollup(graded) {
  * C4 kinds that model people, and the tag marking an element as somebody
  * else's system. A person is never a service directory, and `#external` is
  * undocumented on purpose — every census and exemption over the fleet map
- * asks both questions.
+ * asks both questions, and `INFRA_KINDS` below is the third they now ask
+ * beside them.
  *
- * Extracted on the third strike: `commands/validate/checks/vocabulary.ts`,
- * `core/gate/partners.ts` and `core/verify/checklist.ts` each carried a copy.
+ * Extracted on the third strike: `commands/validate/checks/vocabulary.ts` (a
+ * module since deleted), `core/gate/partners.ts` and `core/verify/checklist.ts`
+ * each carried a copy.
  * Their real home is `core/c4/likec4.ts` beside the model they describe, but
  * that file sits against the 300-line limit and its package holds five files
  * — so the trio lives here, beside `landscapeEvidence`, which reads the same
@@ -88,6 +99,45 @@ export function maturityRollup(graded) {
  * in one place anyway — that list IS what the kind-tag check is about.
  */
 export const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+/**
+ * C4 kinds that model INFRASTRUCTURE the fleet runs rather than a system a team
+ * adopts. A person is never a `services/<id>/`, and neither is a datastore: a
+ * Postgres, a Kafka topic or an S3 bucket has no spec.md to write, no OpenAPI to
+ * publish, no maturity rung to climb and nobody to adopt it.
+ *
+ * The third census category, beside `ACTOR_KINDS` and `EXTERNAL_TAG`, and it
+ * exists because the fleet had only two. A store the fleet OWNS and draws at
+ * fleet level was neither a person nor somebody else's system, so it earned
+ * `landscape.service-undocumented` ("bind it with `metadata { service }`, or tag
+ * it `#external`") — two remedies, neither of them true of it — and
+ * `gate.partner-undocumented` on every service that reads it. `examples/docs`
+ * and this repo's own suite both tagged an owned Redis `#external` purely to buy
+ * that silence, which is a map that lies about ownership to satisfy a check.
+ *
+ * The LIMITATION is `ACTOR_KINDS`' exactly, and is stated here so the next
+ * reader does not have to measure it: the hook is a kind NAME, compared
+ * case-insensitively, so a fleet whose specification spells its kind `postgres`,
+ * `store` or `datastore` is not covered. That is deliberate rather than
+ * unfinished — a tag (`#infrastructure`) can be added later as a SECOND spelling
+ * without moving anything, exactly as `#external` sits beside `ACTOR_KINDS`
+ * today. An element of one of these kinds that stands for a real
+ * `services/<id>/` — a bound `database`, a title naming a directory — is a
+ * service and every reader here must say so first; the kind is the fallback,
+ * never the override.
+ */
+export const INFRA_KINDS = new Set(["database", "queue", "topic", "cache", "bucket"]);
+/**
+ * The one element kind read as a datastore, compared case-insensitively — the
+ * subject of `landscape.datastore-shared`.
+ *
+ * It was a bare string declared twice, in `commands/validate/fleet/map/consumers.ts`
+ * and `commands/validate/fleet/map/attest.ts`, each with a comment pointing at
+ * the other. Two literals free to drift about what a store IS are exactly the
+ * failure the trio above was extracted to stop: the peer census and the nested
+ * census would have graded different fleets the day one of them learned a second
+ * spelling.
+ */
+export const DATASTORE_KIND = "database";
 export const EXTERNAL_TAG = "external";
 /** Tag marking ubiquitous infrastructure; the scaffolded fleet view excludes it. */
 export const PLATFORM_TAG = "platform";

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

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

package/examples/README.md

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

package/examples/docs/architecture/landscape.likec4

@@ -34,13 +34,19 @@ specification {
   // takes the addition into that model instead, and this file never grows an
   // interior.
   element container
-  // Declared here for the SERVICE MODELS, and nothing in this file uses it: a
-  // store lives inside the service that owns it (`landscape.datastore-private`
-  // is the check that pushes one back in), so every `database` element in this
-  // fleet is written in a `services/<svc>/model.likec4` under
-  // `extend marketplace.<svc>`. An extending model declares no kinds of its
-  // own, so a kind it needs and this block does not declare is ONE parse error
-  // on the model — which is what this line prevents.
+  // Declared here for the SERVICE MODELS, and nothing in this file uses it.
+  // This fleet writes every `database` element inside the service that owns it,
+  // in a `services/<svc>/model.likec4` under `extend marketplace.<svc>` — a
+  // CHOICE this example makes, not a rule loam enforces. Drawing an owned store
+  // beside the services is equally first-class and earns no finding; what the
+  // placement decides is one thing, and it is a fact about LikeC4: a second
+  // service's edge naming `marketplace.<svc>.<store>` resolves only against a
+  // declaration the MAP holds, because a per-service project is `architecture/`
+  // plus one model. So a store a second consumer will name belongs on the map,
+  // and one nobody else reaches may live wherever the team finds it clearest.
+  // An extending model declares no kinds of its own, so a kind it needs and
+  // this block does not declare is ONE parse error on the model — which is what
+  // this line prevents.
   element database
   element person
   // A topic is an element, and the kind carries #external rather than each
@@ -79,6 +85,14 @@ specification {
   // cannot carry flattened to `-`. Declared here for the same reason — one
   // specification block serves the whole `architecture/` project.
   tag req-NOTIFY-ONCE
+  // The SUITES a flow runs with — `#suite-<name>` on the view, many-to-many, so
+  // the one journey below sits in both. Declared here, like every tag, so a
+  // mistyped suite is a parse error rather than a second, empty suite.
+  // `loam list suites` answers which services each one needs up: the union of
+  // its journeys' participants, plus the ones no services/ directory stands for
+  // (the customer who drives it, the #external topic in the middle).
+  tag suite-smoke
+  tag suite-notifications
   // An ARCHITECTURAL OBLIGATION, declared in architecture/obligations.yaml and
   // applied HERE, on the objects it holds for. The decision itself is
   // architecture/adrs/0001-transactional-outbox.md; this tag is the architect

package/examples/docs/architecture/services.likec4

@@ -0,0 +1,70 @@
+// generated by loam — one overview view per service under services/, drawn from the fleet map.
+// Do not edit: `loam subsystem sync` regenerates this file from the directories and the map,
+// and `loam validate --all` reports `subsystem.views-stale` when it drifts.
+// A navigation aid, not the fleet's architecture: author your own diagrams elsewhere.
+
+views {
+  view service_checkout_2dweb of marketplace.checkoutWeb {
+    title 'checkout-web'
+    include *
+    include customer
+    include marketplace.orderService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.checkoutWeb
+    include marketplace.checkoutWeb ->
+    include marketplace.checkoutWeb.* -> marketplace.checkoutWeb.*
+  }
+
+  view service_identity_2dservice of marketplace.identityService {
+    title 'Platform / identity-service'
+    include *
+    include marketplace.orderService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.identityService
+    include marketplace.identityService ->
+    include marketplace.identityService.* -> marketplace.identityService.*
+  }
+
+  view service_notification_2dservice of marketplace.notificationService {
+    title 'Platform / notification-service'
+    include *
+    include kafka.crmEvents
+    include kafka.orderEvents
+    include kafka.paymentEvents
+    include notificationProvider
+    exclude * -> *
+    include -> marketplace.notificationService
+    include marketplace.notificationService ->
+    include marketplace.notificationService.* -> marketplace.notificationService.*
+  }
+
+  view service_order_2dservice of marketplace.orderService {
+    title 'order-service'
+    include *
+    include kafka.orderEvents
+    include kafka.paymentEvents
+    include marketplace.checkoutWeb
+    include marketplace.identityService
+    include marketplace.paymentService
+    exclude * -> *
+    include -> marketplace.orderService
+    include marketplace.orderService ->
+    include marketplace.orderService.* -> marketplace.orderService.*
+  }
+
+  view service_payment_2dservice of marketplace.paymentService {
+    title 'payment-service'
+    include *
+    include kafka.paymentEvents
+    include marketplace.checkoutWeb
+    include marketplace.identityService
+    include marketplace.orderService
+    include stripe
+    exclude * -> *
+    include -> marketplace.paymentService
+    include marketplace.paymentService ->
+    include marketplace.paymentService.* -> marketplace.paymentService.*
+  }
+}

package/examples/docs/architecture/subsystems.likec4

@@ -11,5 +11,8 @@ views {
     description 'Cross-cutting identity and messaging'
     include marketplace.identityService
     include marketplace.notificationService
+
+    include marketplace.identityService -> *, * -> marketplace.identityService
+    include marketplace.notificationService -> *, * -> marketplace.notificationService
   }
 }

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

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

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

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

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

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

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

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

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

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

package/examples/docs/services/order-service/model.likec4

@@ -43,14 +43,16 @@ model {
       description 'Applies payment.PaymentAuthorized once per paymentId, then advances the order'
       technology 'Kotlin'
     }
-    // The store is a NESTED container of this service, never a fleet-level peer: it
-    // has exactly one consumer, so drawn beside the services in the landscape it would
-    // read as a system in its own right (`landscape.datastore-private` is the check
-    // that pushes it back in here). Nesting hides nothing — a second service reaching
-    // the same data earns `landscape.datastore-shared`, counted from that service's own
-    // model — but it does decide where the store may be written: an edge naming
-    // `marketplace.orderService.db` resolves only for a project that holds this file,
-    // so a store two services will share belongs on the map inside `marketplace.orderService`.
+    // The store is a NESTED container of this service, and that is this fleet's
+    // CHOICE rather than a rule: loam grades neither placement, and the same store
+    // drawn beside the services in the landscape earns no finding either. What the
+    // choice decides is one thing, and it is a fact about LikeC4 rather than a
+    // preference: an edge naming `marketplace.orderService.db` resolves only for a
+    // project that holds this file, and a per-service project is `architecture/`
+    // plus ONE model — so a store a second service will name belongs on the map,
+    // inside `marketplace.orderService`. Nesting hides nothing meanwhile: a second
+    // service reaching the same data earns `landscape.datastore-shared`, counted
+    // from that service's own model.
     // The `database` kind is the landscape's, declared there once for every model that needs it.
     db = database 'db' {
       description 'Orders, idempotency keys, the applied-payment ledger and the outbox table'

package/examples/docs/services/payment-service/model.likec4

@@ -24,10 +24,12 @@ model {
       description 'Payment domain logic'
       technology 'Java'
     }
-    // The store is a container of THIS service, not a fleet-level peer. Drawn
-    // in the landscape it would be a system in its own right, available to be
-    // depended on — which is the claim `landscape.datastore-private` exists to
-    // refuse when only one service reaches it.
+    // The store is a container of THIS service rather than a fleet-level peer —
+    // where a store is drawn is the team's choice and loam grades neither, so
+    // this is a decision the example makes and explains, not one it was forced
+    // into. Kept here because nothing else reaches this data: the day something
+    // does, its edge resolves only against a declaration the MAP holds, and the
+    // store moves up into `marketplace.paymentService` on the landscape.
     db = database 'db' {
       description 'Payments store'
       technology 'PostgreSQL'

package/examples/docs/services/platform/identity-service/model.likec4

@@ -39,13 +39,15 @@ model {
     // byte in here costs latency and never correctness, and ARCH-INTROSPECT-CACHE
     // in arch.spec.md is the requirement that says so in a scenario.
     //
-    // Both stores stay NESTED inside the service boundary. Lifting either into
-    // architecture/landscape.likec4 as a peer is `landscape.datastore-private`:
-    // drawn at fleet level a store reads as a system in its own right, available
-    // for somebody else's service to depend on, which is the one coupling that is
-    // hardest to undo once a second team believes the picture. The extending
-    // shape makes that the default rather than a discipline — internals are
-    // written where they belong because there is nowhere else to write them.
+    // Both stores stay NESTED inside the service boundary, and nothing makes
+    // them: loam grades neither placement, so lifting either into
+    // architecture/landscape.likec4 as a peer would earn no finding. They stay
+    // here because the extending shape makes it the cheapest default — an
+    // internal is written where the service is described, and nobody has to
+    // decide anything. The one consequence to know before choosing is about
+    // LikeC4 and not about taste: a second service's edge resolves only against
+    // a declaration the MAP holds, so a store somebody else will name goes up
+    // onto the landscape, inside `marketplace.identityService`.
     introspectionCache = container 'introspection-cache' {
       description 'Short-TTL introspection verdicts, keyed by token id'
       technology 'Redis'

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

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

package/examples/docs/services/platform/notification-service/model.likec4

@@ -25,11 +25,10 @@ model {
       technology 'Go'
     }
     // Both stores are nested INSIDE the service and neither is drawn beside it
-    // in the landscape: a store with one consumer drawn as a fleet-level peer
-    // reads as a system other services may depend on, which is what
-    // `landscape.datastore-private` pushes back on. Neither appears in
-    // health.yaml's dependencies either — they share this service's lifecycle
-    // rather than being something it reaches across a boundary.
+    // in the landscape — the example's choice, and one loam does not grade
+    // either way. Neither appears in health.yaml's dependencies either: they
+    // share this service's lifecycle rather than being something it reaches
+    // across a boundary, and that is the fact the nesting is drawn from.
     deliveryLog = database 'delivery-log' {
       description 'One row per (message id, channel) — the idempotency key that makes redelivery a no-op — carrying the orderId and customer each send was addressed to, so a receipt can find its order and a capture that arrives first has somewhere to wait'
       technology 'PostgreSQL'

package/package.json

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