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

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.*
+  }
+}

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

@@ -0,0 +1,257 @@
+# The HTTP contract. Written by an agent from the `loam adopt` brief, then curated;
+# forward-flow changes are authored in a feature's specs/order-service/openapi.yaml
+# and merged here by `loam archive`.
+#
+# `operationId` is the token the whole spine joins on: a landscape edge names it in
+# `metadata { op }`, a requirement names it on an `Operations:` line, and it is
+# defined here. loam reads only the eight HTTP methods of a path item, so an id
+# tucked into a vendor extension does not exist — a phantom id would mask a contract
+# break rather than declare an operation.
+openapi: 3.1.0
+info:
+  title: order-service
+  version: "2.0"
+  description: Order placement, retrieval and cancellation for the marketplace checkout.
+
+paths:
+  /orders:
+    post:
+      operationId: createOrder
+      summary: Place an order
+      # The idempotency key is part of the contract, not an implementation detail:
+      # ARCH-ORD-IDEMPOTENCY promises a replay of this header returns the first
+      # order, and a promise a caller cannot see is a promise nobody can rely on.
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          description: Caller-generated key; a repeat replays the first response.
+          schema:
+            type: string
+            maxLength: 64
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOrderRequest'
+      # Every operation needs at least one response declaring a schema, or
+      # `openapi.response-undescribed` says the contract names the operation and
+      # nothing about what it returns. And every exact 4xx/5xx below has to be
+      # reachable from a scenario of a requirement whose `Operations:` names this
+      # operation — 409 is written as a scenario in spec.md's ORD-PLACE, not as a
+      # sentence about refusals, or `api.response-ungoverned` fires.
+      responses:
+        "201":
+          description: The order was accepted and is awaiting payment.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        "409":
+          description: The idempotency key was already used for a different basket.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+  /orders/{id}:
+    get:
+      operationId: getOrder
+      summary: Read an order
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: The order as it currently stands.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        "404":
+          description: No order with that id was ever placed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+  /orders/{id}/cancel:
+    post:
+      operationId: cancelOrder
+      summary: Cancel an order
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: The order is cancelled.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+        "409":
+          description: The order has already been handed to fulfilment.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+
+  /v1/orders:
+    post:
+      operationId: createOrderV1
+      summary: Place an order (v1, legacy)
+      description: >-
+        Superseded by createOrder. Takes a flat basket, assumes EUR and accepts no
+        idempotency key, so a replayed import places a second order. One caller left:
+        the partner batch importer.
+      # This one flag is the whole lifecycle signal on the spine. loam reads the
+      # standard per-operation `deprecated` and turns it into two warnings: every
+      # landscape edge whose `metadata { op }` names this operation gets
+      # `spine.op-deprecated` (the contract holds — the CONSUMER should be migrating,
+      # counted per inbound edge), and the requirement that governs only deprecated
+      # operations gets `api.requirement-deprecated` once — ORD-PLACE-V1 in spec.md,
+      # which is the demonstration this example ships. Deprecation is the first step
+      # of a removal; the last one is FEAT-112, which retires this path and method
+      # with an `x-loam-remove: true` marker in its own openapi delta plus a REMOVED
+      # requirement naming createOrderV1. Until that feature archives the operation is
+      # live, and deleting it here would break the importer today.
+      deprecated: true
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOrderV1Request'
+      responses:
+        "201":
+          description: The order was accepted.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderV1'
+
+# Every schema lives in this document. An external `$ref` is out of scope for the
+# reader and for the merge alike, and an internal one that resolves to nothing is
+# `openapi.ref-unresolved` — the operation validates while its payload is silently
+# absent, which is exactly the shape that reads as a complete contract and is not one.
+components:
+  schemas:
+    CreateOrderRequest:
+      type: object
+      required: [customerId, currency, lines]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        lines:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/OrderLine'
+
+    CreateOrderV1Request:
+      type: object
+      description: The v1 shape — no currency, no idempotency key.
+      required: [customer, items]
+      properties:
+        customer:
+          type: string
+        items:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [sku, qty, unitPrice]
+            properties:
+              sku:
+                type: string
+              qty:
+                type: integer
+                minimum: 1
+              unitPrice:
+                type: integer
+                description: minor units, assumed EUR
+
+    OrderLine:
+      type: object
+      required: [sku, quantity, unitAmount]
+      properties:
+        sku:
+          type: string
+        quantity:
+          type: integer
+          minimum: 1
+        unitAmount:
+          type: integer
+          description: minor units
+
+    Order:
+      type: object
+      required: [orderId, customerId, state, currency, totalAmount, lines]
+      properties:
+        orderId:
+          type: string
+          format: uuid
+        customerId:
+          type: string
+          format: uuid
+        state:
+          type: string
+          description: The lifecycle state ORD-PLACE, ORD-CANCEL and ORD-ON-AUTHORIZED move between.
+          enum: [awaiting_payment, confirmed, fulfilling, cancelled]
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+        totalAmount:
+          type: integer
+          description: minor units
+        lines:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderLine'
+        placedAt:
+          type: string
+          format: date-time
+
+    OrderV1:
+      type: object
+      description: The v1 response — a flatter Order, kept for the one remaining caller.
+      required: [id, status, total]
+      properties:
+        id:
+          type: string
+        status:
+          type: string
+        total:
+          type: integer
+          description: minor units, EUR
+
+    Problem:
+      type: object
+      description: RFC 9457 problem details, the one refusal shape every 4xx here uses.
+      required: [type, title, status]
+      properties:
+        type:
+          type: string
+          format: uri
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+        idempotencyKey:
+          type: string
+          description: Present on the createOrder 409, naming the key that conflicted.

package/examples/docs/services/order-service/runbook.md

@@ -0,0 +1,62 @@
+---
+service: order-service
+status: draft
+owner: orders-team
+---
+
+# order-service — runbook
+
+Nothing in this file is read by a check: `loam list` tracks that a runbook exists and stops
+there. It is here because the two incidents below are the ones the architecture in
+`arch.spec.md` makes possible, and the person paged at 03:00 needs the consequence spelled out,
+not the requirement id.
+
+## Deploy
+- Pipeline: `.gitlab-ci.yml` -> `deploy:prod` (manual gate). Rolling, one pod at a time.
+- Config: `application.yml`; secrets via Vault path `secret/order-service`.
+- The outbox relay and the payment-consumer ship in the same image as the API and are switched
+  on per deployment (`ORDER_RELAY_ENABLED`, `ORDER_CONSUMER_ENABLED`). Scaling the API to zero
+  therefore stops publishing and consuming too — check both flags before assuming a broker
+  fault.
+
+## Health
+- Liveness: `GET /actuator/health/liveness`
+- Readiness: `GET /actuator/health/readiness` — checks the database and the kafka connection.
+  It deliberately does NOT check payment-service: a payment-service outage must show up as
+  failed placements and a page, not as every order-service pod dropping out of the load
+  balancer at once.
+
+## Common incidents
+
+### Placement failures {#placement-failures}
+`order_placement_failures` is paging, so more than 2% of `POST /orders` is returning 5xx.
+
+1. Look at `authorizePayment` from this side first — the usual cause is payment-service, and
+   `order_placement_latency_p95_ms` rising before the error rate is the signature.
+2. If payment-service is healthy, check the database connection pool: placement writes the
+   order, its idempotency key and its outbox row in one transaction, so pool exhaustion fails
+   the whole placement rather than degrading it.
+3. Do NOT drain the queue of retries by hand. Every accepted placement carries an
+   `Idempotency-Key`; callers retrying is the designed path and a replay returns the first
+   order.
+
+### Outbox backlog
+`OrderPlaced` events stop arriving while orders keep being placed — notification-service goes
+quiet and nothing else looks wrong, because placements are still committing.
+
+1. Check the `order_outbox_pending` gauge and the relay's lag against `order.events.v1`.
+2. If kafka is unreachable, there is nothing to fix here: the relay retries and the backlog
+   drains on its own once the broker returns. Orders are safe — that is the whole point of
+   writing the event in the placement transaction.
+3. If kafka is healthy and the relay is stuck, restart it. Republishing is safe: the relay
+   promises at-least-once, consumers deduplicate, and a row published twice is a scenario
+   ARCH-ORD-OUTBOX already covers.
+4. Never delete outbox rows to clear a backlog. A deleted row is an order the fleet was never
+   told about, and nothing downstream will ever notice.
+
+## Escalation
+- On-call channel: `#orders-oncall`; paging rotation `orders-oncall`.
+- Payment authorization problems escalate to `#payments-oncall` — order-service orchestrates
+  the payment (`adrs/0001-orchestrated-order-lifecycle.md`) but owns none of it.
+- Broker problems escalate to the platform team; kafka is `#external #platform` in the
+  landscape and nobody in this fleet operates it.