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

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.

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