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

package/examples/docs/services/order-service/arch.spec.md

@@ -25,9 +25,16 @@ this service's own `model.likec4` plus the landscape (`covers.unknown`, with a d
 hint, is the typo guard — a mistyped entry otherwise costs exactly the coverage it was written
 for), and every `slis[].name` and `alerts[].name` in `health.yaml` must be named by one of them
 (`health.uncovered`, or a signal ships to the on-call rotation with nothing testing it). Edge
-entries below are spelled as this model draws them — `orderService.outbox -> kafka.orderEvents`
-— because the endpoint that matters is the container; `order-service -> payment-service`
-resolves too, through the `metadata { service }` binding on the root element.
+entries below are spelled as this model draws them — `marketplace.orderService.outbox ->
+kafka.orderEvents` — because the endpoint that matters is the container; `order-service ->
+payment-service` resolves too, through the `metadata { service }` binding on the map's element.
+
+Element ids here carry the FULL path, `marketplace.` and all. That is a consequence of the model
+shape rather than a style: `model.likec4` extends the element the fleet map declares inside the
+`marketplace` group, so the container it adds is `marketplace.orderService.db` and no shorter
+spelling of it exists. A service whose model declares its own `specification` and is parsed alone
+mints shorter ids and writes them here — see SCHEMA.md, "Two shapes of a service model", which also
+lists requalifying these lines as a step of the migration between the two.
 
 ## Requirements
 
@@ -40,7 +47,7 @@ key rather than placing a second order or requesting a second authorization. che
 retry on a gateway timeout is not a rare path — it is the normal shape of a mobile checkout —
 and without the key a customer's flaky connection charges the card twice.
 
-Covers: orderService.db, orderService.domain -> paymentService
+Covers: marketplace.orderService.db, marketplace.orderService.domain -> marketplace.paymentService
 
 #### Scenario: checkout-web retries a placement it never saw acknowledged
 - **Given** an order placed under `Idempotency-Key` "ik-8842" with an authorization already requested
@@ -63,7 +70,7 @@ database and then to kafka. A dual write has no failure mode in which both sides
 between them either announces an order nobody stored or stores one nobody hears about, and
 notification-service is the service that pays for the second case.
 
-Covers: orderService.outbox, orderService.outbox -> kafka.orderEvents
+Covers: marketplace.orderService.outbox, marketplace.orderService.outbox -> kafka.orderEvents
 
 #### Scenario: The broker is unavailable when an order is placed
 - **Given** an accepted order whose `OrderPlaced` row is still in the outbox table
@@ -86,7 +93,7 @@ already recorded. The producer's outbox promises at-least-once delivery and a re
 redelivers whatever was in flight, so a consumer without a ledger is a consumer that confirms
 an order it already confirmed — and, once ORD-CANCEL has moved on, resurrects a cancelled one.
 
-Covers: orderService.consumer, kafka.paymentEvents -> orderService.consumer
+Covers: marketplace.orderService.consumer, kafka.paymentEvents -> marketplace.orderService.consumer
 Consumes: payment.PaymentAuthorized
 
 #### Scenario: The same authorization is redelivered after a consumer rebalance

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

@@ -1,30 +1,27 @@
-// order-service's own C4 — the model behind `services/order-service/`.
+// order-service's own C4 — what is INSIDE the element the fleet map binds to
+// services/order-service/.
 //
-// Every .likec4 file loam reads is parsed ON ITS OWN; nothing is concatenated and
-// nothing is inherited from architecture/landscape.likec4. So this document declares
-// the kinds it uses even though the landscape declares the same names: leaving them
-// out does not borrow them, it fails to parse (`c4.invalid`, an error), and the arch
-// axis, the `Covers:` resolution and health.yaml's dependency reconciliation all go
-// quiet behind that one failure.
-specification {
-  element softwareSystem
-  element container
-  element database
-  element topic
-}
-
+// This is an EXTENDING model: it declares no `specification` block, so every
+// kind and tag it uses comes from architecture/landscape.likec4, and it declares
+// no partner of its own. The map already says that order-service exists, what it
+// is called and which directory it binds to; this file says what is inside it,
+// with `extend` on the fully-qualified id the map gave that element. The id has
+// to be the full path — `extend orderService` resolves to nothing, because the
+// element is nested in the `marketplace` group.
+//
+// Nothing here re-declares kafka, payment-service or identity-service. That is
+// the whole point of the shape: the root likec4.config.json does not exclude
+// `services/**`, so the map and every model are ONE LikeC4 project, an element
+// is declared exactly once, and two documents cannot disagree about its tags or
+// its description. A PARTNER is what this file refers to and never owns — the
+// map's element, reached by the id the map spells. An element declared here
+// outside `marketplace.orderService` would be `c4.element-unowned`.
+//
+// SCHEMA.md, "Two shapes of a service model", has the other shape (a model that
+// declares its own `specification` and is parsed alone) and the recipe for
+// migrating between them.
 model {
-  orderService = softwareSystem 'order-service' {
-    description 'Owns the order lifecycle and orchestrates the payment behind it'
-    // The binding, not the title, is what ties this element to services/order-service/,
-    // and it is what every join downstream resolves through: health.yaml's dependency
-    // ids, an `arch.spec.md` edge entry written as `order-service -> payment-service`,
-    // the landscape's twin element. Rename the box without it and each of those stops
-    // matching in silence.
-    metadata {
-      service 'order-service'
-    }
-
+  extend marketplace.orderService {
     api = container 'api' {
       description 'REST API: createOrder, getOrder, cancelOrder, and the deprecated createOrderV1'
       technology 'Spring Boot'
@@ -36,7 +33,8 @@ model {
     // The two background containers exist in this model because arch.spec.md has to
     // be able to point at them: ARCH-ORD-OUTBOX and ARCH-ORD-DEDUPE cover them by id,
     // and an obligation whose subject is not modelled is an obligation no `Covers:`
-    // line can name.
+    // line can name. Written the way the map spells them —
+    // `marketplace.orderService.outbox` — because that is the id this file makes.
     outbox = container 'outbox-relay' {
       description 'Publishes committed outbox rows to order.events.v1 — at-least-once'
       technology 'Kotlin'
@@ -45,58 +43,45 @@ 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).
+    // 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'
       technology 'PostgreSQL'
     }
 
+    // The internal edges, written INSIDE the extend block, where the children
+    // resolve by their short names.
     api -> domain 'Places, reads and cancels'
     domain -> db 'Writes the order, its idempotency key and its outbox row in one transaction'
     outbox -> db 'Polls unpublished outbox rows and marks them sent'
     consumer -> db 'Records the applied paymentId, then advances the order'
   }
 
-  // Everything the service touches from outside its own boundary. The landscape
-  // carries only the boundary crossing; THIS file carries the whole reach, and it is
-  // the file `health.yaml`'s `dependencies:` are reconciled against — an id nothing
-  // here answers to is `health.dependency-unmodelled`, the check that catches a
-  // dependency the on-call file still swears by after the code stopped calling it.
-  paymentService = softwareSystem 'payment-service' {
-    description 'Authorizes and captures cards'
-    metadata {
-      service 'payment-service'
-    }
-  }
-  identityService = softwareSystem 'identity-service' {
-    description 'Issues and introspects access tokens'
-    metadata {
-      service 'identity-service'
-    }
-  }
-  kafka = softwareSystem 'kafka' {
-    description 'Event backbone (platform)'
-    // A topic per channel rather than one broker box. What a producer and a consumer
-    // actually share is the channel, and pointing every edge at the broker turns the
-    // fleet map into a star with one node in the middle the moment the fleet is
-    // bigger than this example.
-    orderEvents = topic 'order.events'
-    paymentEvents = topic 'payment.events'
-  }
-
-  // The edges, drawn from the container that really makes each call — which is the
-  // half of the truth the landscape cannot hold. A model with elements and no
-  // relationships beside a health.yaml declaring two dependencies is
-  // `c4.no-relationships`: a service that reaches nothing is almost never true.
+  // The cross-boundary edges, drawn OUTSIDE the extend block, from the container
+  // that really makes each call to the other party's element as the MAP spells
+  // it — which is the half of the truth the landscape cannot hold, since the map
+  // carries only the service-level crossing. This file names no `kafka` of its
+  // own: `kafka.orderEvents` is the map's topic, and pointing at it is what makes
+  // health.yaml's `kafka` dependency resolve (a partner brings its ancestors with
+  // it, so the broker answers even though only its topic is named).
   //
   // The `metadata` blocks below are not read for a service model — only landscape
   // edges feed `spine.op-*` and the event spine — but they are written anyway so the
   // two documents cannot drift into disagreeing about which operation and which
-  // message each edge stands for.
-  orderService.domain -> paymentService 'Calls authorizePayment' {
+  // message each edge stands for. A model with elements and no relationships beside
+  // a health.yaml declaring two dependencies is `c4.no-relationships`: a service
+  // that reaches nothing is almost never true.
+  marketplace.orderService.domain -> marketplace.paymentService 'Calls authorizePayment' {
     metadata {
       op 'authorizePayment'
     }
@@ -104,12 +89,12 @@ model {
   // ORD-CANCEL's `Requires: user/orders:cancel` has to be enforced somewhere, and this
   // is that edge: the API introspects the caller's token before it will cancel anything.
   // Drawn here and absent from health.yaml, which states the asymmetry and the reason.
-  orderService.api -> identityService 'Calls introspectToken' {
+  marketplace.orderService.api -> marketplace.identityService 'Calls introspectToken' {
     metadata {
       op 'introspectToken'
     }
   }
-  orderService.outbox -> kafka.orderEvents 'Publishes OrderPlaced' {
+  marketplace.orderService.outbox -> kafka.orderEvents 'Publishes OrderPlaced' {
     metadata {
       publishes 'order.OrderPlaced'
     }
@@ -119,7 +104,7 @@ model {
   // edge drawn the other way round binds to nothing. Nothing grades it in a
   // service model, which is exactly why it follows the same convention — a
   // reader who learns the arrow here should not have to unlearn it upstairs.
-  kafka.paymentEvents -> orderService.consumer 'PaymentAuthorized advances the order' {
+  kafka.paymentEvents -> marketplace.orderService.consumer 'PaymentAuthorized advances the order' {
     metadata {
       consumes 'payment.PaymentAuthorized'
     }
@@ -127,12 +112,15 @@ model {
 }
 
 // Views are the LikeC4 renderer's, never loam's — no check reads this block. Scoped
-// to the system, because "what does an order stand on" is this file's question and
-// the fleet-wide one is already answered in architecture/landscape.likec4.
+// to the service's element, because "what does an order stand on" is this file's
+// question and the fleet-wide one is already answered in architecture/landscape.likec4.
+// This file is part of the ROOT project, beside the map: `npx likec4 start` at the
+// docs root draws it, and there is no per-service likec4.config.json to write.
+// View ids are flat across the whole project, so this one is spelled to be unique.
 views {
-  view order_service of orderService {
+  view order_service of marketplace.orderService {
     title 'order-service — containers, its store, and what it reaches'
     include *
-    include paymentService, identityService, kafka, kafka.*
+    include marketplace.paymentService, marketplace.identityService, kafka, kafka.*
   }
 }

package/examples/docs/services/payment-service/arch.spec.md

@@ -15,9 +15,12 @@ its scenarios exercise, and `loam validate` checks every entry resolves
 (`covers.unknown`) and every declared alert/SLI is covered (`health.uncovered`).
 
 An edge entry resolves by exact element id **or** by the service an endpoint stands for, which
-is why the entries below name `payment-service` rather than `marketplace.paymentService`: the
-landscape draws this service inside a grouping element, and a `Covers:` line written against a
-group path would have to be rewritten the day somebody moves the box.
+is why the edge entries below name `payment-service` rather than `marketplace.paymentService`:
+the landscape draws this service inside a grouping element, and an edge written against a group
+path would have to be rewritten the day somebody moves the box. A CONTAINER has no such coarser
+name, so `marketplace.paymentService.outbox` is spelled in full — `model.likec4` extends the
+element the map declares inside `marketplace`, so that IS the container's id. SCHEMA.md, "Two
+shapes of a service model", has the rule and the migration step that requalifies these lines.
 
 ## Requirements
 
@@ -27,7 +30,7 @@ Requirement-ID: ARCH-PAY-OUTBOX
 The service SHALL write a domain event and the state change it reports in one
 database transaction, published to kafka by an outbox relay — never a dual write.
 
-Covers: paymentService.outbox, payment-service -> kafka.paymentEvents
+Covers: marketplace.paymentService.outbox, payment-service -> kafka.paymentEvents
 Publishes: payment.PaymentAuthorized, payment.PaymentCaptured
 
 #### Scenario: Broker down at commit time

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

@@ -1,19 +1,21 @@
-// Per-service C4. Written by an agent from the `loam adopt` brief, then curated.
+// payment-service's own C4 — what is INSIDE the element the fleet map binds to
+// services/payment-service/. Written by an agent from the `loam adopt` brief,
+// then curated.
 //
-// loam parses every `.likec4` file ALONE, so this document declares its own
-// `specification` block; a renderer handed the whole tree at once would merge
-// them and call every declaration a duplicate, which is what
-// `likec4.config.json` scopes the root project to `architecture/` for.
-specification {
-  element softwareSystem
-  element container
-  element database
-}
-
+// An EXTENDING model: no `specification` block of its own, no copy of any
+// partner. The kinds (`container`, `database`) and every element this file
+// points at are declared once in architecture/landscape.likec4, and the root
+// `likec4.config.json` does not exclude `services/**`, so the map and every
+// model are one LikeC4 project. `extend` takes the FULLY-QUALIFIED id — the
+// element is nested in the `marketplace` group, so `extend paymentService`
+// would resolve to nothing.
+//
+// There is no likec4.config.json beside this file and loam never writes one for
+// an extending model: it belongs to the root project, so `npx likec4 start` at
+// the docs root already draws it beside the map. SCHEMA.md, "Two shapes of a
+// service model", has the other shape and the migration recipe.
 model {
-  paymentService = softwareSystem 'payment-service' {
-    description 'Owns payment authorization/capture'
-
+  extend marketplace.paymentService {
     api = container 'api' {
       description 'REST API'
       technology 'Spring Boot'
@@ -22,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'
@@ -40,28 +44,25 @@ model {
     domain -> outbox 'Appends events in the state-change transaction'
   }
 
-  // The service model carries everything the service touches — cross-boundary
-  // dependencies included, drawn with the edge the service actually has. The
-  // landscape carries only the boundary crossing; health.yaml's dependencies
-  // must resolve HERE (`health.dependency-unmodelled` otherwise), which is why
-  // all three of this service's declared dependencies appear below.
-  kafka = softwareSystem 'kafka' {
-    description 'Event backbone (platform)'
-  }
-  identityService = softwareSystem 'identity-service' {
-    description 'Token validation (degradable: cached decisions carry a request)'
-  }
-  stripe = softwareSystem 'stripe' {
-    description 'Card acquirer'
-  }
-
-  paymentService.outbox -> kafka 'Relay publishes payment events'
-  paymentService.domain -> identityService 'Validates the caller token'
-  paymentService.domain -> stripe 'Authorizes and captures cards'
+  // Everything the service touches across its own boundary, drawn from the
+  // container that really touches it to the other party's element AS THE MAP
+  // SPELLS IT — never a copy of that element. The landscape carries only the
+  // service-level crossing; these three edges say which container makes it.
+  // health.yaml's three dependencies resolve through them
+  // (`health.dependency-unmodelled` otherwise): `identity-service` through the
+  // binding on the map's element, `stripe` by its id, and `kafka` because a
+  // partner brings its ancestors — the edge names the TOPIC and the broker
+  // answers for it.
+  marketplace.paymentService.outbox -> kafka.paymentEvents 'Relay publishes payment events'
+  marketplace.paymentService.domain -> marketplace.identityService 'Validates the caller token'
+  marketplace.paymentService.domain -> stripe 'Authorizes and captures cards'
 }
 
+// Views are the LikeC4 renderer's, never loam's. This file is part of the root
+// project, so `npx likec4 start` at the docs root draws this view beside the
+// fleet map with nothing else to write.
 views {
-  view payment_service of paymentService {
+  view payment_service of marketplace.paymentService {
     include *
   }
 }

package/examples/docs/services/platform/identity-service/arch.spec.md

@@ -23,8 +23,11 @@ element id, an edge `source -> target`, or a health signal `sli:<id>` / `alert:<
 is `covers.unknown` (a mistyped id silently costs exactly the coverage it was written
 for), and an SLI or alert in `health.yaml` that no requirement here covers is
 `health.uncovered`. Every id below comes from `model.likec4` or `health.yaml` in this
-directory; nothing here reaches for the landscape, because everything this service
-touches is inside its own boundary.
+directory; no entry names another service, because everything this service touches is
+inside its own boundary. The element ids carry the full `marketplace.identityService.`
+path because that is what the ids ARE: `model.likec4` extends the element the fleet map
+declares inside the `marketplace` group, so a container it adds has no shorter spelling.
+SCHEMA.md, "Two shapes of a service model", has the rule.
 
 ## Requirements
 
@@ -41,7 +44,7 @@ one a single-instance test never catches: the signer and the verifier are differ
 processes reading the same store, and a key promoted before it lands there makes
 one instance mint tokens the others report inactive.
 
-Covers: identityService.keyStore, identityService.tokens -> identityService.keyStore
+Covers: marketplace.identityService.keyStore, marketplace.identityService.tokens -> marketplace.identityService.keyStore
 
 #### Scenario: A rotation keeps tokens minted a minute earlier verifiable
 - **Given** the active key K1 and tokens issued under it with thirty minutes of life left
@@ -71,7 +74,7 @@ cache holds derived state only: losing it costs latency, never correctness, and
 design where a cache miss can produce a *different verdict* is the bug this
 requirement exists to prevent.
 
-Covers: identityService.introspectionCache, identityService.tokens -> identityService.introspectionCache
+Covers: marketplace.identityService.introspectionCache, marketplace.identityService.tokens -> marketplace.identityService.introspectionCache
 
 #### Scenario: A revocation invalidates the cached verdict immediately
 - **Given** a token whose active verdict is cached

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

@@ -1,30 +1,22 @@
-// The identity-service C4 model: the containers behind the token API and the
-// two stores they reach.
+// identity-service's own C4 — what is INSIDE the element the fleet map binds to
+// services/platform/identity-service/: the containers behind the token API and
+// the two stores they reach.
 //
-// The `specification` block is repeated in every .likec4 file on purpose. loam
-// parses each document ALONE — it never stitches this file to
-// architecture/landscape.likec4 before reading it — so a kind declared only in
-// the landscape would resolve in the LikeC4 workspace and fail here, and the
-// failure surfaces as `c4.invalid` on a file whose text looks perfect.
-specification {
-  element softwareSystem
-  element container
-  element database
-}
-
+// An EXTENDING model. There is no `specification` block here and there must not
+// be one: the kinds come from architecture/landscape.likec4, which is read as
+// part of the SAME LikeC4 project (the root `likec4.config.json` excludes
+// `**/node_modules/**` and `features/**`, and nothing under `services/`). A
+// second declaration of a kind the map already declares is a duplicate error
+// blamed on both files. `extend` takes the fully-qualified id the map minted —
+// `marketplace.identityService` — because the element is nested in the
+// `marketplace` group; `extend identityService` resolves to nothing.
+//
+// Where the service sits in the SUBSYSTEM tree changes none of this: the model
+// is found by walking `services/`, and `services/platform/` is a grouping
+// directory, never part of any id. SCHEMA.md, "Two shapes of a service model",
+// has the standalone shape and the recipe for migrating a model to this one.
 model {
-  identityService = softwareSystem 'identity-service' {
-    description 'Issues the access tokens the rest of the fleet presents, and answers whether one is still good'
-    // The binding — not the title — is what ties this element to
-    // services/identity-service/. With a title alone, renaming the box to
-    // 'Identity' would silently stop every join that reads this file (health
-    // dependencies, `Covers:` entries, the landscape spine) while `loam
-    // validate` stayed green, because a title that fails to match is only a
-    // guess at a binding and is graded as one.
-    metadata {
-      service 'identity-service'
-    }
-
+  extend marketplace.identityService {
     api = container 'api' {
       description 'HTTP surface: POST /tokens, POST /tokens/introspect, GET /tokens/{token}/valid'
       technology 'Go'
@@ -47,11 +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.
+    // 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'
@@ -61,11 +57,12 @@ model {
     // These three edges are the WHOLE runtime graph of this service:
     // identity-service is the fleet's root of trust and calls nothing outside
     // its own boundary, which is why health.yaml carries no `dependencies:`
-    // key. They still have to be drawn — with four nested elements and no edge
-    // joining any of them this model is `c4.no-relationships`, on the grounds
-    // that parts which reach nothing are almost never the truth. (The check is
-    // evidence-gated: one lone container proves nothing and stays silent, which
-    // is why the warning is about a model this shape and not about any model.)
+    // key, and why this model draws no cross-boundary edge at all. They still
+    // have to be drawn — with four nested elements and no edge joining any of
+    // them this model is `c4.no-relationships`, on the grounds that parts which
+    // reach nothing are almost never the truth. (The check is evidence-gated:
+    // one lone container proves nothing and stays silent, which is why the
+    // warning is about a model this shape and not about any model.)
     tokens -> keyStore 'Signs with the active key; rotation promotes the next; introspection reads keys and revocations back'
     tokens -> introspectionCache 'Caches introspection verdicts, invalidates on revocation'
   }
@@ -74,9 +71,10 @@ model {
 // Views belong to LikeC4's renderer; no loam check reads anything below. One
 // view is enough here because the whole model fits inside one boundary — the
 // landscape splits its views only because a fleet-wide `include *` is the page
-// nobody can read.
+// nobody can read. View ids are flat across the whole project now that the map
+// and every model share one, so this one is spelled to be unique.
 views {
-  view identity_service of identityService {
+  view identity_service of marketplace.identityService {
     title 'identity-service — containers'
     include *
   }

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/health.yaml

@@ -25,9 +25,14 @@ checks:
   liveness: GET /internal/health/liveness
   readiness: GET /internal/health/readiness    # consumer group joined + both stores reachable
 dependencies:
-  # Resolved against services/notification-service/model.likec4 and never the
-  # landscape (`health.dependency-unmodelled` when nothing there answers to the
-  # name). The delivery log and the contact store are absent on purpose: both
+  # Resolved against services/platform/notification-service/model.likec4 — this
+  # service's own model, never the fleet map read on its own
+  # (`health.dependency-unmodelled` when nothing there answers to the name).
+  # That model EXTENDS the map, so what answers is its own slice: the elements
+  # it adds, plus the partners it points at and their ancestors. `kafka` below
+  # resolves through the second half — the edges name `kafka.orderEvents` and
+  # the broker that owns the topic comes with it.
+  # The delivery log and the contact store are absent on purpose: both
   # are nested inside the service element and share its lifecycle, so they are
   # blast radius rather than dependency — identity-service's health.yaml states
   # the same rule for its two stores.