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

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`.

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

@@ -0,0 +1,88 @@
+---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/
+---
+
+# payment-service
+
+Owns payment authorization and capture. This is the **living spec** — the complete current
+state. Feature deltas (ADDED/MODIFIED/REMOVED requirements) merge in here on `loam archive`;
+`features/archive/` keeps every one of those deltas, so "which change introduced this
+requirement" stays a search rather than a record somebody has to maintain.
+
+## Requirements
+
+### Requirement: Authorize a payment
+
+Requirement-ID: PAY-AUTHORIZE
+The service SHALL reserve funds for an order before capture, and SHALL treat an authorization
+request as idempotent by order id so that a caller's timeout-and-retry never reserves twice.
+
+Operations: authorizePayment
+Publishes: payment.PaymentAuthorized
+Realizes: checkout#CHECKOUT-CHARGE-ONCE
+
+#### Scenario: Successful authorization
+- **Given** an order with a valid payment method
+- **When** authorization is requested
+- **Then** funds are reserved and a `PaymentAuthorized` event is emitted
+
+#### Scenario: A retry of the same authorization returns the first result
+- **Given** an authorization already reserved for order "A-1"
+- **When** the same request arrives again after a caller timeout
+- **Then** the original authorization is returned and no second reservation is made
+
+#### Scenario: A second authorization for the same order with a different amount is refused
+- **Given** an authorization already reserved for order "A-1" of 100.00 USD
+- **When** an authorization of 120.00 USD is requested for the same order
+- **Then** the request is refused with 409 and the first reservation stands
+
+### Requirement: Capture an authorized payment
+
+Requirement-ID: PAY-CAPTURE
+The service SHALL settle a previously authorized payment, and SHALL refuse to capture a payment
+it never authorized.
+
+Operations: capturePayment
+Publishes: payment.PaymentCaptured
+Requires: service/payments:capture
+
+#### Scenario: Capture an authorized payment
+- **Given** an authorized payment
+- **When** capture is requested
+- **Then** the payment is settled and a `PaymentCaptured` event is emitted
+
+#### Scenario: Capturing an unknown payment is refused
+- **Given** a payment id no authorization ever created
+- **When** capture is requested for it
+- **Then** the request is refused with 404 and nothing is settled
+
+### Requirement: Refund a captured payment
+
+Requirement-ID: PAY-REFUND
+The service SHALL return captured funds to the customer's payment method, SHALL reconcile the
+refund against the acquirer before reporting it complete, and SHALL refuse a second refund of a
+payment it has already refunded.
+
+Operations: refundPayment
+Publishes: payment.PaymentRefunded
+Requires: user/payments:refund
+
+#### Scenario: Refund a captured payment in full
+- **Given** a captured payment of 100.00 USD
+- **When** a refund is requested for it
+- **Then** 100.00 USD is returned to the customer's payment method
+- **And** the payment is recorded as refunded
+
+#### Scenario: A second refund of the same payment is refused
+- **Given** a payment already refunded in full
+- **When** a refund is requested for it again
+- **Then** the request is refused with 409 and no second refund is issued
+
+#### Scenario: The refund is announced only after the acquirer reconciles
+- **Given** a refund accepted by the acquirer but not yet reconciled
+- **When** the reconciliation completes
+- **Then** `payment.PaymentRefunded` is published exactly once for that payment

package/examples/docs/services/platform/identity-service/adrs/0001-token-introspection-over-local-validation.md

@@ -0,0 +1,60 @@
+---
+id: ADR-identity-service-0001
+status: accepted
+date: 2026-06-02
+service: identity-service
+---
+
+# 1. Introspect tokens centrally instead of validating them locally
+
+## Context
+Every service in the fleet has to decide whether a caller's token is good. The
+original answer was `GET /tokens/{token}/valid` (`validateToken`): a boolean, cheap
+to call, and cheap to cache — which is precisely what made it wrong.
+
+The endpoint answered from the token's signature and expiry, so it could only ever
+say "this was issued by us and has not expired yet". It could not say "this client
+was revoked eleven minutes ago". A revoked client therefore kept transacting until
+its token's natural expiry, and lengthening token lifetimes — the obvious fix for the
+load this endpoint put on the key store — made the revocation window longer in exact
+proportion.
+
+The boolean was also a dead end for authorization: a caller that needs the subject
+and the scopes has to fetch them somewhere, and every consumer had begun decoding the
+token itself to get them. Two services were already trusting claims they had not
+verified.
+
+## Decision
+`POST /tokens/introspect` (`introspectToken`) is the single answer, in the shape of
+RFC 7662: it returns `active` computed from **revocation state**, together with the
+subject and scopes, and an unknown, expired or revoked token is `{"active": false}`
+with a 200 rather than a 4xx — the caller asked a question and got an answer.
+
+`validateToken` is marked `deprecated: true` in `openapi.yaml` and keeps working. Its
+verdict is now computed the same way as introspection's, so the two can never
+disagree; only its response shape stays frozen.
+
+Introspection is gated on `service/tokens:introspect` and served from a short-TTL
+cache. Both obligations are written down where a test can be generated from them —
+`IDN-INTROSPECT` in `spec.md` for the permission, `ARCH-INTROSPECT-CACHE` in
+`arch.spec.md` for the cache's TTL, its invalidation on revocation, and its fallback.
+
+## Consequences
+- Revocation propagates within the cache TTL instead of within a token lifetime.
+- Every consumer now makes a network call where it used to decode locally, which is
+  why the cache and its single-flight behaviour are architecture requirements rather
+  than an implementation detail; the stampede failure mode is in `runbook.md`.
+- `validateToken` is deprecated rather than deleted, and that is a deliberate,
+  visible state rather than a decision postponed. payment-service still calls it —
+  the landscape edge `paymentService -> identityService` carries
+  `metadata { op 'validateToken' }` — so deleting the operation would break a
+  consumer with nothing having proposed the break. Instead the flag makes the
+  migration legible to `loam validate`: `spine.op-deprecated` names the consumer that
+  has not moved, and `api.requirement-deprecated` names `IDN-VALIDATE-LEGACY` as
+  behaviour on its way out. Both warnings stay until the migration is finished, and
+  they are how anyone can see it is not.
+- Retirement is an explicit change, not a cleanup: a feature delta carries
+  `x-loam-remove: true` inside the operation in
+  `features/<FEAT>/specs/identity-service/openapi.yaml` plus a `REMOVED` requirement
+  naming `validateToken`, and `loam archive` deletes the operation and the
+  requirement together. That is the step that ends this ADR's transitional state.