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

package/examples/docs/architecture/landscape.likec4

@@ -8,6 +8,16 @@
 // service needs a directory (warning). An element is tied to its directory by
 // `metadata { service '<id>' }`, or by its title when there is no binding.
 // Systems that are not ours carry #external and are exempt.
+//
+// This file is also the SPECIFICATION every service model borrows. Each
+// `services/<…>/<svc>/model.likec4` here is an EXTENDING model: it declares no
+// kinds and no partners, and says what is inside its service with
+// `extend marketplace.<svc> { … }` on the element below that binds to its
+// directory. The root `likec4.config.json` therefore does NOT exclude
+// `services/**` — the map and every model are ONE LikeC4 project, so an element
+// is declared exactly once and no two documents can disagree about its tags.
+// SCHEMA.md, "Two shapes of a service model", has both shapes and the rule that
+// picks between them; a kind or tag a model needs is added HERE, once.
 specification {
   // A grouping element — it stands for no service and owns no directory. The
   // service checks WALK the tree rather than reading only top-level elements:
@@ -20,7 +30,18 @@ specification {
   // Declared here because archive SPLICES a delta's additions verbatim: FEAT-101's
   // new system carries its `api` container along, and the kind has to be legal in
   // THIS document for the merged landscape to parse (archive refuses otherwise).
+  // Only a NEW service arrives this way — one that already has an extending model
+  // 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.
+  element database
   element person
   // A topic is an element, and the kind carries #external rather than each
   // instance doing it: LikeC4 does NOT inherit tags, so a topic nested inside
@@ -137,6 +158,18 @@ model {
     description 'CRM of record — the fleet reads its events and writes none'
   }
 
+  // Declared HERE rather than in notification-service's model, and that is the
+  // rule an extending model turns on: a system a service reaches is the fleet's
+  // element, declared once, and a model that declared its own copy would be
+  // `c4.element-unowned` (an extending model may only add elements under the
+  // element that resolves to its own service). One consumer, so it never
+  // becomes `landscape.platform-candidate`; #external, so no
+  // services/notification-provider/ is asked for.
+  notificationProvider = softwareSystem 'notification-provider' {
+    #external
+    description 'Third-party email and SMS gateway — quota-limited, and outside this fleet'
+  }
+
   customer -> marketplace.checkoutWeb 'Uses'
 
   // The synchronous spine. Every one of these resolves against the TARGET's
@@ -185,6 +218,14 @@ model {
   // it raises no warning because its title does not claim to be a call into a
   // fleet service.
   marketplace.paymentService -> stripe 'Authorizes cards'
+  // The second half of the rule the extending shape keeps: the container that
+  // really makes the call is drawn in the service's own model
+  // (`marketplace.notificationService.sender -> notificationProvider`), and the
+  // SERVICE-level twin is drawn here, because every fleet check — the spine,
+  // `landscape.service-isolated`, the platform census — reads this file alone.
+  // The edge exists twice on purpose; SCHEMA.md says so where it says the map
+  // is the one document holding every cross-service edge.
+  marketplace.notificationService -> notificationProvider 'Sends email and SMS'
 
   // The event spine, the async mirror of `metadata { op }`: the name must be a
   // message the PRODUCER's own asyncapi.yaml declares an `action: send` for, or

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

@@ -14,7 +14,10 @@
 // read as ONE LikeC4 project, so the steps below resolve against the landscape's
 // elements even though this file declares none — which also means exactly one
 // file in this directory declares the `specification` block, and it is not this
-// one.
+// one. (The renderer's root project is WIDER than what loam grades here: it also
+// holds every `services/<svc>/model.likec4`, because each of them extends the
+// map. A tag declared twice across that whole set is `c4.fleet-project-invalid`,
+// which is why a tag belongs in the landscape's one block.)
 //
 // THE TAG MUST BE THE FIRST THING IN THE VIEW BODY. Written after `title` it is
 // five parse errors, none of which mentions tags. That is the mistake every
@@ -30,7 +33,7 @@
 // `usecase.step-unlinked` is met except the one that matters, which is that a
 // person is not a caller. Somebody clicking a button owes no operationId. Delete
 // that exemption from the checker and this file is what notices: the example
-// fleet's warning count moves from eight to nine and test/examples.test.ts
+// fleet's warning count moves from ten to eleven and test/examples.test.ts
 // fails.
 //
 // The hop from checkout-web to order-service is DELIBERATELY NOT DRAWN, and its

package/examples/docs/likec4.config.json

@@ -3,7 +3,6 @@
   "title": "Fleet landscape",
   "exclude": [
     "**/node_modules/**",
-    "services/**",
     "features/**"
   ]
 }

package/examples/docs/services/checkout-web/model.likec4

@@ -1,27 +1,24 @@
-// Per-service C4 for a UI service. A UI is a first-class C4 system: it has
-// containers, it has runtime dependencies, and its pages (ui/pages/*.page.yaml)
-// hang off the operations the edges below name.
+// checkout-web's own C4 — what is INSIDE the element the fleet map binds to
+// services/checkout-web/. A UI is a first-class C4 system: it has containers, it
+// has runtime dependencies, and its pages (ui/pages/*.page.yaml) hang off the
+// operations the edges below name.
 //
-// Every .likec4 file is parsed ON ITS OWN — loam never concatenates them — so
-// this document declares the kinds it uses even though architecture/landscape.likec4
-// declares the same ones. Leaving them out here does not inherit, it fails to parse
-// (`c4.invalid`, an error), and the spec/API joins that read the model go quiet with it.
-specification {
-  element softwareSystem
-  element container
-  element person
-}
-
+// An EXTENDING model: no `specification` block, no partner copies. The kinds and
+// every element this file points at — `customer`, `marketplace.orderService`,
+// `marketplace.paymentService` — are declared once in
+// architecture/landscape.likec4, and the root `likec4.config.json` does not
+// exclude `services/**`, so the map and every model are read as ONE LikeC4
+// project. `extend` takes the fully-qualified id, because the element is nested
+// in the `marketplace` group.
+//
+// Note what this file does NOT do: it does not declare `customer = person`. The
+// actor is the map's, and the edge below simply points at it. That is the rule
+// the shape turns on — an element declared here outside
+// `marketplace.checkoutWeb` is `c4.element-unowned` — and it is also what stops
+// two documents from holding two different descriptions of the same person.
+// SCHEMA.md, "Two shapes of a service model", has the other shape.
 model {
-  // The actor belongs in a UI's own model in a way it does not in a backend's:
-  // the pages exist for this person, and the flows in ui/pages/ start at them.
-  // The landscape draws the same customer -> checkout-web edge at fleet scale;
-  // a person is exempt from the service/directory cross-check either way.
-  customer = person 'Customer'
-
-  checkoutWeb = softwareSystem 'checkout-web' {
-    description 'Customer-facing checkout UI'
-
+  extend marketplace.checkoutWeb {
     spa = container 'spa' {
       description 'Checkout SPA — cart, payment and order status pages'
       technology 'React'
@@ -37,37 +34,21 @@ model {
       technology 'Node.js'
     }
 
-    customer -> spa 'Buys'
     spa -> bff 'Calls the checkout BFF'
   }
 
-  // The services this one actually calls. A service model carries everything the
-  // service touches, cross-boundary included, drawn with the edge the service
-  // really has — the landscape carries only the boundary crossing (checkout-web ->
-  // order-service), while the edge below says WHICH container makes the call.
-  // Without these three edges this file would be two boxes and a hop, and
-  // `c4.no-relationships` would be right to say a model that reaches nothing is
-  // almost never true.
-  orderService = softwareSystem 'order-service' {
-    description 'Owns the order lifecycle'
-    // Bind rather than rely on the title. A renamed box silently stops matching
-    // its directory everywhere the two are joined — in the landscape that costs
-    // `landscape.binding-unknown` (error) when the id is wrong, and here it is
-    // what `health.dependency-unmodelled` resolves a declared dependency
-    // through in the services that have a health.yaml. checkout-web has none:
-    // a UI is nobody's runtime dependency, so it declares no SLIs, no alerts
-    // and no dependency graph, and owes no arch.spec.md to cover them.
-    metadata {
-      service 'order-service'
-    }
-  }
-  paymentService = softwareSystem 'payment-service' {
-    description 'Owns payment authorization/capture'
-    metadata {
-      service 'payment-service'
-    }
-  }
+  // The person is the MAP's element and the hop into this UI is drawn from it.
+  // The landscape draws the coarser `customer -> marketplace.checkoutWeb` twin
+  // at fleet scale; this one says which container the click reaches. A person is
+  // exempt from the service/directory cross-check either way.
+  customer -> marketplace.checkoutWeb.spa 'Buys'
 
+  // The services this one actually calls, drawn with the edge the service really
+  // has — the landscape carries only the boundary crossing (checkout-web ->
+  // order-service), while the edges below say WHICH container makes the call.
+  // Without them this file would be two boxes and a hop, and `c4.no-relationships`
+  // would be right to say a model that reaches nothing is almost never true.
+  //
   // `metadata { op }` is the C4 half of the operation join: the exact
   // operationId order-service's openapi.yaml declares. What `loam validate`
   // grades is the LANDSCAPE's twin of each edge below — `spine.op-undefined`
@@ -77,12 +58,12 @@ model {
   // nothing would catch it if they did. Two calls to one service are two edges,
   // not one edge with a list — a view has to be able to show that the status
   // page and the checkout page stand on different operations.
-  checkoutWeb.bff -> orderService 'Calls createOrder' {
+  marketplace.checkoutWeb.bff -> marketplace.orderService 'Calls createOrder' {
     metadata {
       op 'createOrder'
     }
   }
-  checkoutWeb.bff -> orderService 'Calls getOrder' {
+  marketplace.checkoutWeb.bff -> marketplace.orderService 'Calls getOrder' {
     metadata {
       op 'getOrder'
     }
@@ -94,16 +75,18 @@ model {
   // for an edge that SAYS it calls something and names no operation, so nothing
   // can check the call still exists. Free here and one warning there, which is
   // the asymmetry worth knowing: the fleet map is what the spine reads.
-  checkoutWeb.spa -> paymentService 'Calls the payment API'
+  marketplace.checkoutWeb.spa -> marketplace.paymentService 'Calls the payment API'
 }
 
 // Views are the LikeC4 renderer's, never loam's — no check reads this block.
-// Scoped to the system so the page answers "what does the checkout UI stand on"
-// rather than redrawing the fleet, which architecture/landscape.likec4 already does.
+// Scoped to the service's element so the page answers "what does the checkout UI
+// stand on" rather than redrawing the fleet, which architecture/landscape.likec4
+// already does. This file is part of the root project: `npx likec4 start` at the
+// docs root draws it, with no per-service project file to write.
 views {
-  view checkout_web of checkoutWeb {
+  view checkout_web of marketplace.checkoutWeb {
     title 'checkout-web — containers and the services they call'
     include *
-    include orderService, paymentService
+    include marketplace.orderService, marketplace.paymentService
   }
 }

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/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,21 +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 why the root
-// `likec4.config.json` scopes the fleet project to `architecture/` and stays
-// that way. What renders THIS model beside the map from the docs root is this
-// directory's own `likec4.config.json`, written by `loam subsystem sync`.
-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'
@@ -42,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