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

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

@@ -0,0 +1,134 @@
+---
+service: order-service
+status: draft
+owner: orders-team
+sources:
+  - src/main/kotlin/
+---
+
+# order-service
+
+Owns the order lifecycle — placement, the payment it orchestrates, and cancellation. This is
+the **living spec**: the complete current state, not a changelog. Feature deltas
+(`## ADDED|MODIFIED|REMOVED Requirements`) merge in here on `loam archive`, so what is written
+below is always what the service promises today.
+
+Three join lines carry the whole file into the rest of the docs, and each is graded:
+`Operations:` names operationIds from `openapi.yaml` (an operation nobody names is
+`api.ungoverned`; a name nothing defines is `spec-api.op-undefined`), `Publishes:` / `Consumes:`
+name messages `asyncapi.yaml` declares an `action: send` / `action: receive` for
+(`spec-event.message-undefined` otherwise), and `Requires:` names a pair
+`architecture/permissions.yaml` declares (`permissions.unknown` otherwise). The architectural
+obligations behind these promises — idempotency, the outbox, the dedupe ledger, the alerts —
+are not here; they live in `arch.spec.md`, which is a separate requirement namespace.
+
+## Requirements
+
+### Requirement: Place an order
+
+Requirement-ID: ORD-PLACE
+The service SHALL accept an order for a customer's basket, obtain a payment authorization from
+payment-service before acknowledging it, and announce the accepted order to the fleet. The
+authorization answers in band — `authorizePayment` returns the reservation, so nothing is
+acknowledged on a card nobody has reserved. The order is still placed in state
+`awaiting_payment`: what clears that state is `payment.PaymentAuthorized`, and the requirement
+that acts on it is ORD-ON-AUTHORIZED.
+
+Operations: createOrder
+Publishes: order.OrderPlaced
+Realizes: checkout#CHECKOUT-CHARGE-ONCE
+
+#### Scenario: A basket becomes an order
+- **Given** a customer with a basket of two lines and a valid payment method
+- **When** `createOrder` is called with a fresh `Idempotency-Key`
+- **Then** the order is stored in state `awaiting_payment`
+- **And** `order.OrderPlaced` is announced with the order id, the customer id and the total
+
+#### Scenario: A reused idempotency key with a different basket is refused
+- **Given** an order already placed under `Idempotency-Key` "ik-8842"
+- **When** `createOrder` is called again with that key and a basket that differs from the first
+- **Then** the service refuses with 409 and names the conflicting key
+- **And** the first order is left exactly as it was placed
+
+### Requirement: Read an order
+
+Requirement-ID: ORD-READ
+The service SHALL return an order's current state to its owner, so checkout-web's status page
+reads the order rather than inferring it from payment events it cannot see.
+
+Operations: getOrder
+
+#### Scenario: An order is read back
+- **Given** an order placed for customer "cus-31"
+- **When** `getOrder` is called for that order id
+- **Then** the response carries the order's state, its lines and its total
+
+#### Scenario: An order id that was never issued
+- **Given** an order id no placement ever produced
+- **When** `getOrder` is called for it
+- **Then** the service answers 404 rather than an empty order
+
+### Requirement: Cancel an order
+
+Requirement-ID: ORD-CANCEL
+The service SHALL let an order be cancelled while nothing irreversible has happened to it, SHALL
+return the customer's money when the order's payment was already captured, and SHALL refuse once
+the order has been handed to fulfilment — a cancellation after that point is a return, which
+this service does not model.
+
+Operations: cancelOrder
+Requires: user/orders:cancel
+
+#### Scenario: A customer cancels before fulfilment
+- **Given** an order in state `awaiting_payment`
+- **When** its owner calls `cancelOrder`
+- **Then** the order moves to `cancelled` and no further payment work is started
+
+#### Scenario: Cancelling a confirmed order refunds its captured payment
+- **Given** an order in state `confirmed` whose payment was captured
+- **When** its owner calls `cancelOrder`
+- **Then** `refundPayment` is called on payment-service for that payment
+- **And** the order moves to `cancelled` only once the refund is recorded
+
+#### Scenario: An order already handed to fulfilment cannot be cancelled
+- **Given** an order in state `fulfilling`
+- **When** `cancelOrder` is called for it
+- **Then** the service refuses with 409 and the order stays `fulfilling`
+
+### Requirement: Accept an order through the v1 API
+
+Requirement-ID: ORD-PLACE-V1
+The service SHALL keep accepting orders on the v1 endpoint for as long as the partner batch
+importer still calls it. This is legacy: v1 takes a flat basket with no idempotency key and no
+currency, so a retried import creates a second order and every total is assumed to be EUR. It
+is kept alive for one remaining caller and nothing new may be built on it — FEAT-112 retires
+the endpoint once that importer has moved to `createOrder`.
+
+Operations: createOrderV1
+
+#### Scenario: The partner batch importer places an order on v1
+- **Given** the partner importer, the only caller left on v1
+- **When** it posts a flat basket to `createOrderV1`
+- **Then** an order is placed exactly as `createOrder` places one, with the currency defaulted to EUR
+- **And** no idempotency key is recorded, so a replayed import would place a second order
+
+### Requirement: Advance an order when payment is authorized
+
+Requirement-ID: ORD-ON-AUTHORIZED
+The service SHALL move an order to `confirmed` when payment-service announces that the order's
+payment was authorized, and SHALL leave an order that is no longer awaiting payment untouched.
+The authorization decision belongs to payment-service; what this requirement owns is the order
+state that follows from it.
+
+Consumes: payment.PaymentAuthorized
+
+#### Scenario: Authorization confirms the order
+- **Given** an order in state `awaiting_payment`
+- **When** `payment.PaymentAuthorized` arrives naming that order
+- **Then** the order moves to `confirmed` and becomes eligible for fulfilment
+
+#### Scenario: Authorization arrives for an order the customer already cancelled
+- **Given** an order cancelled while its authorization was still in flight
+- **When** `payment.PaymentAuthorized` arrives naming that order
+- **Then** the order stays `cancelled` and is never confirmed
+- **And** the authorization is left to expire uncaptured, because this service never captures

package/examples/docs/services/payment-service/adrs/0001-payments-outbox.md

@@ -0,0 +1,18 @@
+---
+id: ADR-payment-service-0001
+status: accepted
+date: 2026-05-10
+service: payment-service
+---
+
+# 1. Use a transactional outbox for payment events
+
+## Context
+Payment state changes must publish events without dual-write races between the DB and Kafka.
+
+## Decision
+Persist events to an outbox table in the same transaction as the state change; a relay publishes to Kafka.
+
+## Consequences
+- At-least-once delivery with idempotent consumers.
+- Extra outbox table and relay process to operate (see `runbook.md`).

package/examples/docs/services/payment-service/adrs/0002-idempotency-keys-on-authorization.md

@@ -0,0 +1,27 @@
+---
+id: ADR-payment-service-0002
+status: accepted
+date: 2026-06-18
+service: payment-service
+---
+
+# 2. Make authorization idempotent by order id
+
+## Context
+Callers retry on timeout, and a timed-out authorization is an unknown outcome rather than a
+failure: the funds may already be reserved at the acquirer. Retrying without an identity for the
+request reserves twice, and the second reservation is invisible until a customer complains.
+
+## Decision
+`authorizePayment` is idempotent by order id. A repeat of a request already recorded returns the
+original authorization; a request naming the same order with a *different* amount is refused
+with `409` rather than treated as a new attempt, because the two cannot both be what the caller
+meant. The same idempotency key travels to the acquirer, so the reconciliation job can replay a
+timed-out call safely.
+
+## Consequences
+- Retries are safe, and `order-service` may retry `authorizePayment` without a compensating flow.
+- The refusal path is a real branch of the contract, so it is written as a scenario rather than
+  as prose — `api.response-ungoverned` is what asks for it.
+- An order whose amount legitimately changes needs a new order id, which the order lifecycle in
+  `services/order-service/` already gives it.

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

@@ -0,0 +1,73 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/
+---
+
+# payment-service — architecture spec
+
+The **living architecture spec**: the obligations the business spec never carries —
+the transactional outbox, retries, metrics and alerts. Same grammar as spec.md;
+each requirement's `Covers:` line names the C4 elements, edges and health signals
+its scenarios exercise, and `loam validate` checks every entry resolves
+(`covers.unknown`) and every declared alert/SLI is covered (`health.uncovered`).
+
+An edge entry resolves by exact element id **or** by the service an endpoint stands for, which
+is why the entries below name `payment-service` rather than `marketplace.paymentService`: the
+landscape draws this service inside a grouping element, and a `Covers:` line written against a
+group path would have to be rewritten the day somebody moves the box.
+
+## Requirements
+
+### Requirement: Events leave through the transactional outbox
+
+Requirement-ID: ARCH-PAY-OUTBOX
+The service SHALL write a domain event and the state change it reports in one
+database transaction, published to kafka by an outbox relay — never a dual write.
+
+Covers: paymentService.outbox, payment-service -> kafka.paymentEvents
+Publishes: payment.PaymentAuthorized, payment.PaymentCaptured
+
+#### Scenario: Broker down at commit time
+- **Given** an authorized payment whose `PaymentAuthorized` event is still in the outbox
+- **When** kafka is unavailable
+- **Then** the payment state stays committed and the event is published once kafka returns
+
+#### Scenario: The relay redelivers rather than dropping
+- **Given** an outbox row the relay published but could not mark as sent
+- **When** the relay restarts
+- **Then** the event is published a second time and consumers deduplicate on `paymentId`
+
+### Requirement: Card authorization survives an acquirer timeout
+
+Requirement-ID: ARCH-PAY-ACQUIRER
+The service SHALL send an idempotency key with every acquirer call and SHALL reconcile a
+timed-out authorization against the acquirer before deciding it failed — a timeout is an
+unknown outcome, never a decline.
+
+Covers: payment-service -> stripe
+
+#### Scenario: The acquirer times out and the money was in fact reserved
+- **Given** an authorization request that times out at the acquirer
+- **When** the reconciliation job replays the request with the same idempotency key
+- **Then** the acquirer returns the original authorization and no second charge exists
+
+### Requirement: Authorization health is measured and paged
+
+Requirement-ID: ARCH-PAY-HEALTH
+The service SHALL export its availability and latency SLIs and page on a sustained
+authorization error rate.
+
+Covers: sli:availability, sli:latency_p99_ms, alert:payment_authorization_5xx
+
+#### Scenario: Error-rate alert fires
+- **Given** more than 1% of authorization requests fail over five minutes
+- **When** the alert rules are evaluated
+- **Then** `payment_authorization_5xx` pages the payments on-call
+
+#### Scenario: SLIs are exported
+- **Given** the service is serving traffic
+- **When** its metrics endpoint is scraped
+- **Then** `availability` and `latency_p99_ms` report values against their SLOs

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

@@ -0,0 +1,130 @@
+# The async contract — the messages this service puts on the bus.
+#
+# AsyncAPI 3.0 only. Its operations are named top-level objects carrying
+# `action: send|receive`, which is what makes a message's 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.
+#
+# loam reads message NAMES and the `action` of the operation carrying them.
+# It never joins on anything inside `payload` — the one look inside is a
+# presence probe (a payload declaring no shape at all warns, a non-JSON
+# `schemaFormat` is skipped) — which is what keeps swapping JSON Schema for
+# Avro a `schemaFormat` line here rather than a change in loam.
+#
+# The name is the spine: the landscape edge's `metadata { publishes }`, the
+# requirement's `Publishes:` line and `name` below are one name spelled three
+# times, and they must be identical.
+asyncapi: 3.0.0
+info:
+  title: payment-service events
+  version: "1.0"
+
+channels:
+  paymentEvents:
+    address: payment.events.v1
+    description: Payment lifecycle events, published by the outbox relay
+    messages:
+      PaymentAuthorized:
+        $ref: "#/components/messages/PaymentAuthorized"
+      PaymentCaptured:
+        $ref: "#/components/messages/PaymentCaptured"
+      PaymentRefunded:
+        $ref: "#/components/messages/PaymentRefunded"
+
+operations:
+  sendPaymentAuthorized:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentAuthorized'
+  sendPaymentCaptured:
+    action: send
+    channel:
+      $ref: '#/channels/paymentEvents'
+    messages:
+      - $ref: '#/channels/paymentEvents/messages/PaymentCaptured'
+  sendPaymentRefunded:
+    action: send
+    channel:
+      $ref: "#/channels/paymentEvents"
+    messages:
+      - $ref: "#/channels/paymentEvents/messages/PaymentRefunded"
+
+components:
+  messages:
+    PaymentAuthorized:
+      # Namespaced by the domain that owns it. One message has exactly one
+      # producer: two services declaring they send this name is
+      # `asyncapi.message-contested`, and then which contract a consumer reads
+      # is a coin flip.
+      name: payment.PaymentAuthorized
+      title: Payment authorized
+      # JSON Schema today, because this fleet runs no schema registry. An Avro
+      # record here later needs a `schemaFormat:` line and no other change:
+      # everything below is opaque to loam.
+      payload:
+        type: object
+        required: [ paymentId, orderId, amount, currency, authorizedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          amount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          authorizedAt:
+            type: string
+            format: date-time
+    PaymentCaptured:
+      name: payment.PaymentCaptured
+      title: Payment captured
+      payload:
+        type: object
+        required: [ paymentId, orderId, capturedAmount, currency, capturedAt ]
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          capturedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: '^[A-Z]{3}$'
+          capturedAt:
+            type: string
+            format: date-time
+    PaymentRefunded:
+      name: payment.PaymentRefunded
+      title: Payment refunded
+      payload:
+        type: object
+        required:
+          - paymentId
+          - orderId
+          - refundedAmount
+          - currency
+          - refundedAt
+        properties:
+          paymentId:
+            type: string
+            format: uuid
+          orderId:
+            type: string
+          refundedAmount:
+            type: integer
+            description: minor units
+          currency:
+            type: string
+            pattern: ^[A-Z]{3}$
+          refundedAt:
+            type: string
+            format: date-time

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

@@ -0,0 +1,39 @@
+# Service health model. Targets are authored; the dependency graph comes from
+# C4 — this service's own model.likec4, which carries everything the service
+# touches. planned: `loam health` composes these across the fleet -> cascade /
+# blast-radius.
+#
+# `loam validate` reads only ids here: the `name` of each SLI and alert (every
+# declared id wants a covering requirement in arch.spec.md, or
+# `health.uncovered` says nothing tests it), and each dependency's `service:`
+# id, which must resolve in model.likec4 (`health.dependency-unmodelled`
+# otherwise). A dependency a feature in flight introduces arrives with that
+# feature — it is not a dependency of the living service yet, which is why
+# payment-split-service is absent from the list below while FEAT-101 is open.
+#
+# Everything else — the queries, the thresholds, the criticality words — is
+# authored prose no check reads. That is deliberate: loam grades whether the
+# signal is tested, never whether the threshold is right.
+service: payment-service
+status: draft
+slis:
+  - name: availability
+    query: "sum(rate(http_requests_total{code!~'5..'}[5m])) / sum(rate(http_requests_total[5m]))"
+    slo: 0.999
+  - name: latency_p99_ms
+    query: "histogram_quantile(0.99, http_request_duration_seconds_bucket)"
+    slo: 300
+alerts:
+  - name: payment_authorization_5xx
+    expr: "rate(http_requests_total{path='/payments',code=~'5..'}[5m]) > 0.01"
+    page: payments-oncall
+checks:
+  liveness: GET /actuator/health/liveness
+  readiness: GET /actuator/health/readiness
+dependencies:
+  - service: kafka
+    criticality: critical        # the outbox holds, but nothing leaves the service
+  - service: stripe
+    criticality: critical        # no acquirer, no authorization
+  - service: identity-service
+    criticality: degradable      # cached introspection decisions carry a request

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

@@ -0,0 +1,67 @@
+// Per-service C4. Written by an agent from the `loam adopt` brief, then curated.
+//
+// loam parses every `.likec4` file ALONE, so this document declares its own
+// `specification` block; a renderer handed the whole tree at once would merge
+// them and call every declaration a duplicate, which is what
+// `likec4.config.json` scopes the root project to `architecture/` for.
+specification {
+  element softwareSystem
+  element container
+  element database
+}
+
+model {
+  paymentService = softwareSystem 'payment-service' {
+    description 'Owns payment authorization/capture'
+
+    api = container 'api' {
+      description 'REST API'
+      technology 'Spring Boot'
+    }
+    domain = container 'domain' {
+      description 'Payment domain logic'
+      technology 'Java'
+    }
+    // The store is a container of THIS service, not a fleet-level peer. Drawn
+    // in the landscape it would be a system in its own right, available to be
+    // depended on — which is the claim `landscape.datastore-private` exists to
+    // refuse when only one service reaches it.
+    db = database 'db' {
+      description 'Payments store'
+      technology 'PostgreSQL'
+    }
+    outbox = database 'outbox' {
+      description 'Transactional outbox drained by the relay'
+      technology 'PostgreSQL'
+    }
+
+    api -> domain 'Uses'
+    domain -> db 'Reads/writes'
+    domain -> outbox 'Appends events in the state-change transaction'
+  }
+
+  // The service model carries everything the service touches — cross-boundary
+  // dependencies included, drawn with the edge the service actually has. The
+  // landscape carries only the boundary crossing; health.yaml's dependencies
+  // must resolve HERE (`health.dependency-unmodelled` otherwise), which is why
+  // all three of this service's declared dependencies appear below.
+  kafka = softwareSystem 'kafka' {
+    description 'Event backbone (platform)'
+  }
+  identityService = softwareSystem 'identity-service' {
+    description 'Token validation (degradable: cached decisions carry a request)'
+  }
+  stripe = softwareSystem 'stripe' {
+    description 'Card acquirer'
+  }
+
+  paymentService.outbox -> kafka 'Relay publishes payment events'
+  paymentService.domain -> identityService 'Validates the caller token'
+  paymentService.domain -> stripe 'Authorizes and captures cards'
+}
+
+views {
+  view payment_service of paymentService {
+    include *
+  }
+}

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

@@ -0,0 +1,151 @@
+# API contract. Written by an agent from the `loam adopt` brief; forward-flow authors changes
+# in the feature's own `specs/<svc>/openapi.yaml` delta and lets `loam archive` merge them here.
+#
+# Only the eight HTTP methods of a path item are read for operationIds — an id tucked inside a
+# vendor extension does not exist as far as the spine is concerned, because a phantom id would
+# mask a contract break. Two things are graded beyond form: every operation wants a response
+# with a schema (`openapi.response-undescribed` otherwise — a contract that names an operation
+# and says nothing about what it returns still sends the reader to the code), and every 4xx/5xx
+# it declares wants a scenario that reaches it (`api.response-ungoverned`).
+openapi: 3.1.0
+info:
+  title: payment-service
+  version: "1.0"
+paths:
+  /payments:
+    post:
+      operationId: authorizePayment
+      summary: Authorize a payment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthorizationRequest'
+      responses:
+        "201":
+          description: Authorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Payment'
+        "409":
+          description: A different authorization already exists for this order
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+  /payments/{id}/capture:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    post:
+      operationId: capturePayment
+      summary: Capture an authorized payment
+      responses:
+        "200":
+          description: Captured
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Capture'
+        "404":
+          description: No such authorized payment
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+  /payments/{id}/refund:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+    post:
+      operationId: refundPayment
+      summary: Refund a captured payment
+      responses:
+        "200":
+          description: Refunded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Refund"
+        "409":
+          description: The payment was already refunded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+
+components:
+  schemas:
+    AuthorizationRequest:
+      type: object
+      required: [ orderId, amount, currency ]
+      properties:
+        orderId:
+          type: string
+        amount:
+          type: integer
+          description: minor units
+        currency:
+          type: string
+          pattern: '^[A-Z]{3}$'
+    Payment:
+      type: object
+      required: [ paymentId, status ]
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [ authorized, declined ]
+    Capture:
+      type: object
+      required: [ paymentId, capturedAmount ]
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        capturedAmount:
+          type: integer
+          description: minor units
+    # RFC 9457. One shared shape for every refusal, so a client parses failures once —
+    # and so the 409 and 404 above declare a schema rather than a bare description.
+    Problem:
+      type: object
+      required: [ type, title, status ]
+      properties:
+        type:
+          type: string
+          format: uri
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+    Refund:
+      type: object
+      required:
+        - paymentId
+        - refundedAmount
+        - refundedAt
+      properties:
+        paymentId:
+          type: string
+          format: uuid
+        refundedAmount:
+          type: integer
+          description: minor units
+        refundedAt:
+          type: string
+          format: date-time

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

@@ -0,0 +1,37 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+---
+
+# payment-service — runbook
+
+Frontmatter here is read by nothing: `loam list` tracks that this file EXISTS, and no check
+grades a field in it. What is written above is a note to the next reader, not a claim loam will
+catch when it goes stale.
+
+## Deploy
+- Pipeline: `.gitlab-ci.yml` -> `deploy:prod` (manual gate).
+- Config: `application.yml`; secrets via Vault path `secret/payment-service`.
+
+## Health
+- Liveness: `GET /actuator/health/liveness`
+- Readiness: `GET /actuator/health/readiness` (checks db + kafka)
+- The SLIs and the alert are declared in `health.yaml`, and `arch.spec.md` carries the
+  requirement that says what each one is for. A signal nothing covers is `health.uncovered`.
+
+## Common incidents
+- **Outbox relay lag** -> events delayed, and every consumer downstream of `payment.events`
+  falls behind with it. Check the `outbox_pending` gauge; restart the relay. The payments
+  themselves are unaffected: the outbox is what makes the state change and its event one
+  transaction, so nothing is lost, only late.
+- **DB connection exhaustion** -> 503s. Check pool metrics; scale or fix a leak.
+- **Acquirer timeouts** -> authorizations in an unknown state. Do not retry by hand: the
+  reconciliation job replays with the original idempotency key, which is the only path that
+  cannot double-charge.
+- **identity-service unavailable** -> declared `degradable` in `health.yaml`: cached
+  introspection decisions carry requests for their remaining TTL, and authorization starts
+  failing closed once the cache empties.
+
+## Escalation
+On-call channel: `#payments-oncall`.