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

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'
@@ -48,55 +46,40 @@ model {
     // 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).
+    // 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 `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 +87,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 +102,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 +110,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'
@@ -40,28 +42,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'
@@ -51,7 +43,9 @@ model {
     // 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.
+    // 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.
     introspectionCache = container 'introspection-cache' {
       description 'Short-TTL introspection verdicts, keyed by token id'
       technology 'Redis'
@@ -61,11 +55,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 +69,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/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.

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

@@ -1,35 +1,21 @@
-// Per-service C4. Written by an agent from the `loam adopt` brief, then curated.
+// notification-service's own C4 — what is INSIDE the element the fleet map binds
+// to services/platform/notification-service/. Written by an agent from the
+// `loam adopt` brief, then curated.
 //
-// Every .likec4 file is parsed ALONE, so the kinds this document uses have to be
-// declared in this document: a `specification` block here is not a duplicate of
-// the landscape's, it is what makes this file readable without it.
-specification {
-  element softwareSystem
-  element container
-  element database
-  // Declared because the consumption edges below point at CHANNELS rather than
-  // at the broker. Three edges into one `kafka` box would say only "talks to
-  // kafka"; three edges into three topics say which contracts this service is
-  // standing on, and they line up one-for-one with the channels in
-  // asyncapi.yaml.
-  element topic {
-    style {
-      shape queue
-    }
-  }
-}
-
+// An EXTENDING model: no `specification` block, no partner copies. The topics
+// this service consumes — `kafka.orderEvents`, `kafka.paymentEvents`,
+// `kafka.crmEvents` — are the MAP's, declared there once with the `topic` kind
+// that carries `#external` and `#platform`; this file points at them. So is
+// `notificationProvider`, the third-party gateway: a system this service reaches
+// belongs in architecture/landscape.likec4, and declaring a copy of it here
+// would be `c4.element-unowned`. `extend` takes the fully-qualified id because
+// the element is nested in the `marketplace` group.
+//
+// SCHEMA.md, "Two shapes of a service model", has the standalone shape — a model
+// that declares its own `specification` and is therefore parsed alone — and the
+// ordered recipe for migrating one to this shape.
 model {
-  notificationService = softwareSystem 'notification-service' {
-    description 'Turns fleet events into customer email and SMS'
-    // The binding, not the title, is what ties this element to
-    // services/notification-service/. With only a title, renaming the box in a
-    // diagram silently detaches every join that runs through it — health.yaml's
-    // dependencies, `Covers:` entries, the landscape's service checks.
-    metadata {
-      service 'notification-service'
-    }
-
+  extend marketplace.notificationService {
     consumer = container 'consumer' {
       description 'Kafka consumer group; one handler per message name'
       technology 'Go'
@@ -67,30 +53,12 @@ model {
     sender -> deliveryLog 'Records delivered / failed'
   }
 
-  // Everything the service touches belongs in its own model, cross-boundary
-  // dependencies included — the landscape carries only the boundary crossing.
-  // health.yaml names `kafka` as a critical dependency and that id has to resolve
-  // HERE, by element id, `metadata { service }` binding or title
-  // (`health.dependency-unmodelled` otherwise); and a model with elements and no
-  // edges beside a health.yaml that declares dependencies is `c4.no-relationships`
-  // — a service that reaches nothing is almost never true.
-  kafka = softwareSystem 'kafka' {
-    description 'Event backbone (platform)'
-    orderEvents = topic 'order.events'
-    paymentEvents = topic 'payment.events'
-    crmEvents = topic 'crm.events'
-  }
-
-  // The second thing this service reaches across its own boundary, and the one
-  // the runbook spends an incident section on: while the provider is down or
-  // throttling, nothing is delivered and there is no fallback path. It belongs
-  // here for the same reason payment-service's model draws `stripe` — a model
-  // that stopped at the broker would show a worker whose only failure mode is
-  // lag, which is the half of the picture the on-call graphs already give you.
-  provider = softwareSystem 'notification-provider' {
-    description 'Third-party email and SMS gateway — quota-limited, and outside this fleet'
-  }
-
+  // The three channels this service takes messages off, pointing at the map's
+  // topics. health.yaml names `kafka` as a critical dependency and that id has to
+  // resolve through this model (`health.dependency-unmodelled` otherwise): it
+  // does, because a partner brings its ANCESTORS with it — the edges name the
+  // topics and the broker answers for them.
+  //
   // No `metadata { consumes }` on these edges, and adding it would change
   // nothing: loam reads the event spine off `architecture/landscape.likec4`
   // alone, never off a service model. What resolves a consumed name against
@@ -104,15 +72,27 @@ model {
   // Drawn topic → consumer, the direction the landscape uses and the one the
   // event spine requires there: `consumes` binds the edge's TARGET, so the same
   // edge drawn the other way round binds to nothing at all.
-  kafka.orderEvents -> notificationService.consumer 'OrderPlaced triggers the confirmation'
-  kafka.paymentEvents -> notificationService.consumer 'PaymentCaptured triggers the receipt'
-  kafka.crmEvents -> notificationService.consumer 'CustomerUpdated refreshes contact details'
+  kafka.orderEvents -> marketplace.notificationService.consumer 'OrderPlaced triggers the confirmation'
+  kafka.paymentEvents -> marketplace.notificationService.consumer 'PaymentCaptured triggers the receipt'
+  kafka.crmEvents -> marketplace.notificationService.consumer 'CustomerUpdated refreshes contact details'
 
-  notificationService.sender -> provider 'Sends email and SMS, and backs off on 429'
+  // The second thing this service reaches across its own boundary, and the one
+  // the runbook spends an incident section on: while the provider is down or
+  // throttling, nothing is delivered and there is no fallback path. Its element
+  // is the map's, and the map also carries the SERVICE-level twin of this edge
+  // (`marketplace.notificationService -> notificationProvider`), because every
+  // fleet check reads the map alone. The cross-boundary call is written twice on
+  // purpose — container-level here, service-level there — and that remainder is
+  // recorded in ROADMAP.md rather than hidden.
+  marketplace.notificationService.sender -> notificationProvider 'Sends email and SMS, and backs off on 429'
 }
 
+// Views belong to LikeC4's renderer; no loam check reads anything below. This
+// file is part of the root project, so `npx likec4 start` at the docs root draws
+// this view beside the fleet map — there is no per-service likec4.config.json,
+// and loam never writes one beside an extending model.
 views {
-  view notification_service of notificationService {
+  view notification_service of marketplace.notificationService {
     include *
   }
 }

package/package.json

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