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

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.5",
+  "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": {

package/examples/docs/services/checkout-web/likec4.config.json

@@ -1,4 +0,0 @@
-{
-  "name": "checkout-web",
-  "title": "checkout-web"
-}

package/examples/docs/services/order-service/likec4.config.json

@@ -1,4 +0,0 @@
-{
-  "name": "order-service",
-  "title": "order-service"
-}

package/examples/docs/services/payment-service/likec4.config.json

@@ -1,4 +0,0 @@
-{
-  "name": "payment-service",
-  "title": "payment-service"
-}

package/examples/docs/services/platform/identity-service/likec4.config.json

@@ -1,4 +0,0 @@
-{
-  "name": "identity-service",
-  "title": "identity-service"
-}

package/examples/docs/services/platform/notification-service/likec4.config.json

@@ -1,4 +0,0 @@
-{
-  "name": "notification-service",
-  "title": "notification-service"
-}