@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

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

@@ -0,0 +1,134 @@
+---
+service: order-service
+status: draft
+owner: orders-team
+sources:
+  - src/main/kotlin/
+---
+
+# order-service — architecture spec
+
+The **living architecture spec**: the obligations no business scenario in `spec.md` was ever
+going to carry. "Place an order" says an order is placed; it does not say that the placement
+and its `OrderPlaced` row commit together, that a caller's retry must not buy the basket twice,
+or that a redelivered `PaymentAuthorized` must confirm the order exactly once. Those are the
+corners an agent writing the implementation cuts first, so they are written down mechanically
+here instead of being trusted to a reviewer.
+
+Same grammar as `spec.md`, and a separate requirement namespace — an arch requirement never
+collides with a business one of the same name, and `loam gherkin` emits these tagged
+`@architecture` so the suite knows an integration or operational test is being asked for.
+
+What makes the file checkable is the `Covers:` line: it names the model objects a requirement's
+scenarios exercise, and `loam validate` grades it both ways. Every entry must resolve against
+this service's own `model.likec4` plus the landscape (`covers.unknown`, with a did-you-mean
+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 — `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
+
+### Requirement: Order creation is idempotent under a caller's key
+
+Requirement-ID: ARCH-ORD-IDEMPOTENCY
+The service SHALL record the `Idempotency-Key` of every accepted `createOrder` in the same
+transaction that stores the order, and SHALL replay the stored response for a repeat of that
+key rather than placing a second order or requesting a second authorization. checkout-web's
+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: 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
+- **When** the identical `createOrder` request arrives again after the caller timed out
+- **Then** the stored response for "ik-8842" is returned unchanged
+- **And** payment-service receives no second `authorizePayment` call
+
+#### Scenario: An authorization call that times out is retried, not abandoned
+- **Given** a `createOrder` whose `authorizePayment` call times out with no response
+- **When** the placement path retries the authorization
+- **Then** `authorizePayment` is called again for the same `orderId`, amount and currency
+- **And** payment-service's idempotency by order id returns the first authorization instead of reserving funds twice
+
+### Requirement: OrderPlaced leaves through the transactional outbox
+
+Requirement-ID: ARCH-ORD-OUTBOX
+The service SHALL write the order and its `OrderPlaced` event into the same database
+transaction and SHALL publish the event from the outbox relay — never by writing to the
+database and then to kafka. A dual write has no failure mode in which both sides agree: a crash
+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: 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
+- **When** kafka is unreachable
+- **Then** the order stays committed and is readable through `getOrder`
+- **And** the relay publishes the event once kafka returns, without the caller retrying
+
+#### Scenario: The relay crashes after publishing and before marking the row sent
+- **Given** an outbox row published to `order.events.v1` but not yet marked sent
+- **When** the relay restarts and picks the row up again
+- **Then** the event is published a second time with the same order id
+- **And** consumers deduplicate on it, because this relay promises at-least-once and not exactly-once
+
+### Requirement: PaymentAuthorized is consumed at least once and applied once
+
+Requirement-ID: ARCH-ORD-DEDUPE
+The service SHALL record the `paymentId` of every `payment.PaymentAuthorized` it applies, in
+the transaction that advances the order, and SHALL ignore a message whose `paymentId` is
+already recorded. The producer's outbox promises at-least-once delivery and a rebalance
+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: marketplace.orderService.consumer, kafka.paymentEvents -> marketplace.orderService.consumer
+Consumes: payment.PaymentAuthorized
+
+#### Scenario: The same authorization is redelivered after a consumer rebalance
+- **Given** an order confirmed from `payment.PaymentAuthorized` for payment "pay-77"
+- **When** the same message is redelivered after the consumer group rebalances
+- **Then** the ledger already holds "pay-77" and the message is acknowledged without a write
+- **And** the order's state and its updated-at timestamp are unchanged
+
+#### Scenario: The consumer fails mid-batch and the offset is not committed
+- **Given** a batch of authorizations where the third message fails to apply
+- **When** the consumer restarts from the last committed offset
+- **Then** the first two are recognized by the ledger and skipped
+- **And** the third is applied, so no authorization is lost to a partial batch
+
+### Requirement: Order placement is measured and paged
+
+Requirement-ID: ARCH-ORD-SIGNALS
+The service SHALL export availability and placement-latency SLIs, and SHALL page the orders
+on-call when placements fail at a sustained rate. Placement is the fleet's revenue path and it
+fails silently from the customer's side — a broken authorization call looks like a slow
+checkout — so the alert is on the outcome, not on any one dependency being down.
+
+Covers: sli:availability, sli:order_placement_latency_p95_ms, alert:order_placement_failures
+
+#### Scenario: Sustained placement failures page the on-call
+- **Given** more than 2% of `createOrder` calls failing over five minutes
+- **When** the alert rules are evaluated
+- **Then** `order_placement_failures` pages the orders on-call with the runbook link
+
+#### Scenario: The SLIs are exported against their objectives
+- **Given** the service is serving traffic
+- **When** its metrics endpoint is scraped
+- **Then** `availability` and `order_placement_latency_p95_ms` report values against their SLOs
+
+#### Scenario: A degraded payment-service shows up as placement latency, not as a silent stall
+- **Given** payment-service answering `authorizePayment` slowly but successfully
+- **When** placements queue behind it
+- **Then** `order_placement_latency_p95_ms` rises above its objective before any request times out

package/examples/docs/services/order-service/asyncapi.yaml

@@ -0,0 +1,109 @@
+# The async contract — both directions, because this service is a producer and a
+# consumer at once.
+#
+# AsyncAPI 3.0 only. Its operations are named top-level objects carrying
+# `action: send|receive`, which is the exact analog of an `operationId` and the thing
+# that makes direction legible; 2.x spells the same thing as publish/subscribe under
+# a channel, where the two words are ambiguous about whose perspective they take. A
+# 2.x document declares no `operations` at all, so loam refuses it as one
+# `asyncapi.invalid` naming the version rather than reading it as a contract with no
+# messages (`asyncapi convert --target-version=3.0.0` upgrades it).
+#
+# The join is the message NAME, spelled three times and required to be identical: the
+# landscape edge's `metadata { publishes }` / `metadata { consumes }`, a requirement's
+# `Publishes:` / `Consumes:` line, and `name` below. A name this file does not declare
+# an operation for, in the matching direction, is `spine.message-undefined` from the
+# landscape and `spec-event.message-undefined` from the spec — the same breach seen
+# from the two documents that can be wrong about it.
+asyncapi: 3.0.0
+info:
+  title: order-service events
+  version: "1.0"
+
+channels:
+  orderEvents:
+    address: order.events.v1
+    description: Order lifecycle events, published by the outbox relay (ARCH-ORD-OUTBOX)
+    messages:
+      OrderPlaced:
+        $ref: '#/components/messages/OrderPlaced'
+  paymentEvents:
+    address: payment.events.v1
+    description: payment-service's channel, read by the payment-consumer
+    messages:
+      PaymentAuthorized:
+        $ref: '#/components/messages/PaymentAuthorized'
+
+operations:
+  sendOrderPlaced:
+    action: send
+    channel:
+      $ref: '#/channels/orderEvents'
+    messages:
+      - $ref: '#/channels/orderEvents/messages/OrderPlaced'
+  # `action: receive` is what keeps order-service a consumer of this message and not a
+  # second producer of it: `asyncapi.message-contested` counts services declaring they
+  # SEND one name, and two of them make every consumer's join a coin flip. Declaring
+  # the message here is not a claim to own it — payment-service's contract is
+  # authoritative — it is what makes the consuming edge resolve at all.
+  receivePaymentAuthorized:
+    action: receive
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+
+components:
+  messages:
+    OrderPlaced:
+      # Namespaced by the domain that owns it, and produced by exactly one service.
+      name: order.OrderPlaced
+      title: Order placed
+      # The producer's copy, so this is the authoritative shape — notification-service
+      # declares a three-field subset of it and nothing compares the two, which is what
+      # leaves this file free to add a field without breaking a consumer. `currency`
+      # travels with `totalAmount` because a total with no currency is precisely the
+      # defect v1 shipped (ORD-PLACE-V1: every v1 total is assumed EUR). Declaring
+      # properties at all is what keeps this out of `asyncapi.payload-undescribed`.
+      payload:
+        type: object
+        required: [orderId, customerId, currency, totalAmount, placedAt]
+        properties:
+          orderId:
+            type: string
+            format: uuid
+          customerId:
+            type: string
+            format: uuid
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          totalAmount:
+            type: integer
+            description: minor units
+          placedAt:
+            type: string
+            format: date-time
+
+    PaymentAuthorized:
+      # The consumer's copy of a contract payment-service owns. It is deliberately the
+      # subset this service reads — `paymentId` is what ARCH-ORD-DEDUPE's ledger keys
+      # on and `orderId` is what ORD-ON-AUTHORIZED advances — and nothing compares the
+      # two documents field by field, because a consumer that demanded the producer's
+      # whole payload would break on every field the producer adds.
+      name: payment.PaymentAuthorized
+      title: Payment authorized
+      payload:
+        type: object
+        required: [paymentId, orderId, authorizedAt]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+            description: The ledger key that makes a redelivery a no-op.
+          orderId:
+            type: string
+            format: uuid
+          authorizedAt:
+            type: string
+            format: date-time

package/examples/docs/services/order-service/health.yaml

@@ -0,0 +1,57 @@
+# Service health model. Objectives and queries are authored; the dependency graph is
+# the C4 model's, restated here for the person who opens this file at 03:00.
+#
+# `loam validate` reads exactly three things out of it, and everything else — the
+# queries, the thresholds, the check URLs, the criticality — is prose no check grades:
+#
+#   - each `slis[].name` and `alerts[].name`, every one of which wants a requirement in
+#     arch.spec.md carrying `Covers: sli:<id>` / `Covers: alert:<id>`, or
+#     `health.uncovered` says the signal ships with nothing testing it;
+#   - each `dependencies[].service`, which must resolve in services/order-service/model.likec4
+#     by element id, `metadata { service }` binding or title, or
+#     `health.dependency-unmodelled` fires — the check that catches a dependency this
+#     file still swears by after the code stopped calling it;
+#   - the same dependency list is model-shape evidence: declared here and drawn nowhere
+#     is what makes `c4.no-relationships` a warning rather than a guess.
+#
+# A dependency a feature in flight introduces arrives with that feature. It is not a
+# dependency of the living service yet, and writing it here early makes the on-call
+# file describe a system nobody is running.
+service: order-service
+status: draft
+slis:
+  - name: availability
+    query: "sum(rate(http_requests_total{job='order-service',code!~'5..'}[5m])) / sum(rate(http_requests_total{job='order-service'}[5m]))"
+    slo: 0.999
+  - name: order_placement_latency_p95_ms
+    # Scoped to POST /orders on purpose. getOrder is a single indexed read and
+    # /v1/orders is one nightly batch importer; averaged in, either would pull
+    # the p95 away from the number that says whether checkout feels broken.
+    query: "histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{job='order-service',path='/orders',method='POST'}[5m]))) * 1000"
+    slo: 800
+alerts:
+  - name: order_placement_failures
+    # A ratio, not a bare rate. ARCH-ORD-SIGNALS' scenario and the runbook step
+    # below both say "more than 2% of placements", and `rate(5xx) > 0.02` says
+    # something else entirely — 0.02 failures per second, which is a different
+    # promise at every hour of the day and a silent one at 04:00. Nothing in
+    # loam grades this string: the arch requirement is the only thing that can
+    # catch it drifting from what it claims to measure.
+    expr: "sum(rate(http_requests_total{job='order-service',path='/orders',method='POST',code=~'5..'}[5m])) / sum(rate(http_requests_total{job='order-service',path='/orders',method='POST'}[5m])) > 0.02"
+    for: 5m
+    page: orders-oncall
+    runbook: runbook.md#placement-failures
+checks:
+  liveness: GET /actuator/health/liveness
+  readiness: GET /actuator/health/readiness
+# Critical runtime dependencies only, and the reconciliation with the model runs one
+# way: everything named here must be modelled, not everything modelled named here.
+# model.likec4 also draws the introspectToken call to identity-service, and it is
+# absent below on purpose — introspection results are cached, so a brief identity
+# outage degrades authorization rather than stopping placement, and a list that holds
+# everything the service touches stops being a blast-radius list.
+dependencies:
+  - service: kafka
+    criticality: critical        # no broker -> no OrderPlaced, and the outbox grows unbounded
+  - service: payment-service
+    criticality: critical        # no authorization -> no placement; ORD-PLACE cannot complete

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

@@ -0,0 +1,126 @@
+// order-service's own C4 — what is INSIDE the element the fleet map binds to
+// services/order-service/.
+//
+// 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 {
+  extend marketplace.orderService {
+    api = container 'api' {
+      description 'REST API: createOrder, getOrder, cancelOrder, and the deprecated createOrderV1'
+      technology 'Spring Boot'
+    }
+    domain = container 'domain' {
+      description 'Order state machine; calls payment-service before an order is acknowledged'
+      technology 'Kotlin'
+    }
+    // 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. 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'
+    }
+    consumer = container 'payment-consumer' {
+      description 'Applies payment.PaymentAuthorized once per paymentId, then advances the order'
+      technology 'Kotlin'
+    }
+    // The store is a NESTED container of this service, and that is this fleet's
+    // CHOICE rather than a rule: loam grades neither placement, and the same store
+    // drawn beside the services in the landscape earns no finding either. What the
+    // choice decides is one thing, and it is a fact about LikeC4 rather than a
+    // preference: an edge naming `marketplace.orderService.db` resolves only for a
+    // project that holds this file, and a per-service project is `architecture/`
+    // plus ONE model — so a store a second service will name belongs on the map,
+    // inside `marketplace.orderService`. Nesting hides nothing meanwhile: a second
+    // service reaching the same data earns `landscape.datastore-shared`, counted
+    // from that service's own model.
+    // The `database` kind is the landscape's, declared there once for every model that needs it.
+    db = database 'db' {
+      description 'Orders, idempotency keys, the applied-payment ledger and the outbox table'
+      technology 'PostgreSQL'
+    }
+
+    // The internal edges, written INSIDE the extend block, where the children
+    // resolve by their short names.
+    api -> domain 'Places, reads and cancels'
+    domain -> db 'Writes the order, its idempotency key and its outbox row in one transaction'
+    outbox -> db 'Polls unpublished outbox rows and marks them sent'
+    consumer -> db 'Records the applied paymentId, then advances the order'
+  }
+
+  // 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. 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'
+    }
+  }
+  // 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.
+  marketplace.orderService.api -> marketplace.identityService 'Calls introspectToken' {
+    metadata {
+      op 'introspectToken'
+    }
+  }
+  marketplace.orderService.outbox -> kafka.orderEvents 'Publishes OrderPlaced' {
+    metadata {
+      publishes 'order.OrderPlaced'
+    }
+  }
+  // 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. 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 -> marketplace.orderService.consumer 'PaymentAuthorized advances the order' {
+    metadata {
+      consumes 'payment.PaymentAuthorized'
+    }
+  }
+}
+
+// Views are the LikeC4 renderer's, never loam's — no check reads this block. Scoped
+// 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 marketplace.orderService {
+    title 'order-service — containers, its store, and what it reaches'
+    include *
+    include marketplace.paymentService, marketplace.identityService, kafka, kafka.*
+  }
+}