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

package/examples/README.md

@@ -18,6 +18,7 @@ loam archive FEAT-112 --dry-run    # an operation being retired, writing nothing
 loam verify FEAT-088               # a shipped feature's done-check: attested
 loam verify FEAT-120               # …and its pair, the same check: verified
 loam dependencies                  # the active-feature graph
+loam list suites                   # which services each test suite needs up
 ```
 
 Working on loam itself and running from source, use `npx tsx ../../src/cli.ts <args>` in place of
@@ -58,6 +59,18 @@ GROUP and earns no finding. Each requirement in both files is a promise a custom
 names no service, and carries a `Requirement-ID:` — required here, unlike in a service spec, because
 these documents outlive every service that realizes them.
 
+**One journey in two suites.** The same use case also carries `#suite-smoke` and
+`#suite-notifications`, both declared in the landscape's `specification` block, so `loam list
+suites` has a real answer: each suite needs `checkout-web`, `order-service` and
+`notification-service` up — the union of the journey's participants, resolved through the same
+element→service join the step grades use (notification-service is found through its filing under
+`platform/`, because the answer is ids, never paths). Two participants resolve to no service and are
+NAMED rather than dropped: `customer`, who drives the flow, and `kafka.orderEvents`, which is
+`#external` through its `topic` kind and wants a double on the test stand. One journey in both
+suites is the point of the tag: a directory could file it in only one. The suite tags change
+nothing `validate` says here — the view was already graded through its `#cap-` tag — but on a view
+carrying ONLY `#suite-` tags they are the opt-in, and its hops are graded like any other use case's.
+
 **Two glossary terms**, `glossary/order.md` and the nested `glossary/payments/authorization.md`,
 each cited from the capability documents that use the word. This is the axis's whole mechanism in
 two files: the citation is an ordinary markdown link, so `loam validate` resolves it like any other
@@ -81,8 +94,9 @@ nowhere, and `obligation.unapplied` is the warning in the table below.
 **On the event spine the arrow follows the message** — producer → topic for `publishes`, topic →
 consumer for `consumes` — and that is load-bearing rather than aesthetic. `publishes` binds the
 edge's source and `consumes` binds its target, so a consume edge drawn the other way round binds to
-nothing: the metadata parses, the document validates, and the check silently grades zero edges.
-Nothing in loam reports that today, which is why the landscape says so in a comment.
+nothing: the metadata parses, the document validates, and no contract is checked against the link.
+`spine.message-unbound` (warn) is what reports it, on the service at the end the key did not bind;
+SCHEMA.md's *Which way an edge points* lists every reader of the arrow and the drawing each expects.
 
 ## Four features, at four points in their life
 
@@ -94,8 +108,10 @@ for.
 - **`features/archive/FEAT-088-refunds/`** — shipped, and **`attested`**. It was merged by the real
   `loam archive`, so its `.loam-before/` snapshot holds the exact bytes the merge overwrote and
   `loam unarchive FEAT-088` would put them back. Its `verification.yaml` is the done-check written
-  down: every claim is confirmed, but the scenario claims rest on an agent's word instead of a
-  digest-matched test run. loam does not pretend those are the same thing.
+  down — recorded all at once, so it is the one file (a feature recorded per service carries one
+  `verification/<svc>.yaml` per attesting service instead): every claim is confirmed, but the
+  scenario claims rest on an agent's word instead of a digest-matched test run. loam does not
+  pretend those are the same thing.
 - **`features/archive/FEAT-120-refund-notification/`** — shipped, and **`verified`**. The sequel
   FEAT-088 left open: the money went back and nobody told the customer. It publishes
   `payment.PaymentRefunded` from payment-service and has notification-service turn it into the
@@ -111,10 +127,10 @@ for.
   with its own requirements, architecture requirements and contract, a C4 delta that splices a
   nested element into the living landscape, a `MODIFIED` requirement that **renames its heading**
   while keeping its `Requirement-ID` — loam's rename mechanism — and an **event-contract delta**
-  (`specs/payment-service/asyncapi.yaml`): a complete AsyncAPI 3.0 document restating
-  payment-service's living contract under `loam rebase`-written `x-loam-based-on` pins and adding
-  one new producer side, so the archive merges the new slots and leaves every pinned quote to the
-  living contract's own copy.
+  (`specs/payment-service/asyncapi.yaml`) that restates payment-service's living contract under
+  `loam rebase`-written `x-loam-based-on` pins and adds one new producer side, so the archive merges
+  the new slots and leaves every pinned quote to the living contract's own copy. The restatement is
+  there to demonstrate the pin; a real delta holds only the slots it adds, changes or removes.
 - **`features/FEAT-112-retire-order-v1/`** — in flight, and the smallest legal shape: no
   `delta.likec4` at all, because retiring an operation moves no boxes. It carries the two halves
   loam requires together for a removal — a `REMOVED` requirement and an `x-loam-remove: true` marker
@@ -143,12 +159,39 @@ while the other three sit unfiled — the permanent, normal state a partially or
 in, counted by `loam list` and never a finding. Placement is not identity: both services' specs,
 contracts and digests are byte-identical to their unfiled days, every command addresses them by bare
 id, and `architecture/subsystems.likec4` — GENERATED by `loam subsystem sync`, one view per
-subsystem, one `include` per line — is the only file the grouping added. Edit the tree with
-`loam subsystem move|rename|rm` and the views file travels in the same transaction; edit it by hand
-and `validate --all` answers `subsystem.views-stale`. (`order-service` and `payment-service` stay
+subsystem, one `include` per line — is the only file the grouping added. Its sibling
+`architecture/services.likec4` is the other generated views file and owes the grouping nothing: one
+overview view per service the fleet map draws, filed or not, each declared `of` its service's
+element so every other view drills into it, and each titled by its path so the two files fold into
+one folder tree. Edit the tree with
+`loam subsystem move|rename|rm` and both views files travel in the same transaction; edit either by
+hand and `validate --all` answers `subsystem.views-stale`, naming the file that drifted. (`order-service` and `payment-service` stay
 unfiled deliberately: FEAT-088's committed version-2 snapshot restores them by literal path, and the
 `loam unarchive FEAT-088` walkthrough must keep working byte-for-byte.)
 
+**All five models are EXTENDING models, and that is the shape this example teaches.** None of them
+declares a `specification` block, none re-declares a partner, and none has a `likec4.config.json`
+beside it. Each one says what is inside its service with `extend marketplace.<svc> { … }` on the
+element `architecture/landscape.likec4` already binds to its directory, so `kafka`, `stripe`,
+`notification-provider` and every peer service are declared exactly once — in the map — and no two
+documents can disagree about their tags. The root `likec4.config.json` therefore excludes only
+`**/node_modules/**` and `features/**`: `npx likec4 validate examples/docs` names ONE project,
+`fleet`, holding the map and all five models, and needs no `--project` flag. The other shape — a
+model that declares its own `specification` and is parsed alone, which is what every model here was
+before — is still legal and still supported; SCHEMA.md's "Two shapes of a service model" has both,
+the eight grades in its table — seven that came with the pair, plus the one it narrowed
+(`service.likec4-config-missing`, now standalone-only) — and the
+ordered recipe for migrating between them.
+
+Two consequences are visible in the tree and worth reading for. Element ids carry their full path,
+so `services/order-service/arch.spec.md` writes `Covers: marketplace.orderService.db` — the
+container has no shorter name, because the model extends an element nested in the `marketplace`
+group. And a cross-boundary call is written **twice** on purpose: container-level in the model
+(`marketplace.notificationService.sender -> notificationProvider`) and service-level in the map
+(`marketplace.notificationService -> notificationProvider`), because every fleet check — the spine,
+`landscape.service-isolated`, the platform census — reads the map alone. ROADMAP.md keeps that
+remainder written down rather than hidden.
+
 Plus one count rather than a finding: `sourcesUnverifiableFromHere: 4`. Four specs name paths in
 their own service repositories, and this is none of those repositories — the fleet gate reports the
 blind spot instead of resolving it. Running `loam validate --service <id>` inside each service repo

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:
@@ -17,10 +27,27 @@ specification {
   // CONTAINS services rather than being one.
   element group
   element softwareSystem
-  // 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).
+  // Declared here for the service models, which declare no kinds of their own.
+  // FEAT-101's new system draws an `api` container inside it, and archive
+  // creates services/payment-split-service/model.likec4 with the service and
+  // splices the container in there — never into this file, which holds no
+  // service's interior. That model borrows its kinds from this block, so the
+  // kind has to be legal HERE for it to parse (archive refuses otherwise).
   element container
+  // Declared here for the SERVICE MODELS, and nothing in this file uses it.
+  // This fleet writes every `database` element inside the service that owns it,
+  // in a `services/<svc>/model.likec4` under `extend marketplace.<svc>` — a
+  // CHOICE this example makes, not a rule loam enforces. Drawing an owned store
+  // beside the services is equally first-class and earns no finding; what the
+  // placement decides is one thing, and it is a fact about LikeC4: a second
+  // service's edge naming `marketplace.<svc>.<store>` resolves only against a
+  // declaration the MAP holds, because a per-service project is `architecture/`
+  // plus one model. So a store a second consumer will name belongs on the map,
+  // and one nobody else reaches may live wherever the team finds it clearest.
+  // An extending model declares no kinds of its own, so a kind it needs and
+  // this block does not declare is ONE parse error on the model — which is what
+  // this line prevents.
+  element database
   element person
   // A topic is an element, and the kind carries #external rather than each
   // instance doing it: LikeC4 does NOT inherit tags, so a topic nested inside
@@ -58,6 +85,14 @@ specification {
   // cannot carry flattened to `-`. Declared here for the same reason — one
   // specification block serves the whole `architecture/` project.
   tag req-NOTIFY-ONCE
+  // The SUITES a flow runs with — `#suite-<name>` on the view, many-to-many, so
+  // the one journey below sits in both. Declared here, like every tag, so a
+  // mistyped suite is a parse error rather than a second, empty suite.
+  // `loam list suites` answers which services each one needs up: the union of
+  // its journeys' participants, plus the ones no services/ directory stands for
+  // (the customer who drives it, the #external topic in the middle).
+  tag suite-smoke
+  tag suite-notifications
   // An ARCHITECTURAL OBLIGATION, declared in architecture/obligations.yaml and
   // applied HERE, on the objects it holds for. The decision itself is
   // architecture/adrs/0001-transactional-outbox.md; this tag is the architect
@@ -137,6 +172,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 +232,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
@@ -195,9 +250,10 @@ model {
   // THE ARROW FOLLOWS THE MESSAGE, and that is load-bearing rather than
   // aesthetic. `publishes` binds the edge's SOURCE and `consumes` binds its
   // TARGET, so a consume edge drawn the other way round — `orderService ->
-  // kafka.paymentEvents` — binds to nothing at all: the metadata parses, the
-  // document validates, and the check silently grades zero edges. Producer to
-  // topic, topic to consumer, every time.
+  // kafka.paymentEvents` — binds to nothing at all: the metadata parses and the
+  // document validates, and all that says so is `spine.message-unbound` (warn)
+  // on the service that drew it. Producer to topic, topic to consumer, every
+  // time.
   marketplace.paymentService -> kafka.paymentEvents 'Publishes PaymentAuthorized' {
     #obl-outbox
     metadata {

package/examples/docs/architecture/services.likec4

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

package/examples/docs/architecture/subsystems.likec4

@@ -1,11 +1,18 @@
 // generated by loam — the subsystem tree under services/, one view per subsystem.
 // Do not edit: `loam subsystem sync` regenerates this file from the directories,
 // and `loam validate --all` reports `subsystem.views-stale` when it drifts.
+// A scoping aid, not the fleet's architecture: author your own diagrams elsewhere.
 
 views {
   // services/platform
+  // model: no boundary — marketplace also holds services outside this subsystem.
   view subsystem_platform {
+    title 'Platform'
+    description 'Cross-cutting identity and messaging'
     include marketplace.identityService
     include marketplace.notificationService
+
+    include marketplace.identityService -> *, * -> marketplace.identityService
+    include marketplace.notificationService -> *, * -> marketplace.notificationService
   }
 }

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

@@ -1,8 +1,10 @@
 // A fleet use case: the ordered hops that fulfil one business capability.
 //
 // This file is the whole shape of the axis. A `dynamic view` tagged
-// `#cap-<slug>` opts in to grading; an untagged one is somebody's hand-drawn
-// diagram and loam never says a word about it. The slug is the capability id
+// `#cap-<slug>` opts in to grading — so does one tagged only `#req-` or only
+// `#suite-<name>`, the suite a journey runs with (`loam list suites`); an
+// untagged one is somebody's hand-drawn diagram and loam never says a word
+// about it. The slug is the capability id
 // from architecture/capabilities.yaml with every `/` flattened to `-`, because
 // a LikeC4 tag name cannot carry a slash — `identity/tokens` would be
 // `#cap-identity-tokens`.
@@ -14,7 +16,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 +35,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
@@ -38,14 +43,18 @@
 // edges for that pair — `Calls createOrder` and `Calls getOrder` — so a step
 // between those two elements names two operations, and loam refuses to guess
 // which one the flow exercises: `usecase.step-contested` (warn), listing both
-// candidates. That is the check working. The two fixes are the ones the message
-// offers: draw the hop between elements that name exactly one operation, or give
-// the candidates one operation between them.
+// candidates. That is the check working. The fix is the one the message offers
+// first: say which operation the hop means by opening the step's title with it,
+// then punctuation — `marketplace.checkoutWeb -> marketplace.orderService
+// 'createOrder — creates the order'` — and loam attributes the hop to that edge.
+// (The other fix is to give the candidates one operation between them.)
 
 views {
   dynamic view uc_order_notification {
     #cap-order-notifications
     #req-NOTIFY-ONCE
+    #suite-smoke
+    #suite-notifications
     title 'Order notification'
     description 'A placed order reaches the customer as exactly one confirmation'
 

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

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

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

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

package/examples/docs/features/FEAT-112-retire-order-v1/specs/order-service/openapi.yaml

@@ -17,10 +17,13 @@
 # Removal markers carry no baseline pin, unlike the operations a feature edits:
 # `openapi.remove-target-mismatch` already checks that exact slot, which is the same question a
 # pin would answer.
+#
+# `info` restates the living contract's. No merge carries `info`, so a value that differs here
+# would be lost at archive — `openapi.info-not-merged` says so in the plan instead of letting it vanish.
 openapi: 3.1.0
 info:
   title: order-service
-  version: "1.0"
+  version: "2.0"
 paths:
   /v1/orders:
     post:

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

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

package/examples/docs/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
   }
 }