@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

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

@@ -0,0 +1,127 @@
+---
+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 — `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.
+
+## 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: orderService.db, orderService.domain -> 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: orderService.outbox, 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: orderService.consumer, kafka.paymentEvents -> 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,108 @@
+# 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 would read it as a contract
+# with no messages rather than as a mis-parsed one.
+#
+# 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,138 @@
+// order-service's own C4 — the model behind `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
+}
+
+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'
+    }
+
+    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.
+    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, 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).
+    db = database 'db' {
+      description 'Orders, idempotency keys, the applied-payment ledger and the outbox table'
+      technology 'PostgreSQL'
+    }
+
+    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 `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' {
+    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.
+  orderService.api -> identityService 'Calls introspectToken' {
+    metadata {
+      op 'introspectToken'
+    }
+  }
+  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 -> 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 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.
+views {
+  view order_service of orderService {
+    title 'order-service — containers, its store, and what it reaches'
+    include *
+    include paymentService, identityService, kafka, kafka.*
+  }
+}